Metadata-Version: 2.4
Name: agent-gateway-cli
Version: 26.7.0
Summary: Generic terminal client for an online agent gateway
License-Expression: MIT
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agent-framework>=26.7.0
Requires-Dist: httpx>=0.27
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.8
Dynamic: license-file

# agent-gateway-cli

`agent-gateway-cli` is a terminal client for interacting with an online agent
gateway. It provides an interactive shell for authentication, sessions,
settings, and agent conversations.

The installed command is:

```text
agw
```

## Requirements

- Python 3.13 or newer
- Access to an agent gateway

## Install

Install the latest release from PyPI:

```bash
python -m pip install agent-gateway-cli
```

The package can also be installed from a local checkout:

```bash
python -m pip install .
```

## Initialize

Create the default configuration with the gateway URL:

```bash
agw --init https://gateway.example.com
```

This creates the configuration file only if it does not already exist. The
default location is:

- Unix-like systems: `~/.agent_gateway_cli.yaml`
- Windows: `%USERPROFILE%\.agent_gateway_cli.yaml`

If the file already exists, initialization fails without changing it.

To initialize a different file:

```bash
agw --config /path/to/cli.yaml --init https://gateway.example.com
```

On Windows PowerShell:

```powershell
agw --config C:\path\to\cli.yaml --init https://gateway.example.com
```

## Run

Start the interactive client:

```bash
agw
```

The client displays its version, then prompts for gateway credentials. Type
`help` in the shell to see available commands. Common commands include:

```text
auth login
auth logout
motd
session list
session show
session switch <session-id>
set
set streaming_enabled true
quit
```

Use `--config` to select a non-default configuration file:

```bash
agw --config /path/to/cli.yaml
```

The same path can be supplied through `AGF_CLI_CONFIG_PATH`.

## Configuration

The example configuration is available at
[`config/cli.yaml.example`](config/cli.yaml.example):

```yaml
base_url: https://gateway.example.com
settings_path: ~/.agent_gateway_cli.yaml
history_path: ~/.agent_gateway_cli_history
history_entries: 50
request_timeout: 120
```

Local settings are stored in `settings_path`. Command history is stored
separately in `history_path` and is limited to `history_entries` lines per
user. The default history limit is 50.

To disable the shell's friendly error recovery and allow interrupts and
exceptions to propagate:

```bash
agw --no-error-handling
```

## Package names

- PyPI distribution: `agent-gateway-cli`
- Python package: `agent_gateway_cli`
- Console command: `agw`

## License

This project is licensed under the [MIT License](LICENSE).
