> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly --help
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly push --help
```

> [!TIP]
>
> **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.

> [!NOTE]
>
> **How the CLI maps to the new deployment system**
>
> The CLI keeps its own names. On projects using the new deployment system they map as follows:
>
> * `main` is the Live version. A branch is a Branch, cut from Live. A branch created from another branch is a Sub-branch.
> * `poly branch merge` merges into the parent. Merging a Branch into `main` publishes it to Live. Merging a Sub-branch merges it into its Branch.
> * `poly branch sync` is Sync. It pulls the parent's changes into your branch. Run it before merging if the parent has moved on.
> * `poly branch tag` moves the current Branch to Staging (`pre-release` in the CLI). `poly branch untag` removes it.
> * `poly deployments promote`, and the old sequence of promoting from sandbox to pre-release to live, apply only to projects that have not yet moved to the new deployment system.
> * `poly deployments rollback` rolls Live back on new-system projects.

## Core commands

### `poly start`

End-to-end onboarding for **self-serve** accounts on [studio.poly.ai](https://studio.poly.ai). `poly start` is hardcoded to the `studio` region — for any other region, use [`poly login`](#poly-login).

`poly start`:

1. Opens a browser window so you can sign up or sign in to a self-serve workspace.
2. Generates an API key (or reuses your existing one) and writes it to `~/.poly/credentials.json` under the `studio` region.
3. Optionally creates a new Agent Studio project and pulls it down locally.

If the ADK detects an existing API key in the credential file or environment, `poly start` asks whether to use it. Accept and the command skips ahead to the project-creation prompt; decline and it runs the full sign-in flow.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly start
poly start --base-path /path/to/projects
```

| Flag | Description |
| - | - |
| `--base-path` | Base path to initialize the project in. Defaults to the current working directory. |

### `poly login`

Sign in to an existing Agent Studio account and save API key credentials for the CLI. Works against any region — including `studio`, which makes `poly login --region studio` a viable alternative to `poly start` for self-serve users on a new machine who already have an account and don't need to create a project.

`poly login`:

1. Prompts for a region if `--region` is not supplied.
2. Opens a browser window for sign-in via the Auth0 device authorization flow.
3. Fetches or creates an API key for your user and saves it to `~/.poly/credentials.json` under the chosen region.

Run `poly login` once per region you need access to — credentials for multiple regions are stored side by side in the credential file.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly login
poly login --region us-1
poly login --region euw-1
poly login --region uk-1
poly login --region studio
```

| Flag | Description |
| - | - |
| `--region` | Region to log in to. If omitted, you are prompted to pick one. Choices match the standard region list. |

### `poly apikey`

`poly apikey` exists to get an account API key into `POLY_API_KEY` for the PolyAI APIs and Dialog RSN, and is runnable by an AI coding assistant. One-shot, non-interactive setup: sign-in, creates the account if needed, reuses or creates an account-scoped API key, saves it to `~/.poly/credentials.json`, and exports `POLY_API_KEY` into the shell profile (Windows: user environment). With `--json` (or no terminal) it never prompts; the one prompt it has is the account picker, shown at a terminal when you belong to more than one account. `--region` is required — pass `studio` (PLG) for GitHub-only device sign-in, or any other cluster for the standard sign-in page instead. See [Set up with an AI coding assistant](https://docs.poly.ai/adk/get-started/agentic-setup.md) for the copy-paste prompt that runs this for you. To set up the ADK itself, use `poly setup`/`poly login` instead.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly apikey --region studio
poly apikey --region studio --account-id acc-123
poly apikey --region studio --key-name my-key -f
poly apikey --region studio --json
poly apikey --region us-1
```

| Flag | Description |
| - | - |
| `--region REGION` | Region/cluster to create the key for. Required — no default. Choices match the standard region list. |
| `--key-name NAME` | Name for the account-scoped API key. Defaults to `cli-generated-key` for `studio`, or `cli-generated-key-<region>` for any other region. |
| `--account-id ID` | Account ID to scope the key to. Skips polling for a newly created account. With more than one account and no `--account-id`, a terminal shows a picker; otherwise the command stops and lists them (an `accounts` array in `--json`) so you can re-run with one. The sign-in is kept, so the re-run doesn't sign you in again. |
| `-f`, `--force` | Overwrite an existing `POLY_API_KEY` if it holds a different value. |
| `--json` | Print a single JSON object on stdout. The sign-in URL goes to stderr instead of being suppressed. |

Exit codes: `0` on success, `1` on a sign-in, account, or API failure, `2` when `POLY_API_KEY` is already set to a different value and `--force` was not passed.

> [!NOTE]
>
> **Which region should I pick?**
>
> Pass `--region studio` (PLG) — the cluster individual developers sign up on via GitHub — unless you already have an enterprise account provisioned in a production region (`us-1`, `uk-1`, `euw-1`). Those regions require signing in through the standard email/SSO login page rather than GitHub, since the GitHub-only client only exists for `studio`.

### `poly project`

Manage Agent Studio projects.

#### `poly project create`

Create a new Agent Studio project under an account, then initialize it locally.

Run with no arguments and `poly project create` walks you through interactive prompts:

1. **Region** — auto-selected if your API key only has access to one.
2. **Account** — auto-selected if there's only one in the region; otherwise pick from a searchable list.
3. **Project name** — free-text name for the new project.
4. **Project ID** — optional slug. Defaults to a slugified version of the name (lowercased, spaces replaced with hyphens, special characters removed). Leave empty to let the platform generate one.

After the project is created in Agent Studio, `poly project create` automatically calls `poly init` to initialize the local project directory.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly project create
poly project create --region us-1 --account_id my-account --name my-project
poly project create --region us-1 --account_id my-account --name "My Project" --id my-project
poly project create --region us-1 --account_id my-account --name my-project --greeting "Hi, how can I help?"
poly project create --base-path /path/to/projects
```

| Flag | Description |
| - | - |
| `--region` | Region for the new project. Choices match the standard region list. |
| `--account_id` | Account ID to create the project under. |
| `--name` | Display name for the new project. |
| `--id`, `--project_id` | Optional slug/ID for the project. Defaults to a slugified version of the name. |
| `--greeting` | Initial greeting message for the agent. Defaults to `"Hello, how can I help you?"`. |
| `--voice-id` | Voice ID for the agent. Defaults to a region-specific voice if not supplied. |
| `--base-path` | Base path to initialize the project in. Defaults to the current working directory. |
| `--json` | Print a single JSON object on stdout (machine-readable). Requires `--region`, `--account_id`, and `--name`. |

> [!NOTE]
>
> **`--json` requires explicit flags for `poly project create`**
>
> When using `poly project create --json`, you must supply `--region`, `--account_id`, and `--name` explicitly. Interactive prompts are not supported in JSON mode.

#### Error handling

| Situation | Behaviour |
| - | - |
| `--json` used without `--region`, `--account_id`, or `--name` | Exits with `{ "success": false, "error": "..." }` |
| No accessible regions found | Exits with an error |
| No accounts found in the selected region | Exits with an error |
| API error during project creation | Exits with an error; local init is not attempted |
| No project ID returned by the API | Exits with an error; local init is not attempted |

### `poly init`

Initialize a new Agent Studio project locally.

Run with no arguments and `poly init` walks you through interactive dropdowns:

1. **Region** — auto-selected if your API key only has access to one.
2. **Account** — auto-selected if there's only one in the region; otherwise pick from a searchable list. Each entry is shown as `"name (id)"` to disambiguate accounts that share the same display name.
3. **Project** — pick from a searchable list of every project the API key can see. Each entry is shown as `"name (id)"` for the same reason.

If no projects are found in the selected account, `poly init` offers to create one. Accepting the prompt starts the [`poly project create`](#poly-project-create) flow with the region and account already pre-selected.

After selection, `poly init` creates the project directory at `{base_path}/{account_id}/{project_id}` and immediately pulls the current configuration from Agent Studio. Change into the project directory before running any other commands.

The human-readable project name is stored in `project.yaml` alongside the `project_id`, `account_id`, and `region`:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
project_id: my-project
account_id: my-workspace
region: us-1
project_name: My Project
```

Pass any combination of `--region`, `--account_id`, and `--project_id` to skip the matching prompt. This is the form to use in scripts and CI.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly init
poly init --account_id 123 --project_id my_project
poly init --region us-1 --account_id 123 --project_id my_project
poly init --base-path /path/to/projects
poly init --format
```

#### Error handling

If the account or project ID is invalid or inaccessible, `poly init` returns a descriptive error and cleans up any partially created directories so no empty folders are left behind.

| Situation | Error message |
| - | - |
| `POLY_ADK_KEY` not set | `POLY_ADK_KEY environment variable is not set. Export your API key with: export POLY_ADK_KEY=<your-api-key>` |
| No accounts found in the region | `No accounts found in the selected region.` |
| No projects found in the account | Prompts to create a new project (interactive) or exits with error (JSON mode). |
| Project not found | `Project '<project_id>' not found in account '<account_id>'.` |
| Permission denied | `Forbidden: you do not have permission to access project '<project_id>' in account '<account_id>'.` |

When using `--json`, the response includes `{ "success": false, "error": "..." }` with the same message.

### `poly pull`

Pull the latest project configuration from Agent Studio.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly pull
poly pull --force
poly pull --format
```

If the branch you are currently on no longer exists in Agent Studio, `poly pull` automatically switches to the `main` branch and displays a warning message with the new branch name.

When using JSON output (`--json`), the response includes `new_branch_name` and `new_branch_id` fields if a branch switch occurred.

### `poly push`

Push local changes to Agent Studio.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly push
poly push --dry-run
poly push --skip-validation
poly push --force
poly push --format
```

When pushing creates a new branch (for example, when pushing to Agent Studio for the first time on a branch), the CLI displays a message with the new branch name.

| Flag | Description |
| - | - |
| `--dry-run` | Run all validation and diff steps without sending changes to Agent Studio. |
| `--skip-validation` | Bypass local validation. Use sparingly — for example, when a platform-generated resource fails a strict ADK check but is known to be valid on the platform. |
| `--force`, `-f` | Force the push even when the local project diverges from the remote in unexpected ways. |
| `--format` | Run [`poly format`](#poly-format) over the project before pushing. |

> [!NOTE]
>
> **Call Link URL in chat output may be malformed**
>
> Each chat session prints a Call Link URL for viewing the conversation in Agent Studio. On some deployments this URL has a doubled hostname (for example, `https://studio.studio.poly.ai/…`), which produces a 404. The conversation is still recorded — open Agent Studio directly and navigate to the conversation from there.

> [!NOTE]
>
> **`poly push` reports an error message when there is nothing to push**
>
> If there are no local changes, `poly push` prints `Error: Failed to push` and `No changes detected`. The exit code is 0, so CI scripts that check return codes are not affected. The message is misleading but the command has not actually failed.

When using JSON output (`--json`), the response includes `new_branch_name` and `new_branch_id` fields if a new branch was created.

### `poly status`

View changed, new, and deleted files in your project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly status
```

### `poly diff`

Show differences between the local project and the remote version.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly diff
poly diff --files file1.yaml
poly diff --before main --after my-feature
```

### `poly revert`

Revert local changes.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly revert
poly revert file1.yaml file2.yaml
```

`poly revert` with no arguments reverts every change in the working tree; pass file paths to revert only those files.

### `poly branch`

Manage project branches.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch list
poly branch current
poly branch create my-feature
poly branch create my-hotfix --env live
poly branch create my-hotfix --env live --force
poly branch switch my-feature
poly branch switch my-feature --force
poly branch merge 'Merge feature branch'
poly branch merge 'Merge feature branch' --interactive
poly branch sync
poly branch tag
poly branch untag
poly branch delete
poly branch delete my-feature
```

#### `poly branch merge`

Merge the current branch into its parent via the CLI. A merge message is required. On the new deployment system, merging a Branch into `main` publishes it to Live, and merging a Sub-branch merges it into its Branch.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch merge 'Merge message'
poly branch merge 'Merge message' --interactive
poly branch merge 'Merge message' --resolutions resolutions.json
```

For the full merge workflow — conflict tables, `--interactive` flow, the `--resolutions` JSON format, post-merge behavior, and troubleshooting — see the dedicated [Branch merging reference](https://docs.poly.ai/adk/reference/branch_merge.md).

#### `poly branch sync`

Pull the parent's changes into the current branch. A Branch's parent is `main` (Live on the new deployment system); a Sub-branch's parent is its Branch. Run it before merging if the parent has changed since you created or last synced the branch.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch sync
```

#### `poly branch tag`

Move the current Branch to Staging (`pre-release` in the CLI) so you can test it over a real phone number or widget. Staging holds one Branch at a time. `main` and Sub-branches cannot be tagged. Use `poly branch untag` to take the Branch out of Staging.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch tag
poly branch untag
```

#### `poly branch delete`

Interactively select and delete one or more branches. The `main` branch cannot be deleted.

* Run without arguments to open an interactive checkbox prompt for selecting branches to delete.
* Pass a branch name directly to skip the interactive prompt and delete that branch after confirmation.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly branch delete
poly branch delete my-feature
```

> [!WARNING]
>
> **`poly branch delete` requires a TTY and may fail with a 404**
>
> `poly branch delete` opens an interactive confirmation prompt and must be run in a terminal. In non-interactive environments (scripts, CI), it throws `[Errno 22] Invalid argument`.
>
> On some projects, the delete command hits the same platform endpoint as branch chat and returns a 404 after the confirmation. If this happens, delete the branch through the Agent Studio UI instead.

#### `poly branch create`

Creates a new branch. By default the branch is sourced from the project's `main` branch. On the new deployment system `main` is Live, so the new Branch starts as a copy of Live. On projects that have not yet moved, `main` is the sandbox environment.

| Flag | Description |
| - | - |
| `--env`, `--environment` | Source the new branch from a deployed environment snapshot instead of `main`. Choices: `sandbox`, `pre-release`, `live`. `pre-release` is the Staging environment. |
| `--force`, `-f` | Force branch creation even if there are uncommitted local changes on main. |

When `--env live` or `--env pre-release` (Staging) is specified:

* the version of the deployed environment is pulled into your local workspace
* a branch is created from that snapshot
* the version is immediately pushed to the new branch, leaving a clean slate for hotfix changes
* the command can only be run from `main`
* if there are local changes, the command will fail unless `--force` is also passed

> [!WARNING]
>
> **Use `--env live` with caution**
>
> Branching from a Live deployment snapshot will overwrite your local project with the Live state. On projects that have not yet moved to the new deployment system, merging this branch back to `main` may roll back changes that were introduced after the snapshot was taken. On the new deployment system, if Live changes after the snapshot, run `poly branch sync` before merging so those changes are kept.

### `poly format`

Format project resources.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly format
poly format --check
poly format --files src/functions/booking.py
```

### `poly validate`

Validate project configuration locally.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly validate
```

### `poly review`

Create a GitHub Gist of Agent Studio project changes to share with others.

`poly review` requires a subcommand: `create`, `list`, or `delete`. Use `poly review create` to compare your local changes against the remote project, or pass `--before` and `--after` to compare two remote branches or versions. Add `--verbose` for full error tracebacks while troubleshooting.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly review create
poly review create --before main --after feature-branch
poly review create --verbose
```

#### `poly review list`

Interactively select a review gist and open it in the browser.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly review list
poly review list --json
```

#### `poly review delete`

Interactively select and delete review gists. Use `--id` to delete a specific gist directly without an interactive prompt.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly review delete
poly review delete --id GIST_ID
poly review delete --json
```

### `poly chat`

Start an interactive chat session with your agent, or run scripted/automated conversations.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat
poly chat --environment live
poly chat --channel webchat
poly chat --metadata
poly chat --lang fr-FR
poly chat --input-lang en-US --output-lang fr-FR
```

#### Non-interactive (scripted) mode

Supply messages directly on the command line or from a file to run `poly chat` without a human at the terminal. This is useful for automated testing pipelines and CI scripts.

**Inline messages** — use `-m`/`--message` (repeatable):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat -m 'Hello' -m 'What can you help with?'
```

**File-based input** — use `--input-file`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat --input-file ./script.txt
echo -e 'Hello\nGoodbye' | poly chat --input-file -
```

Each line of the file is sent as a separate message. Use `-` to read from stdin.

If the file path does not exist, `poly chat` exits with an error.

#### Resuming an existing conversation

Use `--conversation-id` (or `--conv-id`) to resume an existing conversation by its ID instead of creating a new session:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat --conv-id <conversation_id>
poly chat --conv-id <conversation_id> -m 'Follow-up message'
```

#### Pushing before chatting

Use `--push` to push the local project to Agent Studio before starting the chat session. This ensures the branch has your latest local changes before testing, without requiring a separate `poly push` step:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly chat --push
poly chat --push -m 'Hello'
```

If the push fails, the command exits without starting the chat session.

#### Language flags

Use language flags to specify the expected input and output language when chatting against multilingual agents. If not specified, the project default is used.

| Flag | Description |
| - | - |
| `--lang` | Sets both input and output language (e.g. `en-US`, `fr-FR`). |
| `--input-lang` | Sets the input language (ASR) only. Overrides `--lang` for input. |
| `--output-lang` | Sets the output language (TTS) only. Overrides `--lang` for output. |

`--input-lang` and `--output-lang` take precedence over `--lang` when both are supplied.

#### `poly chat` flags summary

| Flag | Description |
| - | - |
| `--push` | Push the project before starting the chat session. |
| `-m`, `--message MSG` | Send a message non-interactively (repeatable). |
| `--input-file FILE` | Read messages line-by-line from a file (`-` for stdin). |
| `--conversation-id`, `--conv-id` | Resume an existing conversation by ID. |
| `--json` | Emit a single JSON object when the session ends (see below). |
| `--environment` | Target environment. Choices: `branch`, `sandbox`, `pre-release`, `live`. Defaults to `branch`. `pre-release` is the Staging environment. `branch` chats against the last **pushed** state of your current branch (not local uncommitted changes); on main it falls back to `sandbox`. Use `--push` to push local changes before chatting. |
| `--channel` | Channel to use (e.g. `webchat`, `voice`). |
| `--lang` | Set both input and output language. |
| `--input-lang` | Set input language only. |
| `--output-lang` | Set output language only. |
| `--variant` | Name of the variant to use for the chat session. |
| `--functions` | Show function events in output. |
| `--flows` | Show flow metadata in output. |
| `--state` | Show state changes in output. |
| `--metadata` | Show all metadata (equivalent to `--functions --flows --state`). |

### `poly conversations`

List and inspect conversations for the project using the public Conversations API.

`poly conversations` requires a subcommand: `list`, `get`, or `get-audio`.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly conversations list
poly conversations get <conversation_id>
poly conversations get-audio <conversation_id> -o recording.wav
```

#### `poly conversations list`

List conversations for the project.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly conversations list
poly conversations list --limit 20 --offset 10
poly conversations list --json
```

| Flag | Description |
| - | - |
| `--limit` | Max number of conversations to return. Defaults to `50`. |
| `--offset` | Number of conversations to skip. Defaults to `0`. |
| `--path` | Base path to the project. Defaults to the current working directory. |
| `--json` | Print a single JSON object on stdout (machine-readable). |

The default table view shows conversation ID (rendered as a clickable Agent Studio link), start time, duration, caller number, channel, variant (when present), handoff status, and a short summary heading.

#### `poly conversations get`

Get detailed information for a specific conversation, including all turns.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly conversations get <conversation_id>
poly conversations get <conversation_id> --json
```

| Argument / Flag | Description |
| - | - |
| `conversation_id` | The conversation ID to look up. Required. |
| `--path` | Base path to the project. Defaults to the current working directory. |
| `--json` | Print a single JSON object on stdout (machine-readable). |

The default output shows conversation metadata (channel, language, duration, timestamps, handoff, tags, PolyScore, summary, note) followed by a turn-by-turn transcript.

#### `poly conversations get-audio`

Download the audio recording for a conversation as a WAV file.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly conversations get-audio <conversation_id>
poly conversations get-audio <conversation_id> --direction user
poly conversations get-audio <conversation_id> --redacted -o redacted.wav
poly conversations get-audio <conversation_id> --json
```

| Argument / Flag | Description |
| - | - |
| `conversation_id` | The conversation ID. Required. |
| `--direction` | Audio track to download. Choices: `combined`, `user`, `agent`. Defaults to `combined`. |
| `--redacted` | Download the redacted version of the audio. |
| `-o`, `--output` | Output file path. Defaults to `<conversation_id>.wav`. |
| `--path` | Base path to the project. Defaults to the current working directory. |
| `--json` | Print a JSON summary on stdout instead of the success message (audio is still written to disk). |

### `poly docs`

Output resource documentation.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly docs flows functions topics
poly docs context
poly docs --all
poly docs --all --output rules.md
```

Use `--output` to write the documentation to a local file. This is useful when working with AI coding tools — pass the output file as context to give the agent accurate knowledge of ADK resource types and conventions.

Available resource names include:

| Name | Description |
| - | - |
| `agent_settings` | Personality, role, rules |
| `api_integrations` | External HTTP API definitions |
| `chat_settings` | Chat greeting, style prompt |
| `context` | Context files for agent knowledge |
| `entities` | Structured data collection |
| `experimental_config` | Feature flags |
| `flows` | Multistep processes with steps, functions, conditions |
| `handoffs` | SIP call transfers |
| `functions` | Global and flow functions, decorators, state, metrics |
| `languages` | Default and additional language configuration |
| `tests` | Simulated conversation test cases |
| `safety_filters` | Content moderation settings |
| `sms` | Text message templates |
| `speech_recognition` | ASR settings, keyphrase boosting, transcript corrections |
| `response_control` | Pronunciations, phrase filters |
| `topics` | Knowledge base for RAG |
| `translations` | Localized text strings per language |
| `variants` | Per-variant configuration |
| `voice_settings` | Voice greeting, disclaimer, style prompt |
| `variables` | State variables referenced in code |

### `poly deployments`

Manage deployments for the project.

#### `poly deployments list`

List deployments for the project.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly deployments list
poly deployments list --env live
poly deployments list --details
poly deployments show abc123def
poly deployments show abc123def --env live
```

#### `poly deployments list`

List deployments for the project.

| Flag | Description |
| - | - |
| `--env` | Environment to list deployments for. Choices: `sandbox`, `pre-release`, `live`. `pre-release` is the Staging environment. Defaults to `live` on projects using the new deployment system, otherwise `sandbox`. |
| `--details` | Show additional deployment details. |
| `--verbose` | Show full error tracebacks for debugging. |

> [!TIP]
>
> **Use `--details` for readable output**
>
> The default tabular view may wrap long URLs across multiple rows, making it unreadable in narrow terminals. `--details` produces a vertical layout that is easier to read.

#### `poly deployments promote`

This command applies to projects that have not yet moved to the new deployment system, where publishing a Branch replaces promotion.

Promote a deployment to the next environment (`pre-release` or `live`), removing the need to use the Agent Studio UI.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly deployments promote --from <deployment_id> --to pre-release
poly deployments promote --from sandbox --to live --message "Release notes here"
poly deployments promote --from <deployment_id> --to pre-release --dry-run
poly deployments promote --from <deployment_id> --to live --force
```

| Flag | Description |
| - | - |
| `--from` | ID or environment name of the deployment to promote. Required. |
| `--to` | Target environment. Choices: `pre-release`, `live`. Required. |
| `--message`, `-m` | Optional message to include with the promotion (e.g. release notes or changelog). If not specified, the existing deployment message is used. |
| `--force` | Skip the confirmation prompt. When used without `--message`, the existing deployment message is kept. This is the default in non-interactive mode (e.g. when `--json` is used). |
| `--dry-run` | Show what would be promoted without actually promoting. Displays the deployment hash, target environment, and changes included. |
| `--verbose` | Show full error tracebacks for debugging. |

When promoting to `live`, the command searches for the deployment in `pre-release` and uses sandbox as the linear history source for computing included changes. When promoting to `pre-release`, the command searches sandbox.

The output includes:

* the deployment hash being promoted
* whether it is a first-time promotion to that environment
* a list of **included deployments** (changes being promoted) or **reverting deployments** (when promoting to an older version)

Without `--force`, the command prompts for confirmation before proceeding and optionally allows you to enter or override the deployment message interactively.

#### `poly deployments rollback`

Roll back to a previous deployment version. On projects using the new deployment system this rolls Live back. On other projects it rolls back sandbox.

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly deployments rollback --to <deployment_id>
poly deployments rollback --to <deployment_id> --message "Rolling back due to regression"
poly deployments rollback --to <deployment_id> --dry-run
poly deployments rollback --to <deployment_id> --force
```

| Flag | Description |
| - | - |
| `--to` | ID or environment name of the deployment to roll back to. Required. |
| `--message`, `-m` | Optional message to include with the rollback. If not specified, the existing deployment message is used. |
| `--force` | Skip the confirmation prompt. This is the default in non-interactive mode (e.g. when `--json` is used). |
| `--dry-run` | Show what would be rolled back without actually rolling back. Displays the target deployment and the deployments that would be reverted. |
| `--verbose` | Show full error tracebacks for debugging. |

The output includes a list of **reverting deployments** — the versions that will be undone when the rollback completes.

Without `--force`, the command prompts for confirmation before proceeding.

## 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```

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

> [!NOTE]
>
> **`--interactive` and `--json` cannot be used together**
>
> `poly branch merge --interactive` requires a terminal for its conflict-resolution prompts and is incompatible with `--json`.

> [!NOTE]
>
> **`--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`).

### JSON output shapes

The exact fields vary by command. Common fields include:

| Command | Key fields |
| - | - |
| `poly status --json` | `files_with_conflicts`, `modified_files`, `new_files`, `deleted_files` |
| `poly push --json` | `success`, `message`, `dry_run` |
| `poly pull --json` | `success`, `files_with_conflicts` |
| `poly validate --json` | `valid`, `errors` |
| `poly diff --json` | `diffs` |
| `poly revert --json` | `success`, `files_reverted` |
| `poly branch list --json` | `current_branch`, `branches` |
| `poly branch create --json` | `success`, `new_branch_id`, `branch_name` |
| `poly branch switch --json` | `success`, `switched_to`, `dry_run` |
| `poly branch current --json` | `current_branch` |
| `poly branch delete --json` | `success`, `deleted` |
| `poly branch merge --json` | `success`; on conflict: `conflicts`, `errors` |
| `poly format --json` | `success`, `check_only`, `format_errors`, `affected`, `ty_ran`, `ty_returncode`, `ty_timed_out` |
| `poly init --json` | `success`, `root_path` |
| `poly project create --json` | `success`, `root_path` (via init); on error: `success`, `error` |
| `poly chat --json` | `conversations` (array); optional `push` (when `--push` is used) |
| `poly deployments show --json` | `success`, `deployment`, `active_deployment_hashes`, `included_deployments`, `is_rollback` |
| `poly deployments promote --json` | `success`, `from_hash`, `to_env`, `message`, `included_deployments`; `dry_run` when `--dry-run` is used |
| `poly deployments rollback --json` | `success`, `target_hash`, `message`, `reverted_deployments`; `dry_run` when `--dry-run` is used |
| `poly conversations list --json` | `conversations`, `count`, `limit`, `offset` |
| `poly conversations get --json` | full conversation detail object |
| `poly conversations get-audio --json` | `success`, `conversation_id`, `direction`, `redacted`, `output_path`, `size_bytes` |

For `poly branch delete --json`, when a branch that was the current branch is deleted, the response also includes `"switched_to": "main"`.

For `poly branch merge --json`, a successful merge returns `{ "success": true }`. When conflicts or errors are present, the response includes `"conflicts"` and `"errors"` arrays containing the raw conflict and error objects from the platform.

For `poly deployments show --json`, the response includes:

* `deployment` — the full deployment record for the requested version hash.
* `active_deployment_hashes` — a map of environment names to the currently active version hash in each environment.
* `included_deployments` — the list of sandbox deployments included since the predecessor version in the queried environment.
* `is_rollback` — `true` if the deployment is a rollback to an older version.

Error responses always include `{ "success": false, "error": "...", "traceback": "..." }`.

> [!NOTE]
>
> **`init` with `--json` requires explicit flags**
>
> When using `poly init --json`, you must supply `--region`, `--account_id`, and `--project_id` explicitly. Interactive prompts are not supported in JSON mode.

> [!NOTE]
>
> **`poly project create` with `--json` requires explicit flags**
>
> When using `poly project create --json`, you must supply `--region`, `--account_id`, and `--name` explicitly. Interactive prompts are not supported in JSON mode.

#### `poly chat --json` output shape

When `--json` is used with `poly chat`, the command emits a single JSON object when the session ends:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "conversations": [
    {
      "conversation_id": "conv-123",
      "url": "https://...",
      "turns": [
        { "input": null, "response": "Hello! How can I help?", "conversation_ended": false },
        { "input": "What are your hours?", "response": "We are open 9am–5pm.", "conversation_ended": false }
      ]
    }
  ]
}
```

* `conversations` is an array because `/restart` in scripted input produces multiple entries.
* `turns[0]` is always the agent greeting, with `"input": null`.
* If `--push` is also supplied, the output includes a `push` key: `{ "push": { "success": true, "message": "..." } }`.
* If `--functions`, `--flows`, or `--state` are also set, the relevant metadata fields are included in each turn.

#### `poly conversations get-audio --json` output shape

When `--json` is used with `poly conversations get-audio`, the audio is still written to disk and the command emits a JSON summary:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "conversation_id": "KA-123",
  "direction": "combined",
  "redacted": false,
  "output_path": "KA-123.wav",
  "size_bytes": 2000000
}
```

#### `poly deployments promote --json` output shape

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "from_hash": "abc123456xyz",
  "to_env": "pre-release",
  "message": "Release notes here",
  "included_deployments": [...]
}
```

On dry run, `"dry_run": true` is added and `"success"` reflects the pre-flight state without any changes being made. On error, `"success": false` and `"error": "..."` are returned.

#### `poly deployments rollback --json` output shape

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": true,
  "target_hash": "def789012xyz",
  "message": "Rolling back due to regression",
  "reverted_deployments": [...]
}
```

On dry run, `"dry_run": true` is added. On error, `"success": false` and `"error": "..."` are returned.

### `poly push --output-json-commands`

Adds a `commands` array to the JSON output of `poly push`, containing the serialized Agent Studio commands that were staged. Useful for dry-run review and integration testing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly push --json --dry-run --output-json-commands
```

The output will include a `commands` key with each command serialized from its protobuf representation.

### Driving pull/push from a captured projection

The `--from-projection` flag on `pull`, `push`, `init`, and `branch switch` lets you supply a projection JSON directly (as a string or via stdin with `-`) instead of fetching it from the API. This is useful for offline workflows and integration testing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly pull --from-projection - < projection.json
poly push --from-projection '{"topics": [...], ...}'
cat projection.json | poly pull --from-projection -
```

The `--output-json-projection` flag on `pull`, `init`, and `branch switch` includes the projection in the JSON output when `--json` is also set. This lets you capture a projection from one command and feed it into another.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poly pull --json --output-json-projection | jq .projection > proj.json
poly push --from-projection - < proj.json
```

## Working pattern

A typical CLI workflow looks like this:

1. create a new project with `poly project create` or initialize an existing one with `poly init`
2. pull with `poly pull` if needed to refresh local state
3. create or switch to a branch
4. edit files
5. inspect changes with `poly status` and `poly diff`
6. validate with `poly validate`
7. push with `poly push`
8. optionally review with `poly review`
9. test or chat with the agent using `poly chat`
10. browse and debug conversations with `poly conversations list` and `poly conversations get`
11. optionally move the Branch to Staging with `poly branch tag` to test it over a real phone number or widget
12. merge the branch with `poly branch merge '<message>'`; on the new deployment system, merging into `main` publishes the Branch to Live
13. on projects that have not yet moved to the new deployment system, promote to pre-release or live with `poly deployments promote`

> [!NOTE]
>
> **Run commands from the project folder**
>
> ADK commands are expected to be run from within your local project directory. If needed, use the `--path` flag to point to a project explicitly.

## Related pages

> [card] [Build an agent](https://docs.poly.ai/adk/tutorials/build-an-agent.md)
>
> See how the CLI fits into a real workflow.

> [card] [Branch merging](https://docs.poly.ai/adk/reference/branch_merge.md)
>
> Conflict resolution, `--interactive` flow, and `--resolutions` JSON for `poly branch merge`.

> [card] [Tests](https://docs.poly.ai/adk/reference/tests.md)
>
> Write and manage simulated conversation tests in `test_suite/`.

> [card] [Working locally](https://docs.poly.ai/adk/concepts/working-locally.md)
>
> How the CLI fits into the daily edit/push/test loop.