inkbox-ai/inkbox/inkbox-cli

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:

export INKBOX_API_KEY="ApiKey_..."
export INKBOX_VAULT_KEY="my-vault-key"   # only needed for vault decrypt/create flows

Global options:

--api-key <key>      Inkbox API key (or set INKBOX_API_KEY)
--vault-key <key>    Vault key for decrypt operations (or set INKBOX_VAULT_KEY)
--base-url <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. With --json, success stays on stdout and API failures write one structured error object to stderr, retaining error.detail and error.retryAfterSeconds.

Install & Local Repo Usage

Published package:

npm install -g @inkbox/cli

Or run without a global install:

npx @inkbox/cli <command>

Requires Node.js >= 22.

Inside this repository, prefer running the local source instead of assuming a global install:

npm --prefix cli run dev -- <command>

Examples:

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
• a2a invites create, a2a invites revoke, and a2a invites accept
• email send
• email drafts send
• text send
• phone call
• identity delete
• email delete
• email delete-thread
• email drafts delete
• 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)
• phone incoming-action <action> / number update --incoming-call-action ... (changes what answers that identity's inbound calls — hosted_agent makes the platform voice agent pick up)
• identity signing-key rotate <handle> (rotates that identity's webhook signing key)
• signing-key create (DEPRECATED org-level path)

contacts delete, contacts bulk-delete, contacts facts delete, notes delete, identity mail-rules delete, identity phone-rules delete, mailbox rules delete (deprecated), and number rules delete (deprecated) remove data or affect downstream filtering — 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:

inkbox signup create
inkbox signup verify --code <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

Handles are fixed at creation. Use identity update <handle> --display-name <name> to change an agent's presentation.

inkbox identity list
inkbox identity get <handle>
inkbox identity create <handle> [--display-name <name>] [--description <text>]
                                 [--imessage-enabled]
                                 [--contact-sharing-enabled true|false]
                                 [--email-local-part <part>]
                                 [--sending-domain <name> | --platform-domain]
                                 [--tls-mode edge|passthrough]
inkbox identity delete <handle>
inkbox identity update <handle> [--display-name <name>]
                                 [--description <text> | --clear-description]
                                 [--imessage-enabled true|false]
                                 [--contact-sharing-enabled true|false]
                                 [--mail-filter-mode whitelist|blacklist]
                                 [--phone-filter-mode whitelist|blacklist]
inkbox identity refresh <handle>

--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 mode also governs iMessage and can be configured without a dedicated phone number.

identity create atomically provisions the mailbox AND the tunnel. The JSON output includes both (mailbox, tunnel.publicHost, tunnel.tlsMode).

New identities default contact sharing to enabled. If a personal iMessage line is attached, it automatically offers the identity's display name (or handle as fallback) and optional avatar. Use --contact-sharing-enabled false during identity creation to opt out, or inkbox identity update <handle> --contact-sharing-enabled false to disable it later. Pass true to enable it again.

--sending-domain <name> 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 <handle>.

Identity-Scoped Secrets

These require a vault key:

inkbox identity create-secret <handle> --name <name> --type <type> ...
inkbox identity get-secret <handle> <secret-id>
inkbox identity delete-secret <handle> <secret-id>
inkbox identity revoke-access <handle> <secret-id>
inkbox identity set-totp <handle> <secret-id> --uri <otpauth-uri>
inkbox identity remove-totp <handle> <secret-id>
inkbox identity totp-code <handle> <secret-id>

Secret types:

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.

# Mail rules
inkbox identity mail-rules list <handle> [--action allow|block] [--match-type exact_email|domain] [--limit <n>] [--offset <n>]
inkbox identity mail-rules list-all [--agent-identity-id <id>] [--action …] [--match-type …]   # admin-only, org-wide
inkbox identity mail-rules get <handle> <rule-id>
inkbox identity mail-rules create <handle> --action allow|block --match-type exact_email|domain --match-target <value>
inkbox identity mail-rules update <handle> <rule-id> --action allow|block   # admin-only
inkbox identity mail-rules delete <handle> <rule-id>                                                    # admin-only
 
# Phone rules — require the identity to have a phone number; only exact_number is supported.
inkbox identity phone-rules list <handle> [--action allow|block] [--match-type exact_number] [--limit <n>] [--offset <n>]
inkbox identity phone-rules list-all [--agent-identity-id <id>] [--action …]   # admin-only, org-wide
inkbox identity phone-rules get <handle> <rule-id>
inkbox identity phone-rules create <handle> --action allow|block --match-target <e164> [--match-type exact_number]
inkbox identity phone-rules update <handle> <rule-id> --action allow|block   # admin-only
inkbox identity phone-rules delete <handle> <rule-id>                                                    # admin-only

New rules always start active. These replace the deprecated inkbox mailbox rules / inkbox number rules groups below.

Identity Signing Key

Each identity has its own webhook signing key:

inkbox identity signing-key status <handle>
inkbox identity signing-key rotate <handle>   # mints or rotates; prints the plaintext secret ONCE

Email

All email commands are identity-scoped and require -i <handle>.

inkbox email send -i <handle> \
  --to user@example.com \
  --subject "Hello" \
  --body-html '<p>Hi</p><img src="cid:chart">' \
  --attach ./report.pdf \        # optional; repeatable file attachment
  --inline-image chart=./chart.png \  # optional, repeatable; embeds <img src="cid:chart"> (needs --body-html, image/*)
  --track-opens                 # optional; embed a tracking pixel (needs --body-html)
 
inkbox email reply-all <message-id> -i <handle> --body-html "<p>Thanks</p>" --attach ./notes.txt
inkbox email forward <message-id> -i <handle> --to user@example.com --attach ./extra.pdf --track-opens
 
inkbox email list -i <handle> --limit 10
inkbox email get <message-id> -i <handle>   # fetching an inbound message marks it read
inkbox email search -i <handle> -q "invoice"
inkbox email unread -i <handle> --limit 10
inkbox email mark-read <ids...> -i <handle>
inkbox email mark-unread <ids...> -i <handle>
inkbox email download-attachment <message-id> <filename> -i <handle>   # time-limited download URL
inkbox email delete <message-id> -i <handle>
inkbox email delete-thread <thread-id> -i <handle>
inkbox email star <message-id> -i <handle>
inkbox email unstar <message-id> -i <handle>
inkbox email thread <thread-id> -i <handle>

(--inline-image is send/reply-all only — forwards reject inline images.)

Drafts

inkbox email drafts create -i <handle> --subject "Work in progress" \
  --idempotency-key draft-create-2026-08-19-1
inkbox email drafts list -i <handle>
inkbox email drafts get <draft-id> -i <handle>
inkbox email drafts update <draft-id> -i <handle> --generation <n> \
  --to user@example.com --clear-subject
inkbox email drafts duplicate <draft-id> -i <handle> --generation <n>
inkbox email drafts delete <draft-id> -i <handle> --generation <n>
inkbox email drafts send <draft-id> -i <handle> --generation <n>
 
inkbox email drafts attachment add <draft-id> -i <handle> \
  --generation <n> --attach ./notes.txt
inkbox email drafts attachment remove <draft-id> <part-index> -i <handle> \
  --generation <n>
inkbox email drafts attachment download <draft-id> <part-index> -i <handle> \
  --generation <n> --output ./notes.txt

Create accepts incomplete content. Update supports explicit-null --clear-* flags; omission leaves a field unchanged. Use the generation printed by the latest read or mutation for every following mutation. Attachment part indexes belong to that generation, so run get again after an edit. Drafts share the mailbox's standard Drafts folder with connected mail clients. Reuse one --idempotency-key and the exact same arguments when retrying a logical create after an ambiguous result. Use a new key after the original draft is sent or deleted. Forward-only flags require --forward-message-id.

Successful send prints the sent message and removes the draft; an exact-generation retry may return the same sent message. On HTTP 409, refresh for draft_generation_conflict and retry the same ID and generation for draft_send_in_progress. Never resend draft_delivery_uncertain; after checking sent mail, duplicate or delete it instead.

Use email search only when the identity already has a mailbox assigned.