Dial CLI

dial is the official CLI for Dial — a Communication Stack for AI Agents. It wraps the Dial REST API so you can sign up, provision phone numbers, send SMS, place voice calls handled by an AI voice agent, and stream account 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.

When dial is missing

If dial is not on the PATH (e.g. command -v dial returns nothing, or any dial … invocation errors with "command not found"), do not improvise an install. Fetch the bootstrap instructions and follow them:

curl -fsSL https://getdial.ai/skills.md

That document is the authoritative install + onboarding script. Read it, then execute the steps it specifies (install, dial doctor, dial auth login, dial auth verify-otp, phone verification, dial listen 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:

dial --help                    # all top-level 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, dial local-target add url --help.

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

Onboarding flow

If dial doctor --json reports nextStep other than ready, the user is not yet set up. The full first-time flow is:

dial auth login you@example.com               # email OTP
dial auth verify-otp --code 123456            # verify the email
dial auth register-number +14155550123        # texts a code to the user's phone
dial auth verify-otp --number --code 654321   # verify the phone → writes ~/.local/share/dial/auth.json
dial listen install                           # background daemon for inbound events

Read each step's output — dial auth verify-otp has two outcomes. If the user already had an account, the email step signs them in and you're done (skip to dial listen install). If it reports that a phone number is still required, creating an account needs one: --json sets pendingPhone: true and names auth_register_number/dial auth register-number as the next step, and no API key exists yet.

Ask the user for the phone number — never invent one. It must be able to receive SMS, it should be one the user keeps, and a Dial number is refused. Re-run dial auth register-number with the same number to resend the code, or with a different one to fix a typo before verifying.

A new number starts with a default inbound voice-agent prompt — the system prompt the AI uses on calls to your number. Change it with dial number set <number> --inbound-instruction "...".

dial auth verify-otp also installs a Dial skill into your agent's config (claude-code, cursor, codex, opencode, pi, openclaw, nanoclaw, hermes) when you pass --agent <name> — including on the email step when a phone number is still pending, so you keep the instructions needed to finish.

dial listen install needs a user service supervisor (launchd on macOS, systemd --user on Linux). In sandboxes / containers / CI without one it can't run — dial auth verify-otp detects this and says so. Inbound events still work without it: dial wait-for long-polls the API when the daemon isn't running.

The account also has a web dashboard at https://getdial.ai/dashboard — dial auth verify-otp prints the link and which address signs in, so pass that along. Almost everything is a dial verb, though: only billing changes (dial billing reads), team sharing, and carrier (10DLC) registration need the browser.

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:

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 'webhook'
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 (after grep found a hit, or because you need fuller context), use the sitemap to discover URLs, then fetch the .md companion of any page — it's the same content as the HTML page but in plain markdown, faster to read and friendlier to scan.

# 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 documentation page at https://docs.getdial.ai/<path> has a markdown twin at https://docs.getdial.ai/<path>.md. Use the .md version whenever you're reading docs from inside an agent.

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 just signposts.

• Send an SMS — dial message --to +14155550123 --body "..." (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)
• 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). Free accounts (no top-up or subscription yet) are capped at 5 minutes per call and 2 concurrent calls — a call over the concurrency limit is rejected with 429 call_limit_reached, and passing --max-duration above 300 is rejected with 400 rather than shortened (a cap inherited from the number or account is clamped instead). Both limits lift on the first top-up or subscription (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 (pay-as-you-go only; provisioned asynchronously — poll dial number list until ready) (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; set it at dial number purchase time and change it here. 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)
• Set an iMessage number's display identity — dial number set +14155550123 --first-name Maya --last-name Chen --avatar ./photo.png sets the name and photo shown beside the number's messages in recipients' Messages apps (iMessage numbers only; other numbers reject these flags with 400). --avatar takes a local image file (jpeg/png/gif/webp, max 5 MB — uploaded) or a public image URL (fetched server-side); the photo can be replaced but not removed. --first-name "" / --last-name "" clear a name (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)
• Confirm a message was delivered, or catch a carrier rejection — dial wait-for message.status_changed -f messageId=<id>, or -f deliveryState=failed to watch for rejections. Sending only tells you Dial accepted the message; this is how you learn what the carrier did with it. Delivery and reads are separate fields: deliveryState runs pending → delivered/undelivered/failed (and is unconfirmed on iMessage numbers, which report no delivery receipts), while readState runs unread → read (and is unsupported on SMS, which never reports reads — don't wait for one). A failure carries a plain-language deliveryError (message-status-changed.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 (stream-account-events.md)
• Fan inbound events to a local handler — dial local-target add cmd /path/to/handler or dial local-target add url http://127.0.0.1:8787/dial (local-url-target.md, cli-command-target.md)

Conventions

• --json everywhere for parseable output.
• --from-number <id|E.164|nickname> picks the number to act from flexibly; the legacy --from-number-id <id> takes an id only (use one or the other). Both default to the number Dial auto-provisioned when the account was created. List others with dial number list.
• Phone numbers are E.164 (+14155550123). Reject anything else before calling Dial.
• Writes (message, call, number purchase) are not idempotent — on an ambiguous failure, list first to check before retrying.
• The local API key lives at ~/.local/share/dial/auth.json (mode 0600). The CLI reads it automatically; never echo it back to the user or paste it into responses.