# Inkbox Cli > 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. - **Type:** Skill - **Install:** `agentstack add skill-inkbox-ai-inkbox-inkbox-cli` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [inkbox-ai](https://agentstack.voostack.com/s/inkbox-ai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [inkbox-ai](https://github.com/inkbox-ai) - **Source:** https://github.com/inkbox-ai/inkbox/tree/main/skills/inkbox-cli - **Website:** https://inkbox.ai/docs ## Install ```sh agentstack add skill-inkbox-ai-inkbox-inkbox-cli ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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` - `identity update --mail-filter-mode ... / --phone-filter-mode ...` (admin-only; flips allow/block semantics for that identity's channel) - `mailbox update --filter-mode ...` (DEPRECATED channel path; admin-only) - `number release` - `number update --filter-mode ...` (DEPRECATED channel path; admin-only) - `identity signing-key rotate ` (rotates that identity's webhook signing key) - `signing-key create` (DEPRECATED org-level path) `contacts delete`, `notes delete`, `identity mail-rules delete`, `identity phone-rules delete`, `mailbox rules delete` (deprecated), `number rules delete` (deprecated) 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] [--mail-filter-mode whitelist|blacklist] [--phone-filter-mode whitelist|blacklist] [--status active|paused] inkbox identity refresh ``` `--mail-filter-mode` / `--phone-filter-mode` set the identity's contact-rule mode (admin-only). Unlike the deprecated `mailbox update --filter-mode` / `number update --filter-mode`, the identity path does **not** print a change notice. `--phone-filter-mode` requires the identity to have a phone number (else a 422). `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 ``` ### Identity Contact Rules Allow/block lists are scoped to the **agent identity** (keyed by handle), combined with the identity's mail/phone filter mode (`inkbox identity update --mail-filter-mode / --phone-filter-mode`). Mail matches by exact email or domain; phone matches by exact E.164 number. ```bash # Mail rules inkbox identity mail-rules list [--action allow|block] [--match-type exact_email|domain] [--limit ] [--offset ] inkbox identity mail-rules list-all [--agent-identity-id ] [--action …] [--match-type …] # admin-only, org-wide inkbox identity mail-rules get inkbox identity mail-rules create --action allow|block --match-type exact_email|domain --match-target inkbox identity mail-rules update [--action allow|block] [--status active|paused] # admin-only inkbox identity mail-rules delete # admin-only # Phone rules — require the identity to have a phone number; only exact_number is supported. inkbox identity phone-rules list [--action allow|block] [--match-type exact_number] [--limit ] [--offset ] inkbox identity phone-rules list-all [--agent-identity-id ] [--action …] # admin-only, org-wide inkbox identity phone-rules get inkbox identity phone-rules create --action allow|block --match-target [--match-type exact_number] inkbox identity phone-rules update [--action allow|block] [--status active|paused] # admin-only inkbox identity phone-rules delete # admin-only ``` New rules always start active; use `update --status paused` to pause one. These replace the deprecated `inkbox mailbox rules` / `inkbox number rules` groups below. ### Identity Signing Key Each identity has its own webhook signing key: ```bash inkbox identity signing-key status inkbox identity signing-key rotate # mints or rotates; prints the plaintext secret ONCE ``` ## 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`. `mailbox update --filter-mode` is the **deprecated** channel path (admin-only; prints a stderr change note when the value actually changes). Prefer `inkbox identity update --mail-filter-mode whitelist|blacklist`, which sets the mode on the identity and prints no change note. ## 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 ( … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [inkbox-ai](https://github.com/inkbox-ai) - **Source:** [inkbox-ai/inkbox](https://github.com/inkbox-ai/inkbox) - **License:** MIT - **Homepage:** https://inkbox.ai/docs Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-inkbox-ai-inkbox-inkbox-cli - Seller: https://agentstack.voostack.com/s/inkbox-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.