# CLI overview {#cli-overview}


Use the Nitrosend CLI when you're scripting CI, building an agent runner, or operating Nitrosend from a terminal. It is the Nitrosend MCP callable from a shell: same tools, same envelope, plus exit codes, dry-run, project context, and typed confirmation.



> [!IMPORTANT]
> All plans, including free plans, have full access to Nitrosend MCP/API/CLI. The CLI is not a paid-plan feature; plan limits apply to usage volume and paid add-ons.





> [!IMPORTANT]
> If you're using Claude Desktop, Claude.ai, or Claude Cowork, do not install the CLI to connect Nitrosend. Enable the official Nitrosend connector under **Settings → Connectors** instead (see [Claude Desktop](https://docs.nitrosend.com/integrations/claude-desktop.md)). The CLI is for shell workflows that run outside the Claude connector.




## When to use which surface {#when-to-use-which-surface}


Nitrosend exposes three peer surfaces over the same platform. Pick the one that matches where your work lives.

| Surface | Reach for it when | Skip it when |
|---|---|---|
| **MCP via chat client** (Claude Code, ChatGPT, Cursor, …) | You want a conversation with the platform — drafting copy, exploring data, planning sends. | You need deterministic, scriptable behaviour. |
| **CLI** (`nitrosend`) | You're scripting CI, building an agent runner, or running Nitrosend from a terminal. You need exit codes, JSON envelopes, dry-run, typed prod confirmation. | You're connecting Claude Desktop, Claude.ai, or Cowork; enable the Nitrosend connector instead. You're integrating Nitrosend into application code. |
| **[REST API](https://docs.nitrosend.com/integrations/rest-api.md)** | You're integrating Nitrosend into application code, sending transactional messages from a backend, or wiring up a partner integration. | You need the MCP envelope's `next_action` / `blockers` guidance fields. |

The CLI calls the same MCP tools your chat client calls and returns the same envelope shape — the difference is contract: it has stable exit codes, machine-readable output modes, and refuses unsafe ops in non-interactive mode.


## First workflow {#first-workflow}


Three commands to confirm the CLI is wired up to your account.

```bash
nitrosend login
nitrosend whoami
nitrosend
```

`nitrosend login` runs OAuth in your browser. `whoami` prints the active profile and API endpoint. The bare `nitrosend` invocation runs the dashboard — account state, blockers, and suggested next actions.

For CI or headless workflows, swap OAuth for an API key:

```bash
nitrosend login --api-key nskey_live_...
# or
export NITROSEND_API_KEY=nskey_live_...
nitrosend mcp tools list
```

See [Install & sign in](https://docs.nitrosend.com/cli/install.md) for the full setup, [Agent mode](https://docs.nitrosend.com/cli/agent-mode.md) for the machine-readable contract, and [Recipes](https://docs.nitrosend.com/cli/recipes.md) for end-to-end examples.


## What the CLI doesn't try to be {#what-the-cli-doesnt-try-to-be}


The CLI is for deterministic shell workflows. It is not a replacement for the chat experience or the dashboard. It does not own features the MCP doesn't expose — every command is a sensible thing to call from a shell *and* has a clean MCP analogue. If you need a richer composer, use a chat MCP client. If you need to ship Nitrosend inside an application, use the [REST API](https://docs.nitrosend.com/integrations/rest-api.md).

For image media files in templates and campaigns, v1 does not add a separate
`nitrosend media upload` command. Use the REST direct-upload flow instead:
reserve `/v1/direct_uploads` with `purpose=image` or `purpose=media_asset`, PUT
the bytes to the returned upload URL, then submit the returned `signed_id` to
`/v1/my/images`.
