@palmyr/cli 1.6.0 → 1.7.0

package/README.md

@@ -118,14 +118,46 @@ palmyr wallet create --name agent-prod
 
 # Managed: prints a setup link to send to a human
 palmyr wallet create --name treasury --managed
+
+# Single-chain: skip the other chain's account
+palmyr wallet create --name sol-only --solana
+palmyr wallet create --name base-only --base
 ```
 
+By default a wallet derives both Solana and Base/EVM accounts. Pass `--solana` or `--base` (not both) to materialize only one side. The mnemonic always derives both — `--solana` / `--base` controls *which addresses are surfaced and stored*, not which keys exist cryptographically.
+
 The managed flow returns a one-time URL. The recipient opens it in a browser, registers a WebAuthn passkey, and sets spending limits. From that point on, transactions inside the limit sign instantly; transactions over the limit emit an `approvalUrl` that the human visits to authenticate and approve.
 
+### Bulk creation with tags
+
+Group many wallets under one folder-like tag, then cascade-delete them together when done — ideal for spinning up demo, agent-cohort, or test wallets:
+
+```bash
+# Create 100 unmanaged wallets sharing one tag (~7s on Windows, batched DPAPI seal)
+palmyr wallet create --tag palmyr-demo --count 100
+
+# Custom name prefix; defaults to the tag if omitted → wallets named bot-001..bot-050
+palmyr wallet create --tag agents --count 50 --name-prefix bot
+
+# List, retag, untag
+palmyr wallet list --tag palmyr-demo
+palmyr wallet tag <WALLET_ID> palmyr-demo       # assign / change
+palmyr wallet tag <WALLET_ID> --clear           # remove
+palmyr wallet tags                              # all tags + counts + chains
+
+# Cascade-delete every wallet under a tag (vault file + OS-credential-store secret)
+palmyr wallet tag-delete palmyr-demo --confirm
+```
+
+Bulk-create is unmanaged-only (managed wallets need per-wallet passkey setup) and capped at 500 per call. Names auto-suffix `-001..-N` with zero-padding based on count width.
+
 ### Importing an existing seed
 
 ```bash
 palmyr wallet import --mnemonic "twelve word seed phrase ..." --name imported
+
+# Same chain / tag flags as create
+palmyr wallet import --mnemonic "..." --name from-backup --tag restored --solana
 ```
 
 ### Exporting a seed
@@ -377,10 +409,13 @@ All wallet operations except `addresses`, `api-key`, `config`, and `request-appr
 
 | Command | Network | Notes |
 |---|---|---|
-| `palmyr wallet create [--name N] [--managed]` | local *(server only if `--managed`)* | New wallet. Stores session secret in OS credential store. |
-| `palmyr wallet import --mnemonic "..." [--name N] [--managed]` | local | Restore from BIP-39. |
-| `palmyr wallet list` | local | Lists wallets in the local vault. |
-| `palmyr wallet info <ID>` | local | Show one wallet (id, name, addresses, mode). |
+| `palmyr wallet create [--name N] [--managed] [--solana\|--base] [--tag T] [--count N] [--name-prefix P]` | local *(server only if `--managed`)* | New wallet. Stores session secret in OS credential store. `--count > 1` bulk-creates N unmanaged wallets under a required `--tag` (max 500/call, batched DPAPI seal on Windows). `--solana` / `--base` materializes only one chain. |
+| `palmyr wallet import --mnemonic "..." [--name N] [--managed] [--solana\|--base] [--tag T]` | local | Restore from BIP-39. Same chain / tag flags as `create`. |
+| `palmyr wallet list [--tag T]` | local | Lists wallets in the local vault. `--tag` filters to one folder. |
+| `palmyr wallet info <ID>` | local | Show one wallet (id, name, addresses, mode, tag). |
+| `palmyr wallet tags` | local | List all tags with wallet count, chains, and date range. |
+| `palmyr wallet tag <ID> <TAG>` / `palmyr wallet tag <ID> --clear` | local | Assign, change, or clear a wallet's tag. |
+| `palmyr wallet tag-delete <TAG> --confirm` | local | Cascade-delete every wallet under the tag (vault file + OS-credential-store secret). Requires explicit `--confirm`. |
 | `palmyr wallet addresses <ID>` | API | Server-side derived addresses (multi-chain). |
 | `palmyr wallet sign-message <ID> --chain solana\|evm --msg "..."` | local | Sign an arbitrary message offline. |
 | `palmyr wallet api-key <ID> [--name N]` | API | Mint an agent API key bound to the wallet. |

package/dist/cli.js

@@ -377,6 +377,327 @@ const WALLET_HELP = {
         { flag: '--dst-decimals <n>', desc: 'Dest token decimals', hint: 'default 6 (USDC-like)' },
     ],
 };
+const PHONE_HELP = {
+    search: [
+        { flag: '--country <ISO>', desc: 'Country code', hint: 'default US (e.g. US, GB, AE)' },
+        { flag: '--limit <N>', desc: 'Max results to return' },
+        { flag: '(price)', desc: 'Free — no payment required' },
+        { flag: '(example)', desc: 'palmyr phone search --country US --json' },
+    ],
+    buy: [
+        { flag: '--country <ISO>', desc: 'Country code (required)', hint: 'e.g. US, GB' },
+        { flag: '--area <code>', desc: 'Preferred area code (optional, US only)' },
+        { flag: '(price)', desc: '$3.00 per number provisioned' },
+        { flag: '(example)', desc: 'palmyr phone buy --country US' },
+    ],
+    sms: [
+        { flag: '--id <PHONE_ID>', desc: 'Source phone number id (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number (required)', hint: 'e.g. +15551234567' },
+        { flag: '--body <text>', desc: 'Message body (required)' },
+        { flag: '(price)', desc: '$0.05 per SMS sent' },
+        { flag: '(example)', desc: 'palmyr phone sms --id PN_abc --to +15551234567 --body "hi"' },
+    ],
+    call: [
+        { flag: '--id <PHONE_ID>', desc: 'Source phone number id (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number (required)' },
+        { flag: '--tts <text>', desc: 'Text-to-speech to play on answer (optional)' },
+        { flag: '(price)', desc: '$0.10 per call placed' },
+        { flag: '(example)', desc: 'palmyr phone call --id PN_abc --to +15551234567 --tts "hello"' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List phone numbers owned by your wallet' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr phone list --json' },
+    ],
+    messages: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to read SMS for (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr phone messages --id PN_abc' },
+    ],
+    calls: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to list calls for (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr phone calls --id PN_abc' },
+    ],
+    release: [
+        { flag: '--id <PHONE_ID>', desc: 'Phone number id to release (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.01 per release (stops monthly Telnyx billing)' },
+        { flag: '(example)', desc: 'palmyr phone release --id PN_abc' },
+    ],
+    'call-info': [
+        { flag: '--call <CALL_ID>', desc: 'Call control id (required; --id and positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per lookup' },
+        { flag: '(example)', desc: 'palmyr phone call-info --call CC_abc' },
+    ],
+    speak: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--text <text>', desc: 'TTS text to speak (required; --tts alias accepted)' },
+        { flag: '--voice <name>', desc: 'TTS voice (optional, provider default otherwise)' },
+        { flag: '--language <code>', desc: 'TTS language code (optional, e.g. en-US)' },
+        { flag: '(price)', desc: '$0.08 per speak action' },
+        { flag: '(example)', desc: 'palmyr phone speak --call CC_abc --text "please hold"' },
+    ],
+    play: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--url <audio_url>', desc: 'Public audio URL to play (required; --audio-url alias accepted)' },
+        { flag: '(price)', desc: '$0.08 per playback' },
+        { flag: '(example)', desc: 'palmyr phone play --call CC_abc --url https://example.com/hold.mp3' },
+    ],
+    dtmf: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--digits <seq>', desc: 'DTMF digit sequence (required; positional also accepted)', hint: 'e.g. "1234#"' },
+        { flag: '(price)', desc: '$0.02 per DTMF send' },
+        { flag: '(example)', desc: 'palmyr phone dtmf --call CC_abc --digits "1234#"' },
+    ],
+    gather: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--min-digits <N>', desc: 'Minimum digits to collect (optional)' },
+        { flag: '--max-digits <N>', desc: 'Maximum digits to collect (optional)' },
+        { flag: '--timeout <ms>', desc: 'Per-input timeout in milliseconds (optional)' },
+        { flag: '--terminating-digit <d>', desc: 'Digit that ends collection (optional, e.g. "#")' },
+        { flag: '--prompt <text>', desc: 'Optional TTS prompt to play before gathering' },
+        { flag: '--prompt-voice <name>', desc: 'TTS voice for the prompt (optional)' },
+        { flag: '(price)', desc: '$0.08 per gather action' },
+        { flag: '(example)', desc: 'palmyr phone gather --call CC_abc --max-digits 4 --terminating-digit "#" --prompt "Enter PIN"' },
+    ],
+    record: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--format <fmt>', desc: 'Recording format (optional, provider default otherwise)' },
+        { flag: '(price)', desc: '$0.10 per record start' },
+        { flag: '(example)', desc: 'palmyr phone record --call CC_abc --format mp3' },
+    ],
+    'record-stop': [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '(price)', desc: '$0.02 per stop' },
+        { flag: '(example)', desc: 'palmyr phone record-stop --call CC_abc' },
+    ],
+    hangup: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '(price)', desc: '$0.02 per hangup' },
+        { flag: '(example)', desc: 'palmyr phone hangup --call CC_abc' },
+    ],
+    answer: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of an inbound call (required)' },
+        { flag: '(price)', desc: '$0.02 per answer' },
+        { flag: '(example)', desc: 'palmyr phone answer --call CC_abc' },
+    ],
+    transfer: [
+        { flag: '--call <CALL_ID>', desc: 'Call control id of a live call (required)' },
+        { flag: '--to <+E.164>', desc: 'Destination phone number to bridge into (required)' },
+        { flag: '(price)', desc: '$0.10 per transfer' },
+        { flag: '(example)', desc: 'palmyr phone transfer --call CC_abc --to +15557654321' },
+    ],
+};
+const EMAIL_HELP = {
+    create: [
+        { flag: '--name <name>', desc: 'Inbox name (required)' },
+        { flag: '--domain <domain>', desc: 'Wallet-owned domain to host the inbox on (optional)', hint: 'default: Palmyr-hosted domain' },
+        { flag: '--wallet <id|name>', desc: 'Wallet to own the inbox (optional)' },
+        { flag: '(price)', desc: '$2.00 per inbox provisioned' },
+        { flag: '(example)', desc: 'palmyr email create --name agent --domain example.com' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List inboxes owned by your wallet' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr email list --json' },
+    ],
+    status: [
+        { flag: '<domain>', desc: 'Domain to check (positional or --domain)', hint: 'e.g. example.com' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr email status example.com' },
+    ],
+    register: [
+        { flag: '<domain>', desc: 'Wallet-owned domain to (re-)register with Mailgun (positional or --domain)' },
+        { flag: '(price)', desc: '$0.05 per registration' },
+        { flag: '(example)', desc: 'palmyr email register example.com' },
+    ],
+    read: [
+        { flag: '--id <INBOX_ID>', desc: 'Inbox id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr email read --id INB_abc123' },
+    ],
+    send: [
+        { flag: '--id <INBOX_ID>', desc: 'Source inbox id (required)' },
+        { flag: '--to <addr>', desc: 'Destination email (required)' },
+        { flag: '--subject <text>', desc: 'Subject line (required)' },
+        { flag: '--body <text>', desc: 'Message body (required)' },
+        { flag: '(price)', desc: '$0.08 per email sent' },
+        { flag: '(example)', desc: 'palmyr email send --id INB_abc --to user@x.com --subject Hi --body "..."' },
+    ],
+    threads: [
+        { flag: '--id <INBOX_ID>', desc: 'Inbox id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.02 per call' },
+        { flag: '(example)', desc: 'palmyr email threads --id INB_abc123' },
+    ],
+};
+const COMPUTE_HELP = {
+    plans: [
+        { flag: '--location <loc>', desc: 'Filter to types deployable in this datacenter (optional)', hint: 'e.g. fsn1, nbg1, hel1, ash, hil' },
+        { flag: '(price)', desc: 'Free — live discovery from Hetzner' },
+        { flag: '(example)', desc: 'palmyr compute plans --location fsn1 --json' },
+    ],
+    locations: [
+        { flag: '(no args)', desc: 'List Hetzner datacenters + per-location server-type availability' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'install-recipes': [
+        { flag: '(no args)', desc: 'List available agent install recipes (hermes, openclaw, …)' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'ssh-key': [
+        { flag: 'add <pubkey-file>', desc: 'Upload a key to Hetzner', hint: '[--name "label"]' },
+        { flag: 'list', desc: 'List uploaded Hetzner SSH keys' },
+        { flag: 'delete <id>', desc: 'Remove a Hetzner SSH key' },
+        { flag: '(price)', desc: 'add $0.10 · list $0.01 · delete $0.01' },
+    ],
+    deploy: [
+        { flag: '--type <name>', desc: 'Hetzner server type', hint: 'default cx23' },
+        { flag: '--name <name>', desc: 'Server name', hint: 'default agent-<timestamp>' },
+        { flag: '--location <loc>', desc: 'Hetzner datacenter (optional)', hint: 'e.g. fsn1, nbg1' },
+        { flag: '--install <recipes>', desc: 'Comma-separated install recipes', hint: 'e.g. hermes,openclaw' },
+        { flag: '--no-install', desc: 'Skip cloud-init entirely (vanilla Ubuntu)' },
+        { flag: '--generate-ssh-key', desc: 'GOLDEN PATH (default): generate a fresh keypair locally' },
+        { flag: '--pubkey-file <path>', desc: 'Use an existing public key from disk' },
+        { flag: '--pubkey "ssh-..."', desc: 'Use an inline public key string' },
+        { flag: '--ssh-key <id>', desc: 'Numeric Hetzner key id (already uploaded)' },
+        { flag: '--no-wait', desc: 'Return immediately instead of waiting for SSH-ready' },
+        { flag: '--wait-timeout <s>', desc: 'Override readiness timeout (30–900s)' },
+        { flag: '(price)', desc: '$6.00 per deploy (Hetzner billing flows through)' },
+        { flag: '(example)', desc: 'palmyr compute deploy --type cx23 --install hermes' },
+    ],
+    wait: [
+        { flag: '<name|id>', desc: 'Server (positional, name or numeric id)' },
+        { flag: '--install <recipes>', desc: 'Also gate on the install marker file (e.g. hermes)' },
+        { flag: '--key <path>', desc: 'Path to the private key for SSH verification' },
+        { flag: '--wait-timeout <s>', desc: 'Override readiness timeout (30–900s)' },
+        { flag: '(price)', desc: '$0.01 per readiness poll (server status check)' },
+        { flag: '(example)', desc: 'palmyr compute wait my-vps --install hermes' },
+    ],
+    ssh: [
+        { flag: '<name|id>', desc: 'Server (positional)' },
+        { flag: '(price)', desc: 'Free — local cache lookup only' },
+        { flag: '(example)', desc: 'palmyr compute ssh my-vps' },
+    ],
+    exec: [
+        { flag: '<name|id> -- <cmd> [args...]', desc: 'Run a one-shot command via Palmyr SSH bridge' },
+        { flag: '--timeout <s>', desc: 'Command timeout (1–120s)' },
+        { flag: '(price)', desc: '$0.05 per command' },
+        { flag: '(example)', desc: 'palmyr compute exec my-vps -- systemctl status openclaw' },
+    ],
+    rename: [
+        { flag: '<name|id> <new-name>', desc: 'Rename server (metadata-only, no reboot)' },
+        { flag: '(price)', desc: '$0.01 per rename' },
+    ],
+    'reset-password': [
+        { flag: '<name|id>', desc: 'Rotate the root password (Hetzner-side)' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    console: [
+        { flag: '<name|id>', desc: 'Get a noVNC console URL (break-glass)' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    reboot: [
+        { flag: '<name|id>', desc: 'Reboot the server' },
+        { flag: '(price)', desc: '$0.10 per action' },
+    ],
+    'setup-ssh': [
+        { flag: '--id <SERVER_ID>', desc: 'Server id (required; positional also accepted)' },
+        { flag: '--pubkey-file <path>', desc: 'Public key file to inject' },
+        { flag: '--pubkey "ssh-..."', desc: 'Inline public key string' },
+        { flag: '(price)', desc: '$0.01 per call' },
+        { flag: '(example)', desc: 'palmyr compute setup-ssh --id 12345 --pubkey-file ~/.ssh/id_ed25519.pub' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List your deployed servers' },
+        { flag: '(price)', desc: '$0.01 per call' },
+    ],
+    delete: [
+        { flag: '--id <SERVER_ID>', desc: 'Server id (required; positional also accepted)' },
+        { flag: '(price)', desc: '$0.10 per deletion (Hetzner billing stops on confirm)' },
+    ],
+};
+const DOMAIN_HELP = {
+    check: [
+        { flag: '--name <domain>', desc: 'Domain or root name (positional also accepted)' },
+        { flag: '(price)', desc: 'Free — availability lookup only' },
+        { flag: '(example)', desc: 'palmyr domain check example.dev' },
+    ],
+    pricing: [
+        { flag: '--name <root>', desc: 'Root name to price across TLDs (positional also accepted)' },
+        { flag: '(price)', desc: 'Free' },
+        { flag: '(example)', desc: 'palmyr domain pricing example' },
+    ],
+    buy: [
+        { flag: '--name <domain>', desc: 'Fully-qualified domain (required, e.g. example.dev)' },
+        { flag: '(price)', desc: 'Dynamic — registrar cost × 1.25 markup (charged via x402)' },
+        { flag: '(example)', desc: 'palmyr domain buy --name example.dev' },
+    ],
+    list: [
+        { flag: '(no args)', desc: 'List domains owned or shared with your wallet' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    dns: [
+        { flag: '--name <domain>', desc: 'Domain to read DNS for (positional also accepted)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    'transfer-ownership': [
+        { flag: '--name <domain>', desc: 'Domain to transfer (required)' },
+        { flag: '--to <wallet>', desc: 'Recipient wallet address (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    share: [
+        { flag: '--name <domain>', desc: 'Domain to share (required)' },
+        { flag: '--with <wallet>', desc: 'Wallet to grant shared access (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+    unshare: [
+        { flag: '--name <domain>', desc: 'Domain to revoke from (required)' },
+        { flag: '--from <wallet>', desc: 'Wallet to revoke (required)' },
+        { flag: '(price)', desc: '$0.0001 ownership-proof micro-payment' },
+    ],
+};
+const CHAT_HELP = {
+    run: [
+        { flag: '"<intent>"', desc: 'Plain-string intent (positional or --intent)' },
+        { flag: '--budget <USDC>', desc: 'Max spend cap (required, positive USDC)' },
+        { flag: '--quality <q>', desc: 'Quality tier', hint: 'fast | cheap | best (default best)' },
+        { flag: '--execute', desc: 'Auto-execute the plan once generated' },
+        { flag: '--auto-approve-under <USDC>', desc: 'Skip approval prompts for steps cheaper than this' },
+        { flag: '(price)', desc: '$0.10 orchestration fee + sum of per-step costs (capped by --budget)' },
+        { flag: '(example)', desc: 'palmyr chat run "launch a sneaker brand" --budget 50' },
+    ],
+    resume: [
+        { flag: '<session_id>', desc: 'Existing session id (positional)' },
+        { flag: '"<follow-up>"', desc: 'Follow-up intent (positional remainder or --intent)' },
+        { flag: '--approve', desc: 'Approve a previously-generated plan' },
+        { flag: '--plan-id <id>', desc: 'Plan id to approve (pair with --approve)' },
+        { flag: '--budget <USDC>', desc: 'Override session budget (default $20)' },
+        { flag: '--execute', desc: 'Auto-execute the new plan' },
+        { flag: '(price)', desc: '$0.10 orchestration fee per new plan + per-step costs' },
+        { flag: '(example)', desc: 'palmyr chat resume sess_abc "now post 3 videos"' },
+    ],
+    status: [
+        { flag: '<session_id>', desc: 'Session id (positional)' },
+        { flag: '(price)', desc: 'Free — session inspection' },
+    ],
+    cancel: [
+        { flag: '<session_id>', desc: 'Session id (positional)' },
+        { flag: '(price)', desc: 'Free — halts execution and refunds remaining escrow' },
+    ],
+    sessions: [
+        { flag: '(no args)', desc: 'List your active i402 sessions' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    capabilities: [
+        { flag: '(no args)', desc: 'List canonical capability classes (e.g. web_search, mint_nft)' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    providers: [
+        { flag: '--capability <name>', desc: 'Filter providers by capability (optional)' },
+        { flag: '(price)', desc: 'Free' },
+        { flag: '(example)', desc: 'palmyr chat providers --capability web_search' },
+    ],
+};
 /**
  * Render a per-command menu (no subcommand given). On a TTY → Ink MenuScreen
  * with the Palmyr aesthetic. In agent mode → flat JSON listing the available
@@ -673,7 +994,7 @@ async function main() {
                 break;
             }
             case 'phone': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !PHONE_HELP[subcommand])) {
                     showMenu({
                         command: 'phone',
                         title: 'phone',
@@ -682,13 +1003,31 @@ async function main() {
                         commands: [
                             { name: 'search', description: 'Search available numbers', hint: '--country US' },
                             { name: 'buy', description: 'Buy a phone number', hint: '--country US' },
+                            { name: 'list', description: 'List numbers owned by your wallet' },
+                            { name: 'release', description: 'Release a phone number', hint: '--id PHONE_ID' },
                             { name: 'sms', description: 'Send an SMS', hint: '--id ID --to +1... --body "hi"' },
+                            { name: 'messages', description: 'Read SMS messages received on a number', hint: '--id PHONE_ID' },
                             { name: 'call', description: 'Place a voice call', hint: '--id ID --to +1... --tts "hello"' },
+                            { name: 'calls', description: 'List calls placed/received on a number', hint: '--id PHONE_ID' },
+                            { name: 'call-info', description: 'Get details on a single call', hint: '--call CALL_CONTROL_ID' },
+                            { name: 'speak', description: 'TTS into a live call', hint: '--call ID --text "..." [--voice V]' },
+                            { name: 'play', description: 'Play an audio URL into a live call', hint: '--call ID --url https://...' },
+                            { name: 'dtmf', description: 'Send DTMF tones to a live call', hint: '--call ID --digits "1234#"' },
+                            { name: 'gather', description: 'Collect DTMF input from caller', hint: '--call ID [--min-digits N --max-digits N --timeout MS --prompt "..."]' },
+                            { name: 'record', description: 'Start recording a live call', hint: '--call ID [--format mp3]' },
+                            { name: 'record-stop', description: 'Stop recording a live call', hint: '--call ID' },
+                            { name: 'hangup', description: 'End a live call', hint: '--call ID' },
+                            { name: 'answer', description: 'Answer an inbound call', hint: '--call ID' },
+                            { name: 'transfer', description: 'Transfer a live call to another number', hint: '--call ID --to +1...' },
                         ],
                         fromHome,
                     });
                     break;
                 }
+                if (flags.help && subcommand && PHONE_HELP[subcommand]) {
+                    subcommandHelp('phone', subcommand, PHONE_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'search': {
                         const country = flags.country || 'US';
@@ -757,12 +1096,130 @@ async function main() {
                         render(React.createElement(SuccessScreen, { version: VERSION, title: 'calling', subtitle: to, details: [{ label: 'To', value: to }, { label: 'Call ID', value: data.callControlId || data.id || '' }], footerLeft: 'Call initiated' }));
                         break;
                     }
-                    default: err(`Unknown phone command: ${subcommand}. Try: search, buy, sms, call`);
+                    case 'list': {
+                        const data = await ao.phoneListNumbers();
+                        return print(data);
+                    }
+                    case 'messages': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneMessages(id);
+                        return print(data);
+                    }
+                    case 'calls': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneCalls(id);
+                        return print(data);
+                    }
+                    case 'release': {
+                        const id = flags.id || positional[0];
+                        if (!id)
+                            err('--id PHONE_ID required');
+                        const data = await ao.phoneRelease(id);
+                        return print(data);
+                    }
+                    case 'call-info': {
+                        const callId = flags.call || flags.id || positional[0];
+                        if (!callId)
+                            err('--call CALL_CONTROL_ID required');
+                        const data = await ao.phoneCallInfo(callId);
+                        return print(data);
+                    }
+                    case 'speak': {
+                        const callId = flags.call || flags.id;
+                        const text = flags.text || flags.tts;
+                        if (!callId || !text)
+                            err('--call <id>, --text <text> required');
+                        const voice = flags.voice;
+                        const language = flags.language;
+                        const data = await ao.phoneSpeak(callId, text, { ...(voice ? { voice } : {}), ...(language ? { language } : {}) });
+                        return print(data);
+                    }
+                    case 'play': {
+                        const callId = flags.call || flags.id;
+                        const audioUrl = flags.url || flags['audio-url'];
+                        if (!callId || !audioUrl)
+                            err('--call <id>, --url <https://...> required');
+                        const data = await ao.phonePlay(callId, audioUrl);
+                        return print(data);
+                    }
+                    case 'dtmf': {
+                        const callId = flags.call || flags.id;
+                        const digits = flags.digits || positional[0];
+                        if (!callId || !digits)
+                            err('--call <id>, --digits "1234#" required');
+                        const data = await ao.phoneDtmf(callId, digits);
+                        return print(data);
+                    }
+                    case 'gather': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const parseInt0 = (v) => (typeof v === 'string' ? parseInt(v, 10) : undefined);
+                        const opts = {};
+                        const minDigits = parseInt0(flags['min-digits']);
+                        if (minDigits !== undefined && Number.isFinite(minDigits))
+                            opts.minDigits = minDigits;
+                        const maxDigits = parseInt0(flags['max-digits']);
+                        if (maxDigits !== undefined && Number.isFinite(maxDigits))
+                            opts.maxDigits = maxDigits;
+                        const timeoutMillis = parseInt0(flags.timeout);
+                        if (timeoutMillis !== undefined && Number.isFinite(timeoutMillis))
+                            opts.timeoutMillis = timeoutMillis;
+                        if (flags['terminating-digit'])
+                            opts.terminatingDigit = flags['terminating-digit'];
+                        if (flags.prompt)
+                            opts.prompt = flags.prompt;
+                        if (flags['prompt-voice'])
+                            opts.promptVoice = flags['prompt-voice'];
+                        const data = await ao.phoneGather(callId, opts);
+                        return print(data);
+                    }
+                    case 'record': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneRecord(callId, flags.format);
+                        return print(data);
+                    }
+                    case 'record-stop': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneRecordStop(callId);
+                        return print(data);
+                    }
+                    case 'hangup': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneHangup(callId);
+                        return print(data);
+                    }
+                    case 'answer': {
+                        const callId = flags.call || flags.id;
+                        if (!callId)
+                            err('--call <id> required');
+                        const data = await ao.phoneAnswer(callId);
+                        return print(data);
+                    }
+                    case 'transfer': {
+                        const callId = flags.call || flags.id;
+                        const to = flags.to;
+                        if (!callId || !to)
+                            err('--call <id>, --to <+E.164> required');
+                        const data = await ao.phoneTransfer(callId, to);
+                        return print(data);
+                    }
+                    default: err(`Unknown phone command: ${subcommand}. Try: search, buy, list, release, sms, messages, call, calls, call-info, speak, play, dtmf, gather, record, record-stop, hangup, answer, transfer`);
                 }
                 break;
             }
             case 'email': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !EMAIL_HELP[subcommand])) {
                     showMenu({
                         command: 'email',
                         title: 'email',
@@ -781,6 +1238,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && EMAIL_HELP[subcommand]) {
+                    subcommandHelp('email', subcommand, EMAIL_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'create': {
                         const name = flags.name || positional[0];
@@ -872,7 +1333,7 @@ async function main() {
                 break;
             }
             case 'compute': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !COMPUTE_HELP[subcommand])) {
                     showMenu({
                         command: 'compute',
                         title: 'compute',
@@ -899,6 +1360,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && COMPUTE_HELP[subcommand]) {
+                    subcommandHelp('compute', subcommand, COMPUTE_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'plans': {
                         // --location filters to types deployable in that location. Each
@@ -1474,7 +1939,7 @@ async function main() {
                 break;
             }
             case 'domain': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !DOMAIN_HELP[subcommand])) {
                     showMenu({
                         command: 'domain',
                         title: 'domain',
@@ -1494,6 +1959,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && DOMAIN_HELP[subcommand]) {
+                    subcommandHelp('domain', subcommand, DOMAIN_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'check': {
                         const name = flags.name || positional[0];
@@ -3917,7 +4386,7 @@ async function main() {
                 break;
             }
             case 'chat': {
-                if (!subcommand || flags.help) {
+                if (!subcommand || (flags.help && !CHAT_HELP[subcommand])) {
                     showMenu({
                         command: 'chat',
                         title: 'chat',
@@ -3936,6 +4405,10 @@ async function main() {
                     });
                     break;
                 }
+                if (flags.help && subcommand && CHAT_HELP[subcommand]) {
+                    subcommandHelp('chat', subcommand, CHAT_HELP[subcommand]);
+                    break;
+                }
                 switch (subcommand) {
                     case 'run': {
                         const intent = (positional.join(' ') || flags.intent || '').trim();