--- name: inkbox-cli description: Use when running or writing shell commands with the Inkbox CLI (`inkbox` / `@inkbox/cli`) for identities, email, phone, text/SMS, iMessage, contacts, notes, contact rules, vault, mailbox, phone number, webhook, or signup workflows. user-invocable: false --- # Inkbox CLI Command-line interface for the Inkbox API — identities, email, phone, text/SMS, encrypted vault, mailboxes, phone numbers, signing keys, and webhook utilities. ## Auth & Runtime Set credentials via env vars or global flags: ```bash export INKBOX_API_KEY="ApiKey_..." export INKBOX_VAULT_KEY="my-vault-key" # only needed for vault decrypt/create flows ``` Global options: ```text --api-key Inkbox API key (or set INKBOX_API_KEY) --vault-key Vault key for decrypt operations (or set INKBOX_VAULT_KEY) --base-url Override API base URL --json Output as JSON instead of formatted tables ``` If `INKBOX_API_KEY` is missing and `--api-key` is not passed, the CLI exits with an error. Prefer `--json` when the result will be parsed or fed into another tool. Use the default table/record output when the user wants a quick human-readable summary. ## Install & Local Repo Usage Published package: ```bash npm install -g @inkbox/cli ``` Or run without a global install: ```bash npx @inkbox/cli ``` Requires Node.js >= 22. Inside this repository, prefer running the local source instead of assuming a global install: ```bash npm --prefix cli run dev -- ``` Examples: ```bash npm --prefix cli run dev -- --json identity list npm --prefix cli run dev -- email list -i support-bot --limit 10 ``` ## High-Risk Operations These commands can send real traffic or mutate real resources. Confirm with the user before running them: - `signup create` - `email send` - `text send` - `phone call` - `identity delete` - `email delete` - `email delete-thread` - `vault delete` - `mailbox update --filter-mode ...` (admin-only; flips allow/block semantics for that mailbox) - `number release` - `number update --filter-mode ...` (admin-only; same caveat as mailbox) - `signing-key create` `contacts delete`, `notes delete`, `mailbox rules delete`, `number rules delete` affect downstream filtering and access — confirm intent before running. Also confirm before creating or rotating secrets if the values were not explicitly provided by the user. ## Agent Signup For the full self-signup flow and API semantics, read the shared reference: > **See:** `skills/inkbox-agent-self-signup/SKILL.md` CLI commands: ```bash inkbox signup create inkbox signup verify --code inkbox signup resend-verification inkbox signup status ``` `signup create` is the main command that does not require an API key. The later signup commands require the signup-issued API key to be passed back via `--api-key` or exported as `INKBOX_API_KEY`; the CLI does not persist it automatically. ## Identities ```bash inkbox identity list inkbox identity get inkbox identity create [--display-name ] [--description ] [--email-local-part ] [--sending-domain | --platform-domain] [--tls-mode edge|passthrough] inkbox identity delete inkbox identity update [--new-handle ] [--display-name ] [--description | --clear-description] [--status active|paused] inkbox identity refresh ``` `identity create` atomically provisions the mailbox AND the tunnel. The JSON output includes both (`mailbox`, `tunnel.publicHost`, `tunnel.tlsMode`). `--sending-domain ` binds the agent's mailbox to a verified custom domain (bare name, e.g. `mail.acme.com`); `--platform-domain` forces the platform sending domain; the two are mutually exclusive. `--tls-mode` defaults to `edge` and is fixed at create time (changing it later requires deleting the identity + recreating). For `identity update`, `--description ""` and `--clear-description` both send explicit null to clear; omitting both leaves the field untouched. Notes: - `identity delete` cascades to the linked mailbox + tunnel and revokes any identity-scoped API keys. - `identity get` and `identity refresh` return mailbox, phone-number, and tunnel assignments when present. - Most email, phone, and text commands require `-i, --identity `. ### Identity Visibility Controls which other agent identities can see an identity in API responses. Humans and admins always see every identity. ```bash inkbox identity access list inkbox identity access grant inkbox identity access grant-everyone inkbox identity access revoke ``` `list` shows either a single wildcard row (`viewerIdentityId` empty → every active identity sees it), explicit per-viewer rows, or nothing (no agent can see it). `grant` adds one viewer; `grant-everyone` resets to the org-wide wildcard; `revoke` drops one viewer. Viewer identities are passed as handles and resolved to UUIDs automatically. Unrelated to `identity revoke-access` below, which manages vault-secret access. ### Identity-Scoped Secrets These require a vault key: ```bash inkbox identity create-secret --name --type ... inkbox identity get-secret inkbox identity delete-secret inkbox identity revoke-access inkbox identity set-totp --uri inkbox identity remove-totp inkbox identity totp-code ``` Secret types: ```text login, api_key, ssh_key, key_pair, other ``` ## Email All email commands are identity-scoped and require `-i `. ```bash inkbox email send -i \ --to user@example.com \ --subject "Hello" \ --body-text "Hi" inkbox email list -i --limit 10 inkbox email get -i inkbox email search -i -q "invoice" inkbox email unread -i --limit 10 inkbox email mark-read -i inkbox email delete -i inkbox email delete-thread -i inkbox email star -i inkbox email unstar -i inkbox email thread -i ``` Use `email search` only when the identity already has a mailbox assigned. Before sending, confirm recipients, subject, and body with the user. ## Phone All phone commands are identity-scoped and require `-i `. ```bash inkbox phone call -i --to +15551234567 --ws-url wss://example.com/ws inkbox phone calls -i --limit 10 --offset 0 inkbox phone transcripts -i inkbox phone search-transcripts -i -q "refund" --party remote ``` Before placing a call, confirm the destination number and websocket URL with the user. ## Text Messages All text commands are identity-scoped and require `-i `. **Outbound SMS limits and gates (current):** - Allowed only from **local** numbers, not toll-free. - **100 recipient sends per phone number per rolling 24h.** A 3-recipient group message counts as 3 recipient sends. A single accepted send may push usage past the cap; the next capped send returns `429 sender_rate_limited`. - A freshly provisioned local number needs **~10-15 min** for 10DLC carrier propagation. Inspect with `inkbox number get `; sending is gated until `smsStatus` reads `ready` (otherwise `409 sender_sms_pending`). - Recipient must have texted **`START`** to any number in the org. Unknown → `403 recipient_not_opted_in`. `STOP` → `403 recipient_opted_out`. Inspect / override consent state via `inkbox sms-opt-in` (see below). - **Beta:** Group MMS and conversation sends are beta. Some carriers may reject group chats or MMS from 10DLC numbers even when the sender is ready and recipients have opted in. Customer-managed 10DLC brands/campaigns lift the default per-number cap to the carrier-assigned tier. Toll-free SMS sending is still coming soon. ```bash inkbox text send -i --to +15551234567 --text "Hello from Inkbox" inkbox text send -i --to +15551234567,+15557654321 --text "Hello group" --media-url https://example.com/photo.jpg inkbox text send -i --conversation-id --text "Reply all" inkbox text list -i --limit 20 inkbox text get -i inkbox text conversations -i --limit 20 --include-groups inkbox text conversation -i --limit 50 inkbox text search -i -q "invoice" inkbox text mark-read -i inkbox text mark-conversation-read -i ``` ## iMessage All iMessage commands are identity-scoped and require `-i `. iMessage has no per-identity number: recipients connect to an agent identity through a shared pool of numbers via the triage line, which creates an assignment for that one recipient. There is **no cold outreach** — sends only work toward recipients who connected first, and the identity must be opted in (`inkbox identity update --imessage-enabled true`). ```bash inkbox imessage triage-number # the router number + the connect command humans text to it inkbox imessage send -i --to +15551234567 --text "Hello over iMessage" inkbox imessage send -i --conversation-id --text "Reply" --send-style slam inkbox imessage list -i --limit 20 --unread-only inkbox imessage assignments -i --limit 20 # active connections, newest first inkbox imessage conversations -i --limit 20 inkbox imessage conversation -i --limit 50 inkbox imessage react -i --reaction like inkbox imessage mark-conversation-read -i inkbox imessage typing -i inkbox imessage upload-media ./photo.jpg -i --content-type image/jpeg # Contact rules are scoped to the identity (not a phone number): inkbox imessage contact-rule list -i inkbox imessage contact-rule create -i --action block --match-target +15559999999 inkbox imessage contact-rule update -i --status paused # admin-only inkbox imessage contact-rule delete -i # admin-only inkbox imessage contact-rule list-all # admin-only, org-wide ``` ## SMS Opt-Ins Per-recipient SMS consent state, keyed by `(your org, recipient number)`. The registry is updated automatically when recipients text `START` / `STOP` to any of your numbers (`source=sms`). Reads work for any admin caller; writes require your org to be on its own active, customer-managed 10DLC campaign — default-campaign orgs share consent state and get `409 customer_campaign_required` on writes (audit event recorded with `source=api`). ```bash # List your org's consent rows, newest-updated first inkbox sms-opt-in list inkbox sms-opt-in list --status opted_out --limit 100 inkbox --json sms-opt-in list # Look up one recipient — 404 if no row exists inkbox sms-opt-in get +15551234567 # Programmatic writes (customer-managed 10DLC campaign only) inkbox sms-opt-in opt-in +15551234567 inkbox sms-opt-in opt-out +15551234567 ``` ## Vault Vault decryption and secret creation require a vault key via `INKBOX_VAULT_KEY` or `--vault-key`. ```bash inkbox vault init --vault-key inkbox vault info inkbox vault secrets inkbox vault get inkbox vault create --name --type ... inkbox vault delete inkbox vault keys inkbox vault grant-access -i inkbox vault revoke-access -i inkbox vault access-list inkbox vault logins -i inkbox vault api-keys -i inkbox vault ssh-keys -i inkbox vault key-pairs -i ``` Secret type flags: ```bash # login --password [--username ] [--email ] [--url ] [--totp-uri ] [--notes ] # api_key --key [--endpoint ] [--notes ] # key_pair --access-key --secret-key [--endpoint ] [--notes ] # ssh_key --private-key [--public-key ] [--fingerprint ] [--passphrase ] [--notes ] # other --data [--notes ] ``` ## Mailboxes Mailboxes are provisioned atomically by `inkbox identity create` and removed by `inkbox identity delete` (cascade); there is no standalone create / delete here. The human-readable name lives on the identity now — `inkbox identity update --display-name`; the mailbox PATCH endpoint hard-rejects `display_name` with a 422. ```bash inkbox mailbox list inkbox mailbox get inkbox mailbox update [--filter-mode whitelist|blacklist] # To attach a webhook receiver, use `inkbox webhook subscription create # --mailbox-id --url --event-type message.received ...`. ``` `mailbox list` / `get` / `update` rows include `filterMode` and `agentIdentityId`. `--filter-mode` is admin-only; when the value actually changes, a note is printed to **stderr** telling you how many existing rules are now redundant under the new mode. ## Tunnels Tunnels are provisioned atomically by `inkbox identity create` and removed by `inkbox identity delete` (cascade). The `inkbox tunnel` subcommand is read + update + sign-csr only. ```bash inkbox tunnel list inkbox tunnel get inkbox tunnel update [--metadata ] inkbox tunnel sign-csr --csr [--out ] ``` `tunnel get` accepts either a UUID or the owning identity's agent handle. `tunnel update` is metadata-only; pass `--metadata "{}"` to clear. `tunnel sign-csr` is passthrough-only and uses an elevated 180-second timeout (the server runs DNS validation + cert issuance synchronously). Data-plane auth uses the same API key the CLI was invoked with — admin-scoped or identity-scoped (matching the tunnel's identity). There is no per-tunnel connect secret; mint an identity-scoped key via `inkbox api-keys create --identity-id ` for an agent. ## Custom Sending Domains ```bash inkbox domain list [--status verified] inkbox domain set-default ``` `domain list` shows registered custom domains for your org, optionally filtered by status (e.g. `verified`). `domain set-default` requires an admin-scoped API key; pass the bare custom domain name to set it, or pass the platform sending domain (e.g. `inkboxmail.com` in production) to revert. Domain registration, DNS records, verification, DKIM rotation, and deletion stay in the console. ### Mailbox Contact Rules (`inkbox mailbox rules …`) Per-mailbox allow/block rules (combined with the mailbox's `filterMode`). ```bash inkbox mailbox rules list --mailbox [--action allow|block] [--match-type exact_email|domain] [--limit ] [--offset ] inkbox mailbox rules list --all-mailboxes [--mailbox-id ] [--action …] [--match-type …] # admin-only inkbox mailbox rules get --mailbox inkbox mailbox rules create --mailbox --action allow|block --match-type exact_email|domain --match-target [--status active|paused] inkbox mailbox rules update --mailbox [--action allow|block] [--status active|paused] # admin-only inkbox mailbox rules delete --mailbox # admin-only ``` ## Admin-Only Phone Numbers ```bash inkbox number list inkbox number get inkbox number provision --handle [--type toll_free|local] [--state NY] inkbox number update [--incoming-call-action auto_accept|auto_reject|webhook] [--filter-mode whitelist|blacklist] ... inkbox number release ``` Use `--state` only when provisioning a local number. Phone-number rows also carry `filterMode` / `agentIdentityId`; `--filter-mode` is admin-only and prints a stderr note when the value changes. ### Number Contact Rules (`inkbox number rules …`) Per-number allow/block rules (combined with the number's `filterMode`). ```bash inkbox number rules list --number [--action allow|block] [--match-type exact_number] [--limit ] [--offset ] inkbox number rules list --all-numbers [--phone-number-id ] [--action …] [--match-type …] # admin-only inkbox number rules get --number inkbox number rules create --number --action allow|block --match-target [--match-type exact_number] [--status active|paused] inkbox number rules update --number [--action allow|block] [--status active|paused] # admin-only inkbox number rules delete --number # admin-only ``` ## Contacts Admin-only address book. All commands hit the admin endpoints; agents see contacts they've been granted access to. ```bash inkbox contacts list [--q ] [--order name|recent] [--limit ] [--offset ] inkbox contacts get inkbox contacts create --json # JSON matching CreateContactOptions inkbox contacts update --json # JSON-merge-patch inkbox contacts delete inkbox contacts lookup (--email | --email-contains | --email-domain | --phone | --phone-contains ) inkbox contacts import # bulk vCard import (≤5 MiB, ≤1000 cards) inkbox contacts export [--out ] # vCard 4.0 to stdout or file # Per-contact access grants inkbox contacts access list inkbox contacts access grant (--identity | --wildcard) # admin + JWT only inkbox contacts access revoke ``` `contacts lookup` requires exactly one filter flag. For `create` / `update`, construct the payload carefully — fields include `preferredName`, `givenName`, `familyName`, `companyName`, `jobTitle`, `birthday`, `notes`, and lists `emails` / `phones` / `websites` / `dates` / `addresses` / `customFields` (each list item has `label` / `value`). ## Notes Admin-only free-form notes with per-identity grants (no wildcard). ```bash inkbox notes list [--q ] [--identity ] [--order recent|created] [--limit ] [--offset ] inkbox notes get inkbox notes create --body [--title ] inkbox notes update [--title ] [--body ] # pass --title "" to clear inkbox notes delete # Per-note access grants inkbox notes access list inkbox notes access grant # admin + JWT only inkbox notes access revoke ``` ## Whoami, Signing Keys, Webhooks ```bash inkbox whoami inkbox signing-key create inkbox webhook verify --payload --secret -H "X-Header: value" # Webhook subscriptions (fan-out per (owner, url, event_types)): inkbox webhook subscription list [--mailbox-id ] [--phone-number-id ] [--agent-identity-id ] inkbox webhook subscription create --mailbox-id --url --event-type message.received inkbox webhook subscription create --phone-number-id --url \ --event-type text.received --event-type text.delivered inkbox webhook subscription create --agent-identity-id --url \ --event-type imessage.received --event-type imessage.reaction_received inkbox webhook subscription update [--url ] [--event-type ...] inkbox webhook subscription delete ``` Use `whoami --json` when you need the authenticated caller shape exactly. `inkbox webhook verify` is event-type-agnostic — it operates on raw bytes and only checks the `X-Inkbox-Signature` HMAC. The body can be any of: - **Mail** (envelope): `message.received`, `message.sent`, `message.forwarded`, `message.delivered`, `message.bounced`, `message.failed`. Subscribe via `inkbox webhook subscription create --mailbox-id ...`. - **Text** (envelope): `text.received`, `text.sent`, `text.delivered`, `text.delivery_failed`, `text.delivery_unconfirmed`. Subscribe via `inkbox webhook subscription create --phone-number-id ...`. - **iMessage** (envelope): `imessage.received`, `imessage.reaction_received`, `imessage.sent`, `imessage.delivered`, `imessage.delivery_failed`. Subscribe via `inkbox webhook subscription create --agent-identity-id ...` — owned by the agent identity, since shared iMessage pool numbers are not org resources. - **Inbound call** (flat, no envelope; response controls call routing). Not subscribable; URL stays on the phone-number resource as `incomingCallWebhookUrl`. Mail and text payloads carry `data.contacts` and `data.agent_identities` (both always-present lists; mail entries also carry `bucket` + `address`). Outbound mail payloads also include `data.message.bcc_addresses` (`null` on inbound). Group text events carry per-recipient delivery rows in `data.text_message.recipients`; **outbound group lifecycle** events name the event target in `data.recipient_phone_number` (one webhook per recipient leg). Inbound and outbound 1:1 events leave `data.recipient_phone_number` as `null` — the singular peer is already in `data.text_message.remote_phone_number` (inbound) or `data.text_message.recipients[0]` (outbound 1:1). Inbound-call payloads carry `contacts` and `agent_identities` at the top level (no envelope). For the typed receiver-side shapes, see the SDK skills (`inkbox-ts`, `inkbox-python`). ## Practical Guidance - Prefer the local repo command `npm --prefix cli run dev -- ...` when working in this codebase. - Prefer `--json` for anything that needs stable parsing. - Use the identity handle, not mailbox address or phone number, for identity-scoped commands. - If a command fails because the identity lacks a mailbox or phone number, inspect it first with `inkbox identity get `.