CLI reference

The agentroute CLI is a small command-line companion to the SDK. You build and run agents locally with the Python SDK; the CLI is what you reach for to talk to the AgentRoute platform — authenticate once, then deploy an agent, list what you have running, and tail its logs.

The CLI and the SDK are separate packages

pip install agentroute gives you the SDK (from agentroute import Agent). The CLI ships as its own package, agentroute-cli, and installs the agentroute command. You can use the SDK without ever installing the CLI.

Install

The CLI is published as agentroute-cli and exposes a single entry point, agentroute.

pip install agentroute-cli

It requires Python 3.10 or newer. Verify the install with the global version flag:

agentroute --version

agentroute-cli 0.1.0

Running agentroute with no command prints a hint pointing you at --help, which lists every available subcommand.

Authentication

Every command that talks to the platform needs an API key. There are two ways to provide one, checked in this order:

The AGENTROUTE_API_KEY environment variable.
The ~/.agentroute/config file written by agentroute login.

If neither is present, the command exits with Error: Not logged in. Run 'agentroute login' first.

Logging in

agentroute login runs a device-style code exchange. It prints a URL, you open it in a browser, copy the code shown there, and paste it back into the prompt. The CLI exchanges that code for an API key and writes the key to ~/.agentroute/config.

$ 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

Under the hood, login POSTs the code to {AGENTROUTE_API_URL}/auth/exchange-code and stores the returned api_key. You only need to do this once per machine.

The config file

The config is a plain text file at ~/.agentroute/config with a single key=value line:

~/.agentroute/config

api_key=sk-agentroute-...

Because it holds a credential, keep it private. To sign out, delete the file:

rm ~/.agentroute/config

Environment variables

The CLI reads two environment variables.

Parameter	Type	Default	Description
`AGENTROUTE_API_KEY`	str	—	Your platform API key. When set, it takes precedence over the `~/.agentroute/config` file, which makes it the natural choice for CI and other non-interactive environments.
`AGENTROUTE_API_URL`	str	`https://api.agentroute.ai/v1`	Base URL for the platform API. Every command builds its requests from this value. Override it to point the CLI at a self-hosted or staging environment.

One key, two layers

The CLI key authenticates you to the AgentRoute platform (deploy, list, logs). It is unrelated to the model-provider key the SDK uses at runtime (AGENTROUTE_API_KEY / OPENROUTER_API_KEY for OpenRouter). The CLI reuses the AGENTROUTE_API_KEY name, so in a shell that runs both, a single value can serve both purposes.

Commands

Exchange a one-time code for an API key and save it locally.

deploy

Load an agent.py from a directory and push the agent to the platform.

list

Show your agents in a table with status, URL, and call count.

logs

Print or follow the logs for a deployed agent by name.

See the commands reference for the full flag list and example output of each.

Hosted deployment is still being finalized

The current deploy command predates the v1.1 SDK: it probes legacy attributes on your agent object and calls a deploy method the current Agent does not expose, so agentroute deploy will not yet push a v1.1 agent end to end. Today the SDK is built for running agents in your own process. Track hosted deployment on the platform roadmap.

Next steps

Command reference

Flags, arguments, and output for login, deploy, list, and logs.

Build an agent

The SDK Agent class you run locally before reaching for the CLI.