CLI

Audited operations and actual coverage

This source version adds 80 audited operations across SDK, CLI and MCP. Installed npm versions and hosted enablement must be checked separately.

Coverage: contacts, tasks, tickets, inbox assignment/status/labels/internal notes and separate text sending; AI drafts/configuration/reviewed text knowledge/channels/tests/readiness/publish; manual orders/status/payment/fulfillment; products/categories; contact status/stage/assignment/tags/custom fields; automation inspection/inactive draft/dry simulation/pause/approved activation; campaign audience estimates/drafts/pause/cancel and approved send/resume/schedule. The 553-route inventory is discovery metadata, not executable full dashboard parity.

SDK: describeOperations(), prepareOperation(id, input, idempotencyKey), executeOperation(id, input, { idempotencyKey, confirmation }). CLI: operations list/inspect/preview/run with --input, --idempotency-key and --confirm. MCP: operations_list, operation_inspect, operation_preview, operation_execute; messages use message_send and activation uses lifecycle_activate; campaign delivery uses campaign_send or campaign_schedule. CLI sending uses messages send after previewing inbox.message.send.

Show the exact preview and obtain explicit user approval before a mutation. The confirmation hash binds normalized input and key; it does not prove human approval. Retain the same idempotency key for recovery. No automatic retries. Existing tenant, role, scope and plan gates apply. OAuth write scopes require new explicit consent and start unchecked; old grants do not gain permissions.

AI tests and knowledge processing may consume credits. Publishing and channel assignment can affect live replies. Sending requires approval of contactId, channelId/type and complete text; the server rechecks the target. Inbox media/template sends, entity deletion, arbitrary HTTP, billing and platform administration are not exposed. Campaign template delivery and scheduling require a separate approved frozen audience/content/sender/time snapshot. Order and contact tag changes may trigger configured automation; custom fields replace the entire map; payment updates do not charge a provider. Refunds/cancellation and full campaign/automation coverage remain excluded.

Needs Node.js >= 20.3.

npm i -g @inboxychat/cli
inboxy --version

npx -y -p @inboxychat/cli inboxy --help

1. Sign in to Inboxy as a company admin and open Developers → API keys in the dashboard (/developer-center/keys).
2. Choose "Create an API key" and give the key a name you will recognise (for example "Claude on my laptop").
3. Tick only the scopes you need. There is no default set: a key without scopes cannot be created. The read tools need the ":read" scopes (contacts:read, orders:read, ...).
4. Pick an expiry: 30, 90 (default), 180 or 365 days, or never. The default is 90 days.
5. Copy the key when it is shown. It starts with "inboxy_". Store it in a secret manager or the OS keychain, never in a repository.

Sign in

On a terminal, inboxy auth login opens the browser so you can approve a key for this company. The key is never an argument: inboxy auth login <key> and any --key / --token / --api-key flag are refused. When stdin is not a terminal, paste or pipe the key instead (a hidden prompt is not used for a pipe).

inboxy auth login                      # browser approval on a terminal
pbpaste | inboxy auth login            # or pipe a key (macOS, not a TTY)
inboxy auth login --profile client-a   # one profile per company
inboxy auth status                     # where the key comes from + is it accepted
inboxy auth logout --profile client-a

Where the key is kept

• In the OS keychain: macOS Keychain or Linux Secret Service (secret-tool).
• Without a keychain (or with --store file): in the config file with mode 0600 inside a 0700 directory. A config file other users can read is refused.
• Config file: $INBOXY_CONFIG_DIR, else $XDG_CONFIG_HOME/inboxy, else ~/.config/inboxy/config.json.

Find a customer and their orders

inboxy contacts search "9665" --stage customer
inboxy orders list --contact CONTACT_ID

Export orders as JSON

--all follows the cursors up to --max-pages (default 10).

inboxy orders list --after 2026-10-20 --all --json > orders.json

Agencies: one profile per company

inboxy auth login --profile client-a
inboxy --profile client-a usage
INBOXY_PROFILE=client-b inboxy orders list

Use it in CI or a script

Set INBOXY_API_KEY from your secret store; it overrides the keychain. Branch on the exit code.

INBOXY_API_KEY="$INBOXY_API_KEY" inboxy doctor --json > doctor.json || echo "doctor exit $?"

Commands

inboxy auth login [--store keychain|file] [--no-verify] [--profile <name>]
inboxy auth status [--offline]
inboxy auth logout [--profile <name>]
inboxy whoami
inboxy usage
inboxy stores list
inboxy orders list [--status] [--payment-status] [--fulfillment-status] [--source] [--store <id>] [--contact <id>] [--search <text>] [--after <iso>] [--before <iso>]
inboxy orders get <id>
inboxy contacts search [text] [--status] [--stage] [--tags <ids>] [--created-after <iso>] [--created-before <iso>]
inboxy doctor
inboxy operations list
inboxy operations inspect <operation>
inboxy operations preview <operation> --input <json> --idempotency-key <key>
inboxy operations run <operation> --input <json> --idempotency-key <key> --confirm <preview-hash>
inboxy messages send --input <json> --idempotency-key <key> --confirm <preview-hash>
inboxy lifecycle activate <operation> --input <json> --idempotency-key <key> --confirm <hash>
inboxy campaigns send <operation> --input <json> --idempotency-key <key> --confirm <hash>
inboxy campaigns schedule --input <json> --idempotency-key <key> --confirm <hash>

Paging and global options

• --limit 1-100, --cursor <nextCursor>, or --all (with --max-pages, default 10).
• --json, --profile <name>, --url <origin>, --timeout <ms>. Global options may come before or after the command.

--json output

One document on stdout, schemaVersion 1. Fields may be added, never renamed or removed. data items are the public API v1 objects unchanged.

{ "schemaVersion": 1, "ok": true, "command": "orders list",
  "data": [ ... ], "meta": { "limit": 20, "hasMore": true, "nextCursor": "...", "pages": 1 } }

{ "schemaVersion": 1, "ok": false, "command": "orders list",
  "error": { "kind": "forbidden", "code": "INSUFFICIENT_PERMISSIONS", "status": 403,
             "message": "...", "details": { "requiredScope": "orders:read" }, "retryAfterSeconds": null } }

Environment

• The operation run command can change data after exact preview confirmation.
• The key is never printed. Output and errors are redacted (any inboxy_… value, any Bearer value, and the key in use); status shows only the 8-character prefix.
• No shell: inputs reach the API only as validated, encoded values; ids must be 1-64 letters, digits, "_" or "-".
• HTTPS only (http for localhost); redirects are refused. The REST API rate limits apply.

Start with inboxy doctor. It exits 10 when a check fails and says what to fix.

Exit codes

Common errors

• "No API key" (exit 3): run inboxy auth login, or set INBOXY_API_KEY.
• "Inboxy refused the API key" (exit 4): the key is unknown, revoked or expired. Create a new key.
• "does not have the … scope" (exit 5): create a key that includes the named scope.
• Linux without secret-tool: install libsecret tools, or use inboxy auth login --store file.