# Command reference {#command-reference}


This page is generated from the command descriptors of `@nitrosend/cli` 0.3.11. `nitrosend <command> --help` prints the same usage and examples, and `nitrosend describe <command> --json` returns the full descriptor: every flag with its type and allowed values, which are required, the safety class and the idempotency policy.



> [!TIP]
> In agent runners, prefer `nitrosend describe` over this page. The descriptor returned by the CLI always matches the binary you're running.




## Core {#core}


| Command | Summary |
|---|---|
| `nitrosend` | Show local profile state, cached account state, blockers, and suggested next actions. |
| `nitrosend status [--json]` | Show live authenticated account health, onboarding state, and next actions. |
| `nitrosend describe <command> [--json]` | Return descriptor, schemas, examples, and safety metadata for a command. |
| `nitrosend completion <bash\|zsh\|fish>` | Generate shell completion for bash, zsh, or fish. |
| `nitrosend recent [--json]` | Show redacted recent commands. |
| `nitrosend redo [index] [--explain]` | Show or re-run a recent command. |


## Auth {#auth}


| Command | Summary |
|---|---|
| `nitrosend login [--api-key <key>] [--no-browser] [--api-url <url>] [--profile <name>]` | Store an API-key profile, or start browser OAuth when no API key is provided. |
| `nitrosend signup --email <email> --password-stdin [--utm-source <s>] [--utm-medium <m>] [--utm-campaign <c>] [--api-url <url>] [--profile <name>]` | Begin email-verified signup without changing the current profile. |
| `nitrosend signup verify --verification-stdin [--api-url <url>] [--profile <name>]` | Verify email, choose the final password and save an API-key profile. |
| `nitrosend signup resend --email <email> [--api-url <url>]` | Request another verification email; address and global limits apply. |
| `nitrosend signup resume --email <email> --password-stdin [--api-url <url>] [--profile <name>]` | Recover a verified signup after an interrupted activation or profile write. |
| `nitrosend logout` | Remove the active local profile. |
| `nitrosend whoami [--json]` | Show active auth source, profile, and API endpoint. |


## Messages {#messages}


| Command | Summary |
|---|---|
| `nitrosend send --to <recipient> (--subject <text> --body <text>\|--template-id <id>) [--cc <addresses>] [--bcc <addresses>] [--channel email\|sms] [--idempotency-key <key>] [--dry-run]` | Send one transactional email or SMS now from the account's sender. |


## Contacts {#contacts}


| Command | Summary |
|---|---|
| `nitrosend contacts import <file> --list-id <id> [--json]` | Direct-upload a CSV file and create a contact import. |


## Data {#data}


Read-only list commands call `nitro_query` and return paginated rows.

| Command | Summary |
|---|---|
| `nitrosend flows list [--status <status>] [--search <text>] [--page <n>] [--per <n>]` | List flows. |
| `nitrosend campaigns list [--status <status>] [--search <text>] [--page <n>] [--per <n>]` | List campaigns. |
| `nitrosend contacts list [--query <text>] [--list-id <id>] [--page <n>] [--per <n>]` | List contacts. |
| `nitrosend lists list [--search <text>] [--page <n>] [--per <n>]` | List contact lists. |
| `nitrosend templates list [--search <text>] [--page <n>] [--per <n>]` | List templates. |
| `nitrosend suppressions list [--email <email>] [--reason <reason>] [--source-provider <provider>] [--active <true\|false>] [--page <n>] [--per <n>]` | List account suppressions with bounce diagnostics. |


## Inbox {#inbox}


Read and act on the agent inbox. An account without the agent inbox reports that it is not enabled.

| Command | Summary |
|---|---|
| `nitrosend inbox list [--query <text>] [--inbox-id <id>] [--status <status>] [--view compact\|full] [--page <n>] [--per <n>]` | List and search mailbox conversations. |
| `nitrosend inbox queue [--state <state>] [--inbox-id <id>] [--query <text>] [--sender <text>] [--reason-code <code>] [--since <iso8601>] [--sort queue\|newest] [--view compact\|full] [--page <n>] [--per <n>]` | List prioritized inbox action items as compact rows. |
| `nitrosend inbox get <conversation-id>` | Read one sanitized agent inbox thread. |
| `nitrosend inbox item <action-item-id>` | Read one prioritized inbox action item and its bounded thread context. |
| `nitrosend inbox reply <conversation-id> (--body <text>\|--html <html>) [--subject <text>] [--reply-all] [--cc <addresses>] [--bcc <addresses>] [--test-to <email>] [--idempotency-key <key>] [--dry-run] --confirm <conversation-id>` | Reply to a conversation, or send the reply draft to a test recipient. |
| `nitrosend inbox action <action-item-id> <mark-handled\|request-human\|release-to-agent\|mark-quarantine> [--idempotency-key <key>]` | Apply a handled, human, agent, or quarantine disposition to a queue item. |
| `nitrosend inbox triage <mark-handled\|request-human\|release-to-agent\|mark-quarantine\|classify-spam\|classify-not-spam> (--ids <id,id,...> \| [--state <state>] [--inbox-id <id>] [--query <text>] [--sender <text>] [--reason-code <code>] [--since <iso8601>] --expected-count <n>) [--idempotency-key <key>]` | Apply one disposition to many queue items, by id list or by the same filters as inbox queue. |


## MCP {#mcp}


The CLI is the Nitrosend MCP, callable from a shell. These commands dispatch JSON-RPC over HTTP to the same endpoint chat MCP clients use.

| Command | Summary |
|---|---|
| `nitrosend mcp initialize [--json]` | Initialize MCP handshake. |
| `nitrosend mcp tools list [--json]` | List MCP tools. |
| `nitrosend mcp tools call <name> [--args '{...}']` | Call an MCP tool. |
| `nitrosend mcp resources list [--json]` | List MCP resources. |
| `nitrosend mcp resources read <uri>` | Read an MCP resource. |
| `nitrosend mcp prompts list [--json]` | List MCP prompts. |
| `nitrosend mcp prompts get <name> [--args '{...}']` | Get an MCP prompt. |

The full set of available tools (`nitro_get_status`, `nitro_compose_campaign`, …) is documented under the [MCP Tools](https://docs.nitrosend.com/mcp.md) tab.


## Agent {#agent}


These commands are stable stubs for agent approval handoff.

| Command | Summary |
|---|---|
| `nitrosend approve <token>` | Approve a pending agent operation token. |
| `nitrosend reject <token>` | Reject a pending agent operation token. |


## Fixtures {#fixtures}


Test commands that exercise destructive safety UX without touching live data.

| Command | Summary |
|---|---|
| `nitrosend fixture destroy <name> --confirm <name>` | Exercise destructive safety UX without touching live Nitrosend data. |


## Release {#release}


| Command | Summary |
|---|---|
| `nitrosend version [--json]` | Show CLI version and runtime details. |
| `nitrosend update [--json]` | Show update guidance for the installed CLI. |


## Global options {#global-options}


Every command takes these.

| Option | Effect |
|---|---|
| `--help` | Print usage; after a command, that command's usage and examples. |
| `--version` | Print the CLI version. |
| `--json` | Print the JSON result envelope. |
| `--ndjson` | Print newline-delimited JSON. |
| `--csv` | Print rows as CSV. |
| `--machine` | Agent mode: implies --json --non-interactive --no-color --no-pager. |
| `--non-interactive` | Never prompt; fail closed when input would be needed. |
| `--no-color` | Strip ANSI colour. |
| `--no-pager` | Never page output. |
| `--dry-run` | Validate without side effects, where the command supports it. |
| `--yes` | Skip ordinary confirmations; never a typed confirmation. |
| `--explain` | Return the resolved plan as data and run nothing. |
| `--trace` | Write timing diagnostics to stderr. |
| `--profile <name>` | Use this stored profile. |
| `--api-url <url>` | Use this MCP endpoint. |

Older spellings still work: `--limit` for `--per`, `--list` for `--list-id`, `--json-args` for `--args`.

See [Agent mode](https://docs.nitrosend.com/cli/agent-mode.md) for the full envelope shape and exit code map.
