Agno CLI

Scaffold, run, and connect an AgentOS from the terminal with the agno command.

agno create my-os
cd my-os
cp example.env .env   # fill in your secrets
agno up
agno connect

This quickstart assumes agno 2.7 or later is installed. The agno command scaffolds AgentOS projects, runs them with Docker Compose, connects your coding agents over MCP, and manages service-account tokens.

Every subcommand listed below accepts --json and emits one JSON document for command-level results after argument parsing succeeds. Typer usage errors exit with code 2, write diagnostics to stderr, and do not emit JSON.

Install

The CLI ships with the SDK, so installing agno 2.7 or later puts the agno command on your PATH.

pip install -U agno

The CLI is also published standalone as agnoctl. It depends on typer, rich, and httpx, plus tomli on Python versions below 3.11, so it runs on machines without the SDK:

uvx agnoctl connect

agno and agnoctl are the same CLI under two names.

Commands

Command	What it does	Guide
agno create <name>	Scaffold a project from a starter template	Create a project
agno connect	Connect coding agents to a running AgentOS over MCP	Connect your clients
agno disconnect	Remove AgentOS MCP entries from client configs	Connect your clients
agno up / down / restart	Run the project with Docker Compose	Operate your AgentOS
agno status	Show the discovered AgentOS and connected clients	Operate your AgentOS
agno tokens create / list / revoke	Manage service-account tokens	Manage tokens

How the CLI Finds Your AgentOS

status, tokens, and non-interactive connect runs need a running AgentOS. They resolve one target in this order:

Priority	Source	Example
1	--url flag	agno connect --url https://os.example.com
2	AGENTOS_URL environment variable	export AGENTOS_URL=https://os.example.com
3	AGENTOS_URL in a project env file	AGENTOS_URL=https://os.example.com in .env.production, then .env
4	Localhost probe	Ports 7777, 7778, 7779, 8000

The probe covers AgentOS.serve()’s default port (7777), common bump-up ports, and a bare uvicorn setup (8000). If your AgentOS runs on any other host or port, point the CLI at it with --url or AGENTOS_URL.

Interactive agno connect behaves differently when neither --url nor an exported AGENTOS_URL selects one target. It probes every live env-file and localhost candidate, adds AgentOS URLs found in existing client configurations, and asks you which one to connect. --json and other non-interactive runs use the deterministic priority order above.

Developer Resources

• agnoctl reference: full flag tables, environment variables, exit codes, and JSON output schemas
• Starter templates