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

# Telnyx Agent CLI

> The Telnyx Agent CLI (@telnyx/agent-cli) provides composite setup commands that take you from an API key to a working capability — SMS, voice, an AI assistant on a phone number — in a single command.

The Telnyx Agent CLI (`@telnyx/agent-cli`, bin `telnyx-agent`) is a command-line tool built for AI agents and for developers who want the shortest path from API key to working capability. Where the [Telnyx CLI](/docs/development/cli) exposes each API resource individually, the Agent CLI ships **composite commands**: one call creates the messaging profile, finds and buys a number, and wires everything together.

## Install

```bash theme={null}
npm install -g @telnyx/agent-cli
export TELNYX_API_KEY="KEY_xxx"
```

Requires Node.js 20+. No separate login step — the CLI reads `TELNYX_API_KEY` from the environment.

## Quick start

```bash theme={null}
# Account health at a glance — balance, numbers, profiles, connections
telnyx-agent status

# Machine-readable list of everything the CLI can do
telnyx-agent capabilities --json

# Zero to sending SMS: creates a profile, buys an SMS-capable number,
# and assigns it — in one command
telnyx-agent setup-sms --json
```

Every command supports `--json` for machine-readable output. `setup-sms`, `setup-voice`, and `setup-verify` are **idempotent**: re-running them reuses the resources they already provisioned instead of buying more (`--force` provisions fresh resources). Other setup commands — `setup-ai`, `setup-10dlc`, `setup-porting` — create new resources on each run, so check for existing resources before repeating them.

## When to use the Agent CLI vs the Telnyx CLI

| Use case                               | Agent CLI (`telnyx-agent`)              | Telnyx CLI (`telnyx`) |
| -------------------------------------- | --------------------------------------- | --------------------- |
| Zero-to-working-capability setup       | ✅ One composite command                 | Multiple commands     |
| AI agents provisioning autonomously    | ✅ Idempotent, `--json`, self-describing | Works, but more steps |
| Fine-grained control over one resource | Limited                                 | ✅ Per-resource CRUD   |
| Exploring the full API surface         | Limited                                 | ✅ Full coverage       |

The two install side by side and share the `TELNYX_API_KEY` environment variable.

## Composite setup commands

| Command           | What it does                                                   |
| ----------------- | -------------------------------------------------------------- |
| `setup-sms`       | Messaging profile + SMS-capable number, purchased and assigned |
| `setup-voice`     | Voice connection + voice-capable number                        |
| `setup-ai`        | AI assistant on a voice-capable phone number                   |
| `setup-verify`    | Verify profile ready to send verification codes                |
| `setup-10dlc`     | 10DLC brand and campaign registration flow                     |
| `setup-whatsapp`  | WhatsApp Business Account wiring and number verification       |
| `setup-iot`       | IoT SIM setup                                                  |
| `setup-porting`   | Portability check + port-in order creation and submission      |
| `setup-wireguard` | WireGuard network and interface                                |

Beyond setup, the CLI covers day-to-day operations — `send-sms`, `call-dial`, `fax-send`, `tts`/`stt`, `rcs-send`, `verify-send`, `fund-account`, and more. `telnyx-agent capabilities --json` returns a machine-readable catalog of API capabilities and selected composite commands — a curated catalog rather than the complete command inventory, so pair it with `telnyx-agent --help` for the full command list.

## For AI agents

If you are an agent (or building one), the fast path is:

1. Get an API key — programmatic signup runbook at [telnyx.com/agent-signup.md](https://telnyx.com/agent-signup.md).
2. `npm install -g @telnyx/agent-cli`
3. `telnyx-agent capabilities --json` to discover what you can do, then run the `setup-*` command for the capability you need.

The machine-readable agent entry point at [telnyx.com/agents/start](https://telnyx.com/agents/start) and the [team-telnyx/ai](https://github.com/team-telnyx/ai) repo's `agent.json` manifest both describe the CLI in structured form.

## Source and issues

The Agent CLI lives in the open-source [team-telnyx/ai](https://github.com/team-telnyx/ai/tree/main/cli) repository — file issues and PRs there.