CLI Reference
o2agentctl is your primary interface to the platform — every command below
works identically whether you're scripting it in CI or typing it by hand,
and every command supports --output json.
Global flags
| Flag | Default | Description |
|---|---|---|
--output | text | Output format: text or json |
--gateway-url | http://localhost:8000 | Gateway base URL |
--o2id-base-url | http://localhost:8080 | O2ID base URL |
--o2id-tenant | system | O2ID tenant slug |
--o2id-client-id | o2agentctl | The CLI's registered O2ID application ID |
o2agentctl bootstrap
Registers o2agentctl with an O2ID instance under a well-known, predictable
client ID — run this once per O2ID instance, logged in as an O2ID admin.
After this, o2agentctl login works with no extra flags:
o2agentctl bootstrap
Safe to run more than once — an existing registration is left untouched.
o2agentctl login
Logs in via O2ID, opening your browser for authentication:
o2agentctl login
Credentials are saved to ~/.o2agent/credentials.json and reused by every
other command.
o2agentctl agent create
Registers a new agent, minting its identity in the same step:
o2agentctl agent create --name <name> [--scopes <comma-separated-scopes>]
o2agentctl agent list
Lists every agent you have access to:
o2agentctl agent list
o2agentctl agent version create
Adds a new immutable version to an agent:
o2agentctl agent version create --agent <agent-id> \
--system-prompt "<prompt>" \
--model-provider <mock|openai-compatible> \
--model-name <model>
o2agentctl agent version list
Lists an agent's versions:
o2agentctl agent version list --agent <agent-id>
o2agentctl agent deploy
Promotes a version to be the agent's active deployment:
o2agentctl agent deploy --agent <agent-id> --version <version-id>
o2agentctl agent invoke
Invokes an agent's active deployment:
o2agentctl agent invoke --agent <agent-id> --input "<your input>"
o2agentctl trace tail
Shows the most recent execution traces:
o2agentctl trace tail
o2agentctl tui
Launches the interactive TUI — an agent list, an invoke playground, and a live trace tail — built on the same client as command mode:
o2agentctl tui