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

# CLI

`telnyx-acp` is the command line of the Agent Control Plane. One page per verb follows, grouped as `telnyx-acp --help` groups them, and `telnyx-acp <verb> --help` prints the same for one verb.

Every verb but `chat` and `logs --tail` takes `--json` and answers one envelope, `{ ok: true, command, data }` or `{ ok: false, command, error: { code, message, hint?, detail? } }`. On a terminal the output is coloured, headlines carry an emoji, and a verb that waits on the platform shows a spinner with the elapsed time. Piped, under `--json`, with `NO_COLOR` set, with `TERM=dumb`, in CI, or with `TELNYX_ACP_PLAIN=1`, it is the same text with nothing added, so scripts see stable bytes. On a terminal a verb ends with one line on stderr when a newer release of the CLI exists ([update](https://developers.telnyx.com/docs/agents/cli/utilities.md#update)); the check is off under `--json`, off a terminal, in CI, after `update` and `export`, and with `TELNYX_ACP_NO_UPDATE_CHECK=1`.

Verbs that act on the platform need a session from `login` or `TELNYX_API_KEY`, and check before doing any work. Verbs that act on a project run in the project directory, where `agent.json` is.

## The Verbs

| Group | Verb | Does |
| - | - | - |
| Project Lifecycle | [create](https://developers.telnyx.com/docs/agents/cli/create.md) | Scaffold a project. No flags opens the wizard. |
| | [dev](https://developers.telnyx.com/docs/agents/cli/dev.md) | Run the agent on this machine. |
| | [deploy](https://developers.telnyx.com/docs/agents/cli/deploy.md) | Generate `.telnyx/`, ship it, set up the channels, print the addresses. |
| | [invoke](https://developers.telnyx.com/docs/agents/cli/invoke.md) | One turn against the deployed agent. |
| | [eval](https://developers.telnyx.com/docs/agents/cli/eval.md) | Run the saved test conversations in `evals/` and score each reply. |
| | [chat](https://developers.telnyx.com/docs/agents/cli/chat.md) | A conversation that stays open in the terminal. |
| | [text](https://developers.telnyx.com/docs/agents/cli/text.md) | One SMS to the agent's number from one of the account's, the reply printed. |
| | [rpc](https://developers.telnyx.com/docs/agents/cli/rpc.md) | Call one `@rpc` method on an instance. |
| Resources | [add](https://developers.telnyx.com/docs/agents/cli/add.md) | Add a phone number, an email inbox, the browser page, a channel, a tool or a secret. No arguments reopens the wizard. |
| | [remove](https://developers.telnyx.com/docs/agents/cli/remove.md) | Remove one of those. |
| | [set](https://developers.telnyx.com/docs/agents/cli/set.md) | Change one field of `agent.json`. |
| | [unset](https://developers.telnyx.com/docs/agents/cli/unset.md) | Remove one field of `agent.json`, back to its default. |
| | [tools](https://developers.telnyx.com/docs/agents/cli/tools.md) | The agent's tools as the model sees them; `--refresh` lists each MCP server's tools again. |
| Observe | [status](https://developers.telnyx.com/docs/agents/cli/status.md) | The deployment, the channels, the address. |
| | [logs](https://developers.telnyx.com/docs/agents/cli/logs.md) | Runtime or invocation logs. |
| | [traces](https://developers.telnyx.com/docs/agents/cli/traces.md) | A conversation's recent runs, or one run's steps: model calls, tool calls, timings and tokens. |
| | [versions](https://developers.telnyx.com/docs/agents/cli/versions.md) | The immutable revisions. |
| | [rollback](https://developers.telnyx.com/docs/agents/cli/rollback.md) | Point traffic at an earlier revision. The platform refuses it today for every agent this CLI deploys; the verb prints how to redeploy that revision instead. |
| Lifecycle | [delete](https://developers.telnyx.com/docs/agents/cli/delete.md) | Restore the webhooks, release what `deploy` set up, delete the function and the actor type. |
| | [export](https://developers.telnyx.com/docs/agents/cli/export.md) | Configuration to code, under `src/`. |
| Utilities | [numbers, models, login, validate, update](https://developers.telnyx.com/docs/agents/cli/utilities.md) | The account's numbers and models, sign-in, validation, and the CLI's own update from its releases. |

> [!WARNING]
>
> **Beta.** `list` is not available yet. See [Beta Limitations](https://developers.telnyx.com/docs/agents/deploy-and-operate.md#beta-limitations).

## Exit Codes

| Code | Meaning |
| - | - |
| 0 | ok |
| 1 | the verb ran and failed (a platform error, a failed ship); the first line is the reason |
| 2 | usage: unknown verb, missing required option |
| 3 | `telnyx-edge` missing or older than 0.5.7 |
| 4 | not signed in and no `TELNYX_API_KEY`, or a session that expired and could not be renewed |
| 5 | the verb is reserved for a later stage |