--- title: CLI description: The aiinbx command line — send and read mail, run every API resource, forward webhooks to localhost without a tunnel, wait for an email in a test, and check a domain's DNS. sidebar: label: CLI icon: terminal --- `aiinbx` runs your AI Inbx workspace from a terminal, a script or an agent. Every API operation is a command. A few jobs only a local tool can do have commands of their own: sending files and React Email templates, forwarding webhook events to `localhost`, blocking until an email arrives, and checking a domain's DNS. ```sh aiinbx login aiinbx send --from you@yourdomain.com --to someone@example.com \ --subject "Hello" --text "Sent from the terminal" ``` ## Install The CLI is a single executable. Nothing else, not Node and not Bun, has to be installed to run it. {/* Generated by scripts/cli-install.ts from the shared API contract. */} ```sh macOS & Linux curl -fsSL https://aiinbx.com/install.sh | sh ``` ```sh Homebrew brew install aiinbx/tap/aiinbx ``` ```sh npm npm install -g @aiinbx/cli ``` ```powershell Windows powershell -c "irm https://aiinbx.com/install.ps1 | iex" ``` To run it once without installing: `npx @aiinbx/cli --help`. When a newer version is out, the CLI says so once a day. `aiinbx update` installs it the way the CLI was installed: through npm, pnpm, Bun, Yarn or Homebrew, or, for the install script's copy, by downloading the release, checking it against its checksums and replacing itself. `aiinbx uninstall` removes the CLI the same way, along with the PATH entry the install script added. It signs out of every profile and deletes the config directory; `--keep-config` keeps them. ## Sign in ```sh aiinbx login # opens the browser aiinbx login --device # a code to approve on another device (SSH, containers) echo "$AI_INBX_API_KEY" | aiinbx login --with-api-key aiinbx whoami ``` A login acts for your account in the workspaces you grant it. When it reaches more than one, pick the one commands act in with `aiinbx workspace use `, or pass `--workspace` for a single command. An [API key](/authentication) belongs to one workspace and needs neither. Credentials are taken from `--api-key` first, then `AI_INBX_API_KEY`, then the signed-in profile. A profile's secret is kept in the macOS Keychain, the Secret Service on Linux, or DPAPI on Windows. `-p ` or `AI_INBX_PROFILE` picks a profile, and `aiinbx auth switch ` makes one the default. ## Commands Every API operation is a command, `aiinbx `. Path parameters are arguments and fields are flags. A resource on its own lists it: ```sh aiinbx threads --limit 5 aiinbx threads retrieve thr_123 aiinbx threads reply thr_123 --text "Thanks, on it" aiinbx domains create --name yourdomain.com --region eu-central-1 aiinbx events list --type email.bounced --type email.complained --limit 50 aiinbx webhook-endpoints create --url https://example.com/hooks --subscriptions email.received aiinbx attachments download att_123 --output invoice.pdf ``` - Repeatable flags take one value each: `--to a@x.com --to b@x.com`. - Booleans are switches: `--track-opens`, `--no-track-opens`. - Nested fields take JSON: `--tracking '{"opens":false}'`. - `--data` takes the whole body as JSON, `@file.json`, or `-` for stdin. Flags are laid over it. - Lists take `--limit` and `--cursor`. `--all` fetches every page. - Commands that cannot be undone ask first, or need `--yes` without a terminal. The commands are generated from the same contract as the [API reference](/api) and the SDKs, so they cannot drift from the API. `aiinbx --help` shows every flag with examples. ## Send ```sh aiinbx send --from you@yourdomain.com --to a@example.com --subject Report \ --html-file report.html --text-file report.txt --attach report.pdf cat notes.md | aiinbx send --from you@yourdomain.com --to a@example.com \ --subject Notes --text-file - aiinbx send --from you@yourdomain.com --to a@example.com --subject Welcome \ --react emails/welcome.tsx --props '{"name":"Ada"}' \ --scheduled-at 2026-10-01T09:00:00Z ``` ```text Idempotency key 4e306697-7390-43c4-8e61-cb5a455ff376 ✓ Sent msg_5c2e… to a@example.com (sent) ``` `--react` renders a [React Email](/integrations/react-email) component with the `react` and `@react-email/render` installed in the template's own project. Every send carries an [idempotency key](/reference/conventions), `--idempotency-key` or a generated one, so a retried send never goes out twice. ## Listen: webhooks on localhost ```sh aiinbx listen --forward-to localhost:3000/api/webhooks ``` ```text Ready. Forwarding every event to http://localhost:3000/api/webhooks Signing secret whsec_jeMeEt8G… (aiinbx listen --print-secret) Ctrl-C to stop. 18:54:11 email.received evt_a1b2c3… → 200 7 ms 18:54:12 email.delivered evt_b2c3d4… → 200 1 ms 18:54:40 email.bounced evt_c3d4e5… → 500 3 ms ``` `listen` forwards your workspace's events to a URL on your machine. Each one arrives as a real [webhook delivery](/webhooks) would: the same JSON body, the same `AIInbx-Event-Id` and `AIInbx-Signature` headers, the same [signature scheme](/webhooks/verifying). There is no tunnel to run and no endpoint to register. The CLI reads the [events API](/api) every two seconds and posts what is new. The deliveries are signed with a secret of your profile's own. It stays the same from run to run, so put it in your app's environment once: ```sh aiinbx listen --print-secret # whsec_… AI_INBX_WEBHOOK_SECRET=$(aiinbx listen --print-secret) npm run dev ``` Your handler's `verifyWebhookRequest(request, process.env.AI_INBX_WEBHOOK_SECRET)` then accepts local deliveries unchanged. In production the same code gets the endpoint's secret. ```sh aiinbx listen --forward-to localhost:3000/api/webhooks \ --events email.received,email.bounced \ --since 1h ``` - `--events` forwards only these types. - `--since` replays from an ISO 8601 time or a duration ago (`15m`, `2h`) before it goes on listening. Without it, `listen` starts with what happens next. - At a terminal it prints a line per event: its time, type and id, what your server answered, and how long it took. Anywhere else it prints one JSON object per line: `{"event_id","type","created_at","status","latency_ms","error"}`. - A server that is down or answers an error is logged, and the next event still goes out. `listen` is not retried like a real endpoint. :::note[The summary body] Deliveries carry the body every endpoint receives. The `data.email` that an endpoint with `payload: "full"` is also sent is not included. Read the email by `data.email_id`. ::: ## Wait: block until an email arrives ```sh aiinbx wait --to qa@yourdomain.com --subject "verification code" --timeout 1m ``` ```text id msg_8c1e4f… thread_id thr_3f9a2c… from Acme to qa@yourdomain.com subject Your verification code created_at 2026-09-26T16:54:11.706Z text Your code is 482913. ``` `wait` blocks until a matching email arrives, prints it and exits `0`. When `--timeout` passes first (two minutes by default), it exits `124`, as `timeout` does. It is made for agents and end-to-end tests: sign up, wait for the verification email, read the code. | Flag | Matches | | ------------------------- | --------------------------------------------------------- | | `--from ` | Part of the sender: an address, a domain or a name | | `--to ` | Part of a recipient, in `to` or `cc` | | `--subject ` | Part of the subject | | `--thread ` | Only this thread | | `--direction ` | `inbound` (the default) or `outbound` | | `--since