Skip to content

CLI reference

The PolyAI ADK is accessed through the poly command. Use the CLI help output as the first source of truth.

Start with help

To see all available commands and options:

poly --help

Commands are listed under section headers so related ones stay together:

Section Commands
Getting started init, setup, login, studio, project
Project sync pull, push, status, revert, format, validate, diff, review, branch, test, rtc, chat
Builder API deployments, conversations, audio-cache, functions
Other template, docs, completion

Each command also supports its own help output. For example:

poly push --help

Use help output as the source of truth

The installed CLI is the fastest way to confirm the commands and flags available in your local environment.

Commands

Setting up

Command Purpose
poly setup Set up everything in one command: auth, completion, AI skills, and a project
poly login Sign in to, or sign up for, an Agent Studio account
poly init Connect a local folder to an existing project
poly project Create and manage Agent Studio projects
poly template Browse and load example project templates
poly completion Output a shell completion script

Editing and syncing

Command Purpose
poly pull Pull remote configuration into the local project
poly push Push local changes to Agent Studio
poly status List changed files
poly diff Show local changes in detail
poly revert Discard local changes
poly format Format resource files
poly validate Validate the project locally

Branches and review

Command Purpose
poly branch Create, switch, inspect, and merge branches
poly review Publish a diff for review

Testing and inspection

Command Purpose
poly chat Talk to the agent interactively
poly test Run and inspect simulated conversation tests
poly conversations List and inspect real conversations
poly docs Output resource documentation

Deployment and configuration

Command Purpose
poly deployments List, promote, and roll back deployments
poly rtc Manage per-environment Real-Time Configuration
poly audio-cache Inspect and replace cached TTS audio
poly functions Run and validate Functions via the REST API
poly studio Open the project in the Agent Studio web app

Shared flags

Most commands accept the same four flags:

Flag Description
--path PATH Base path to the project. Defaults to the current working directory.
--json Print a single JSON object on stdout, for scripting. See below.
--verbose Show full error tracebacks.
--debug Display debug logs.

Run commands from the project folder

ADK commands are expected to be run from within your local project directory. If needed, use --path to point to a project explicitly.

Machine-readable JSON output

All core subcommands accept a --json flag that switches stdout to a single JSON object. This is designed for scripting, CI pipelines, and any integration that needs stable, parseable output rather than human-readable console text.

poly status --json
poly push --json
poly pull --json
poly validate --json
poly diff --json
poly revert --json
poly branch list --json
poly branch create my-feature --json
poly branch switch my-feature --json
poly branch current --json
poly branch delete --json
poly branch delete my-feature --json
poly branch merge 'Merge message' --json
poly format --json
poly init --region us-1 --account_id 123 --project_id my_project --json
poly project create --region us-1 --account_id my-account --name my-project --json
poly chat --json -m 'Hello'
poly chat --json --input-file ./script.txt
poly deployments show abc123def --json
poly deployments list --json
poly deployments promote --from <id> --to pre-release --force --json
poly deployments rollback --to <id> --force --json
poly conversations list --json
poly conversations get <conversation_id> --json
poly conversations get-audio <conversation_id> --json
poly audio-cache list --json
poly audio-cache get-file <entry_id> --json
poly audio-cache update-file <entry_id> --file replacement.wav --json
poly audio-cache delete <entry_id> --json
poly audio-cache bulk-delete --ids id1,id2 --json
poly audio-cache synthesize <entry_id> --text "Hello" --json
poly functions execute <function_name> --args '{"x": 1}' --json
poly functions validate --json

--json contract

When --json is used:

  • stdout contains exactly one JSON object
  • the process exits with code 0 on success and non-zero on failure
  • human-readable console messages are suppressed
  • error responses always include { "success": false, "error": "...", "traceback": "..." }

The exact top-level keys vary by command — each command's page documents its own output shape.

--interactive and --json cannot be used together

poly branch merge --interactive requires a terminal for its conflict-resolution prompts and is incompatible with --json.

--json implies --force for deployments commands

When --json is used with poly deployments promote or poly deployments rollback, the confirmation prompt is automatically skipped (equivalent to passing --force).

Advanced JSON-driven workflows

A few commands support extra flags for piping JSON between invocations instead of hitting the API each time:

Flag Commands Description
--from-projection <source> pull, push, init, branch switch Supply a projection JSON directly (file path, inline string, or - for stdin) instead of fetching it from the API. Useful for offline workflows and integration testing.
--output-json-projection pull, init, branch switch Include the projection in the --json output, so it can be captured and fed into another command's --from-projection.
--output-json-commands push Add a commands array to the --json output, containing the serialized Agent Studio commands that were staged. Useful for dry-run review and integration testing. 
poly pull --from-projection - < projection.json
poly push --from-projection '{"topics": [...], ...}'
poly pull --json --output-json-projection | jq .projection > proj.json
poly push --json --dry-run --output-json-commands