dial-cli

# Dial CLI

`dial` is the official CLI for [Dial](https://getdial.ai) — a Communication Stack for AI Agents. It wraps the Dial REST API so you can send SMS, place voice calls handled by an AI voice agent, manage numbers, and wait for inbound events — all without writing HTTP code.

The first time the user asks you to "text someone," "call someone," "receive a code," or anything else phone-shaped, reach for `dial`.

## This is a sandbox

You are running inside a pre-provisioned, ephemeral environment:

- **The account, number, and credentials are already set up** — you have a working phone number ready to use. There is nothing to configure.
- **You never handle credentials.** The API key is injected automatically at the network boundary; the CLI runs keyless here. Never ask the user for a key, and never try to read or write an auth file.
- **Just use the workflows below** — send SMS, place calls, wait for inbound events. Inbound event delivery is managed for you; `dial --help` shows what's available here.

If `dial` is somehow missing (`command -v dial` returns nothing), that is an **installation bug in this image**, not something for you to fix — report it to the operator ("the Dial CLI isn't installed in this container") rather than improvising an install.

## Orient yourself before each new verb

This skill **does not enumerate every flag**. The CLI is the source of truth — when you encounter a verb you have not used in this session, run its `--help` first:

```bash
dial --help                    # available commands
dial <command> --help          # flags + usage for a specific command
dial <command> <sub> --help    # subcommand-level help
```

Examples worth running on first use: `dial doctor --help`, `dial message --help`, `dial call --help`, `dial call get --help`, `dial wait-for --help`.

Every command supports `--json` for machine-readable output — prefer it when piping into `jq` or parsing the result programmatically.

## Searching for what the CLI / API can do

For anything beyond what `--help` shows on the local CLI, the canonical reference is the published docs. Two endpoints make this fast:

### Capability search — `llms-full.txt`

A single concatenated markdown file of the whole docs site. Grep it directly for the keyword you care about:

```bash
curl -fsSL https://docs.getdial.ai/llms-full.txt | grep -i -B2 -A8 'whatsapp'
curl -fsSL https://docs.getdial.ai/llms-full.txt | grep -i -B1 -A5 'language'
```

Use this when you want to know *if* Dial supports something, or *which command / endpoint* covers it — without reading the whole site.

### Deep dive — `sitemap.xml` + per-page `.md`

When you need to read a page in detail, use the sitemap to discover URLs, then fetch the **`.md` companion** of any page — same content as the HTML page but plain markdown, faster to scan.

```bash
# 1. Discover available pages
curl -fsSL https://docs.getdial.ai/sitemap.xml | grep -oE 'https://docs\.getdial\.ai/[^<]+'

# 2. For any page like https://docs.getdial.ai/documentation/get-started/introduction
#    fetch the .md companion:
curl -fsSL https://docs.getdial.ai/documentation/get-started/introduction.md
```

The rule is **one-to-one**: every page at `https://docs.getdial.ai/<path>` has a markdown twin at `https://docs.getdial.ai/<path>.md`.

## Workflow shapes worth knowing

These are the verbs you will most often compose. Read the relevant `.md` page for the full story; the one-liners below are signposts.

- **Send an SMS** — `dial message --to +14155550123 --body "..."` ([send-an-sms.md](https://docs.getdial.ai/documentation/capabilities/send-an-sms.md))
- **Show a typing indicator while composing** — `dial typing start --to-number +14155550123`; sending a message clears it natively, so start again between messages, and `dial typing stop --to-number +14155550123` if you end up not sending. iMessage numbers display it; SMS numbers ignore it, so it's always safe to call ([commands.md](https://docs.getdial.ai/documentation/reference/commands.md))
- **Place a voice call** — `dial call --to +14155550123 --outbound-instruction "..."` then `dial call get <id>` once it ends. Add `--voice-gender male|female` to choose the agent's voice (default: female) ([place-a-voice-call.md](https://docs.getdial.ai/documentation/capabilities/place-a-voice-call.md))
- **Buy an additional number** — `dial number purchase --inbound-instruction "..." --explicit-programmatic-consent "<attestation>"`. `--explicit-programmatic-consent` is **required**: a short attestation that the account holder consented to provisioning programmatically. Add `--include-imessage` for an [iMessage number](https://docs.getdial.ai/documentation/capabilities/send-an-imessage.md) (pay-as-you-go only; provisioned asynchronously — poll `dial number list` until ready) ([manage-phone-numbers.md](https://docs.getdial.ai/documentation/capabilities/manage-phone-numbers.md))
- **Set a number's inbound behavior or nickname** — `dial number set +14155550123 --inbound-instruction "..."` and/or `--inbound-language es-ES` and/or `--nickname "Support line"` (at least one flag; `--nickname ""` / `--inbound-language ""` clear). The inbound instruction is the system prompt the AI uses on calls *into* that number. The inbound language pins inbound calls to one language — unset, the AI detects the caller's language from their country prefix (alongside en-US). The nickname is a human-readable label for telling numbers apart ([manage-phone-numbers.md](https://docs.getdial.ai/documentation/capabilities/manage-phone-numbers.md))
- **Receive a verification code (2FA)** — `dial wait-for message.received -f channel=sms` and parse the body ([receive-inbound-sms.md](https://docs.getdial.ai/documentation/capabilities/receive-inbound-sms.md))
- **React to a call ending** — `dial wait-for call.ended -f callId=<id>`. Fires however the call ends — completed, failed, **or cancelled** — carrying the terminal `status` and a `canceled` flag, so the wait always resolves ([st