a2a CLI
Build, package, and deploy A2A agents.
Top-level help
Usage: a2a [OPTIONS] COMMAND [ARGS]...
Build, package, and deploy A2A agents.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ signup Create or sign into a Keycloak account and cache OAuth │
│ tokens. │
│ login Authenticate with Keycloak and cache OAuth tokens. │
│ logout Forget the cached JWT. │
│ whoami Show the currently logged-in user. │
│ agents List agents visible to the current user. │
│ import Import an already-running A2A agent into the registry. │
│ init Scaffold a new agent project. │
│ validate Load the agent and print its Card schema. Exits non-zero on │
│ errors. │
│ card Print the Agent Card JSON for the project's agent. │
│ compile Compile the project declaration to the sidecar Agent DSL. │
│ run Run the agent's HTTP server locally (used inside the │
│ container too). │
│ sidecar Run the common sidecar runtime for a compiled Agent DSL. │
│ dev Edit locally, run in the cloud: sync this project to the │
│ agent's scale-to-zero │
│ dev box, hot-reload it there, and serve it on a public URL. │
│ Use --local to run │
│ on this machine instead. │
│ chat Run one agent plus declared local Qdrant/Postgres resources. │
│ test Run local preflight checks before deploying. │
│ mcp-url Print the MCP connect config for a deployed agent. │
│ build Build (and optionally push) the container image for the │
│ agent. │
│ deploy Ship the agent. │
│ ssh Open a shell in a throwaway dev box for AGENT. │
│ local-deploy Deploy an agent to the local devcontainer control plane. │
│ local-cleanup Delete a local devcontainer agent and managed local │
│ resources. │
│ use Make AGENT's tools available as typed `a2a <agent> <tool>` │
│ commands. │
│ unuse Remove AGENT's cached CLI stub (stored setup values are │
│ kept). │
│ call Invoke one tool without a typed stub — the schema-free escape │
│ hatch. │
│ frontend Build and inspect packed frontend apps. │
│ auth Manage imported agent auth. │
│ openapi Generate editable agents from OpenAPI specs. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a agents
Usage: a2a agents [OPTIONS]
List agents visible to the current user.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --api TEXT │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a auth
Usage: a2a auth [OPTIONS] COMMAND [ARGS]...
Manage imported agent auth.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ status Show detected auth requirements and configured connections. │
│ bearer Connect HTTP/Bearer auth for an imported agent. │
│ api-key Connect API-key auth for an imported agent. │
│ oauth-token Connect OAuth/OIDC with an existing access token and optional │
│ refresh config. │
│ mtls Connect mTLS client certificate auth for an imported agent. │
│ delete Remove an imported-agent auth connection. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a build
Usage: a2a build [OPTIONS]
Build (and optionally push) the container image for the agent.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --registry TEXT [default: registry.a2acloud.io] │
│ --push Also push the built image │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a call
Usage: a2a call [OPTIONS] AGENT TOOL [ARGS]...
Invoke one tool without a typed stub — the schema-free escape hatch.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * agent TEXT Agent name [required] │
│ * tool TEXT Tool id (see the agent card or `a2a use`) │
│ [required] │
│ [args]... TEXT key=value pairs; values support @file and @- for │
│ stdin │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --json TEXT Full arguments as JSON (inline or @file.json) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a card
Usage: a2a card [OPTIONS]
Print the Agent Card JSON for the project's agent.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a chat
Usage: a2a chat [OPTIONS]
Run one agent plus declared local Qdrant/Postgres resources.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --host TEXT [default: 127.0.0.1] │
│ --port INTEGER [default: 8000] │
│ --reload --no-reload [default: reload] │
│ --env-file PATH [default: .env.local] │
│ --workspace PATH │
│ --build --no-build Build the local agent image │
│ before starting compose. │
│ [default: build] │
│ --up --no-up Start the compose harness │
│ after writing it. │
│ [default: up] │
│ --detach --foreground Run compose in the background. │
│ [default: foreground] │
│ --down Stop the existing chat harness │
│ for this project. │
│ --volumes With --down, also remove the │
│ chat harness data volumes. │
│ --print-compose Print the generated compose │
│ file. │
│ --base-image TEXT Base image for the generated │
│ local Dockerfile. │
│ [default: python:3.11-slim] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a compile
Usage: a2a compile [OPTIONS]
Compile the project declaration to the sidecar Agent DSL.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --out -o PATH Write DSL JSON here (defaults to │
│ PROJECT/.a2a/agent.dsl.json) │
│ --stdout Print DSL JSON instead of writing a file │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a deploy
Usage: a2a deploy [OPTIONS] [PROJECT]
Ship the agent.
Tarballs your source, uploads to the control plane, and prints the
URL when it's live. No local docker. No git. No knowledge of how the
platform builds or deploys.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ [PROJECT] PATH Project directory containing a2a.yaml │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --public --private │
│ --wait --no-wait Poll until URL is live [default: wait] │
│ --api TEXT Override control plane URL │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a dev
Usage: a2a dev [OPTIONS]
Edit locally, run in the cloud: sync this project to the agent's scale-to-zero
dev box, hot-reload it there, and serve it on a public URL. Use --local to run
on this machine instead.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --host TEXT [default: 127.0.0.1] │
│ --port INTEGER [default: 8000] │
│ --reload --no-reload [default: reload] │
│ --env-file PATH [default: .env.local] │
│ --workspace PATH │
│ --docker --host-runtime Run dev mode in the agent │
│ container image instead of this │
│ Python process. │
│ [default: docker] │
│ --local Run on this machine instead of a │
│ cloud dev box (offline / │
│ air-gapped). │
│ --agent TEXT Agent name for the cloud dev box │
│ (default: a2a.yaml name). │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a frontend
Usage: a2a frontend [OPTIONS] COMMAND [ARGS]...
Build and inspect packed frontend apps.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ build Build the packed frontend declared in a2a.yaml. │
│ info Print the packed frontend config resolved from a2a.yaml. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a import
Usage: a2a import [OPTIONS] URL
Import an already-running A2A agent into the registry.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * url TEXT Base URL of an existing A2A agent [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --name -n TEXT Registry slug to use │
│ --public --private [default: private] │
│ --auth-bearer TEXT Bearer token for the imported agent │
│ --auth-api-key TEXT API key value for the imported agent │
│ --auth-name TEXT API-key header or query parameter │
│ name │
│ --auth-location TEXT API-key location: header or query │
│ [default: header] │
│ --auth-scheme TEXT HTTP Authorization scheme │
│ [default: Bearer] │
│ --api TEXT │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a init
Usage: a2a init [OPTIONS] NAME
Scaffold a new agent project.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Agent / project slug, e.g. research-agent [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --description -d TEXT [default: A new A2A agent] │
│ --target -t PATH Parent dir for the new project [default: .] │
│ --language -l TEXT Template language: python, typescript, │
│ javascript, go, or rust │
│ [default: python] │
│ --frontend TEXT Add a packed frontend scaffold: static, │
│ react, or nextjs │
│ --frontend-mode TEXT Frontend deployment mode: static or │
│ server-rendered │
│ [default: static] │
│ --auth TEXT App auth mode for scaffolded │
│ agents/frontends: inherit, platform, or │
│ public │
│ [default: inherit] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a local-cleanup
Usage: a2a local-cleanup [OPTIONS] NAME
Delete a local devcontainer agent and managed local resources.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * name TEXT Agent name to delete from the local control plane │
│ [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --api TEXT Local control plane │
│ URL │
│ --token TEXT Bearer token override │
│ --token-email TEXT Local user email used │
│ when minting a local │
│ token with docker │
│ exec │
│ [default: │
│ local@example.com] │
│ --docker-token --no-docker-token Mint a local CP token │
│ from the │
│ microcash-control-pl… │
│ container when none │
│ is supplied │
│ [default: │
│ docker-token] │
│ --wait-control-plane --no-wait-control-pl… Wait for the local │
│ control plane │
│ /healthz before │
│ deleting │
│ [default: │
│ wait-control-plane] │
│ --ignore-missing Return success when │
│ the agent is already │
│ absent │
│ --json Print │
│ machine-readable JSON │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a local-deploy
Usage: a2a local-deploy [OPTIONS] [PROJECT]
Deploy an agent to the local devcontainer control plane.
This is the non-interactive local harness for tests and generated agents:
it mints an e2e bearer token from the local control-plane container when
no token env var is present, then uses the same tarball upload path as
`a2a deploy`.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ [PROJECT] PATH Project directory containing a2a.yaml │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --public --private │
│ --api TEXT Local control plane │
│ URL │
│ --token TEXT Bearer token override │
│ --token-email TEXT Local user email used │
│ when minting a local │
│ token with docker │
│ exec │
│ [default: │
│ local@example.com] │
│ --docker-token --no-docker-token Mint a local CP token │
│ from the │
│ microcash-control-pl… │
│ container when none │
│ is supplied │
│ [default: │
│ docker-token] │
│ --wait-control-plane --no-wait-control-… Wait for the local │
│ control plane │
│ /healthz before │
│ uploading │
│ [default: │
│ wait-control-plane] │
│ --wait-agent --no-wait-agent Wait for the deployed │
│ agent /healthz URL │
│ after upload │
│ [default: │
│ no-wait-agent] │
│ --json Print │
│ machine-readable JSON │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a login
Usage: a2a login [OPTIONS]
Authenticate with Keycloak and cache OAuth tokens.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --api TEXT [default: https://api.a2acloud.io] │
│ --issuer TEXT [default: │
│ https://auth.a2acloud.io/realms/a2aclo… │
│ --client-id TEXT [default: a2acloud-cli] │
│ --scope TEXT [default: openid email offline_access │
│ mcp:invoke agent:read] │
│ --port INTEGER [default: 41873] │
│ --token TEXT Use an existing Keycloak access token │
│ --open --no-open Open the login URL [default: open] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a logout
Usage: a2a logout [OPTIONS]
Forget the cached JWT.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a mcp-url
Usage: a2a mcp-url [OPTIONS] [NAME]
Print the MCP connect config for a deployed agent.
Every shipped agent auto-exposes ``POST /mcp`` (Streamable HTTP).
This command prints the JSON snippet you paste into Claude Code,
Cursor, or any other MCP client to wire up the agent.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ [name] TEXT Agent name (defaults to a2a.yaml in --project) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --api TEXT │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a openapi
Usage: a2a openapi [OPTIONS] COMMAND [ARGS]...
Generate editable agents from OpenAPI specs.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ preview Preview generated tools, setup fields, and source files. │
│ generate Generate an editable A2APack source repo and start deployment. │
│ spec Generate an OpenAPI spec for this agent's direct tool APIs. │
│ client Generate a TypeScript client for this agent's tool APIs. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a run
Usage: a2a run [OPTIONS]
Run the agent's HTTP server locally (used inside the container too).
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --entrypoint -e TEXT module:Class [required] │
│ --host TEXT [default: 0.0.0.0] │
│ --port INTEGER [default: 8000] │
│ --project -p PATH [default: .] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a sidecar
Usage: a2a sidecar [OPTIONS]
Run the common sidecar runtime for a compiled Agent DSL.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --dsl PATH Compiled Agent DSL JSON path │
│ [default: .a2a/agent.dsl.json] │
│ --worker-url TEXT Native language worker base URL │
│ [default: http://127.0.0.1:9001] │
│ --host TEXT [default: 0.0.0.0] │
│ --port INTEGER [default: 8000] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a signup
Usage: a2a signup [OPTIONS]
Create or sign into a Keycloak account and cache OAuth tokens.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --api TEXT [default: https://api.a2acloud.io] │
│ --issuer TEXT [default: │
│ https://auth.a2acloud.io/realms/a2aclo… │
│ --client-id TEXT [default: a2acloud-cli] │
│ --scope TEXT [default: openid email offline_access │
│ mcp:invoke agent:read] │
│ --port INTEGER [default: 41873] │
│ --token TEXT Use an existing Keycloak access token │
│ --open --no-open Open the login URL [default: open] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a ssh
Usage: a2a ssh [OPTIONS] [AGENT]
Open a shell in a throwaway dev box for AGENT.
The box has node, python, a2a-pack, and the agent repo already loaded, and
scales to zero when you disconnect. Also usable from VS Code Remote-SSH,
Cursor, scp, and rsync via the host alias it writes to ~/.ssh/config.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ [agent] TEXT Agent name (defaults to a2a.yaml in the current repo) │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --print Print connection info instead of opening a shell │
│ --tunnel Serve the dev box on a local TCP port for SSH tools │
│ that can't use ~/.ssh/config (GUIs, IDEs, sftp │
│ clients) │
│ --port INTEGER Local port for --tunnel (0 = pick a free one) │
│ [default: 0] │
│ --json Print connection details as JSON (implies --print) │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a test
Usage: a2a test [OPTIONS]
Run local preflight checks before deploying.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --env-file PATH [default: .env.local] │
│ --workspace PATH │
│ --invoke --no-invoke Run a local tool call │
│ [default: no-invoke] │
│ --skill TEXT Tool to invoke │
│ --args-json TEXT JSON object args for --invoke │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a unuse
Usage: a2a unuse [OPTIONS] AGENT
Remove AGENT's cached CLI stub (stored setup values are kept).
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * agent TEXT Agent stub to remove [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a use
Usage: a2a use [OPTIONS] AGENT
Make AGENT's tools available as typed `a2a <agent> <tool>` commands.
Fetches the agent card (tools + input schemas + consumer setup), checks
the platform-side setup status, then caches the typed stub. Re-run any
time to refresh.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * agent TEXT Agent name from the registry (`a2a agents`) [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a validate
Usage: a2a validate [OPTIONS]
Load the agent and print its Card schema. Exits non-zero on errors.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --project -p PATH [default: .] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯a2a whoami
Usage: a2a whoami [OPTIONS]
Show the currently logged-in user.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯