Commands

The agentroute CLI is a small Typer app for authenticating, deploying, and operating agents against the AgentRoute platform. This page documents every command and flag exactly as they behave today.

All commands except login and --version require an API key. The CLI reads it from the AGENTROUTE_API_KEY environment variable, and falls back to the ~/.agentroute/config file written by agentroute login. If neither is present, the command exits with an error.

Note

Run agentroute --help (or agentroute COMMAND --help) at any time to see the same usage and flags described here, generated directly from the CLI.

Global options

These apply to the top-level agentroute command itself.

`--version`, `-v`

Print the CLI version and exit.

agentroute --version

$ agentroute --version
agentroute-cli 0.1.0

Parameter	Type	Default	Description
`--version`	flag	`false`	Aliased as `-v`. Prints the CLI version and exits immediately, before any subcommand runs.

Invoking agentroute with no command and no flags prints a short hint pointing you at --help.

Authenticate the CLI and save an API key to ~/.agentroute/config.

agentroute login

login prints the browser URL https://agentroute.ai/cli-auth, then prompts you to paste the code shown on that page. It exchanges the code by POSTing {"code": "..."} to AGENTROUTE_API_URL/auth/exchange-code, then writes the returned key to the config file as api_key=....

$ agentroute login
Login to AgentRoute
 
Visit: https://agentroute.ai/cli-auth
Copy the code shown on the page.
 
Enter the code: ABCD-1234
 
✓ Logged in successfully!
API key saved to /Users/you/.agentroute/config

Tip

Already have a key from the dashboard? You can skip login entirely by exporting AGENTROUTE_API_KEY in your shell. The same key works with the SDK — see resolve_model for how the SDK resolves credentials.

deploy

Deploy an agent defined in an agent.py file.

agentroute deploy [PATH]

deploy resolves PATH (default: the current directory), requires an agent.py there, imports that module, finds the agent object, prints its name, description, and skills, then calls the agent's deploy method and prints the resulting URL.

Parameter	Type	Default	Description
`PATH`	str	`.`	Directory containing `agent.py`. Defaults to the current directory.

$ agentroute deploy ./my-agent
Deploying from /Users/you/my-agent...
 
Agent: support-bot
Description: Answers billing questions
Skills: lookup_invoice, refund
 
Deploying...
✓ Deployed successfully!
URL: https://support-bot.agentroute.ai

Hosted deployment is being finalized

The current deploy command predates the v1.1 SDK. It probes legacy attributes (an agent skills map and a to_agent_card method) and calls a deploy() method that the current Agent class does not expose, so deploying a v1.1 agent will not succeed yet. Hosted deployment is still being built out — track progress on the platform roadmap. For now, run agents locally with Agent.run.

logs

Stream or fetch the logs for a deployed agent by name.

agentroute logs NAME [--follow] [--lines N]

logs issues a GET to AGENTROUTE_API_URL/agents/{name}/logs. Without --follow it prints the most recent entries with timestamps and color-coded levels; with --follow it streams new lines as they arrive.

Parameter	Type	Default	Description
`NAME`required	str	—	The agent name to fetch logs for. A `404` from the server prints `Agent '<name>' not found`.
`--follow`	flag	`false`	Aliased as `-f`. Stream logs in real time instead of returning a fixed batch. Disables the request timeout.
`--lines`	int	`50`	Aliased as `-n`. Number of recent log lines to request.

$ agentroute logs support-bot --lines 3
Logs for support-bot
 
2026-06-06T10:02:11Z INFO  agent started
2026-06-06T10:02:12Z INFO  handled request in 840ms
2026-06-06T10:02:19Z ERROR upstream model timeout

To tail logs live, add --follow:

agentroute logs support-bot --follow

list

List all of your deployed agents in a table.

agentroute list

list issues a GET to AGENTROUTE_API_URL/agents and renders a table with columns Name, Status, URL, and Calls. Status values are color-coded (active, deploying, error, stopped). If you have no agents yet, it prints a hint to deploy your first one.

$ agentroute list
                     My Agents
┏━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Name        ┃ Status ┃ URL                        ┃ Calls ┃
┡━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ support-bot │ active │ https://support-bot.age... │ 1,204 │
│ summarizer  │ active │ https://summarizer.age...  │   312 │
└─────────────┴────────┴────────────────────────────┴───────┘

Environment and config

The CLI reads two environment variables, plus a config file for stored credentials.

Parameter	Type	Default	Description
`AGENTROUTE_API_KEY`	str	`None`	Your API key. Takes precedence over the config file. Required by `deploy`, `logs`, and `list`.
`AGENTROUTE_API_URL`	str	`https://api.agentroute.ai/v1`	Base URL for all API calls. Override this to target a staging or self-hosted environment.

When AGENTROUTE_API_KEY is not set, the CLI reads ~/.agentroute/config and looks for a line of the form api_key=.... This file is created and overwritten by agentroute login:

~/.agentroute/config

api_key=ar_live_...

If neither the environment variable nor a config-file key is found, authenticated commands print Error: Not logged in. Run 'agentroute login' first. and exit with a non-zero status.

Note

The SDK and CLI share the same credential precedence (explicit value, then environment, then ~/.agentroute/config). One OpenRouter-style key set as AGENTROUTE_API_KEY works across the toolchain — see models for the full resolution order.

Next steps

CLI overview

Install the CLI and see the big picture.

Build an agent

The Agent you deploy is defined with the SDK.

Models and keys

How credentials and model strings resolve.

Platform roadmap

Where hosted deployment is headed.