cli
Send email and SMS, run flows and campaigns, and call Nitrosend MCP tools from the terminal.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/nitrosend--cli)HTML
<a href="/listings/nitrosend--cli"><img src="/api/listings/nitrosend--cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
nitrosend login # browser-based OAuth (recommended) nitrosend # dashboard: account state, blockers, next actions nitrosend status # account health, onboarding, billing nitrosend flows list # your flows nitrosend campaigns list # your campaigns
Add `--json` to any command for a machine-readable envelope. `nitrosend describe <command>` returns the full input/output schema for any command.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 259 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # @nitrosend/cli
- The Nitrosend command-line interface. Draft campaigns, send tests, run flows, query contacts, and inspect account state — from your terminal or a CI pipeline.
- 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.
- ```bash
- npm install -g @nitrosend/cli
- nitrosend login
- nitrosend
- ```
- Requires Node.js 18+.
- ## Quick start
- ```bash
- nitrosend login # browser-based OAuth (recommended)
- nitrosend # dashboard: account state, blockers, next actions
- nitrosend status # account health, onboarding, billing
- nitrosend flows list # your flows
- nitrosend campaigns list # your campaigns
- ```
- Add `--json` to any command for a machine-readable envelope. `nitrosend <command> --help` prints a command's usage and examples, and `nitrosend describe <command> --json` returns its input schema (every flag, its type and allowed values, and which are required), safety class and examples.
- ## What you can do
- ### Inspect
- ```bash
- nitrosend whoami # active profile + the MCP endpoint the CLI calls
- nitrosend status # live account, billing, preflight checks
- nitrosend flows list # --status --search --page --per
- nitrosend campaigns list
- nitrosend contacts list # --query --list-id
- nitrosend lists list
- nitrosend templates list
- ```
- ### Agent Inbox
- Agent Inbox commands are thin adapters over the existing `nitro_inbox` and
- `nitro_inbox_action` tools. They require Agent Inbox access for the active
- account and brand.
- ```bash
- nitrosend inbox list --query billing # search mailbox conversations
- nitrosend inbox queue # prioritized items needing attention
- nitrosend inbox get 123 # bounded, sanitized thread context
- nitrosend inbox item 456 # one queue item and its thread context
- nitrosend inbox reply 123 --body 'Thanks, we are on it.' --dry-run
- nitrosend inbox reply 123 --body 'Thanks, we are on it.' --confirm 123
- nitrosend inbox reply 123 --body 'Draft reply' --test-to me@example.com --confirm 123
- nitrosend inbox action 456 mark-handled
- nitrosend inbox action 456 request-human
- nitrosend inbox action 456 release-to-agent
- nitrosend inbox action 456 mark-quarantine
- ```
- Reply and action commands receive an automatic idempotency key. Pass
- `--idempotency-key <key>` when a caller needs to retry the same operation with a
- stable key. Real replies and test sends require typed conversation confirmation;
- `--dry-run` validates a reply without sending.
- ### Send and automate
- Send one email (or SMS with `--channel sms`) from your account's sender:
- ```bash
- nitrosend send --to you@example.com --subject 'Hello' --body 'First send.'
- nitrosend send --to you@example.com --subject 'Hello' --body 'First send.' --dry-run
- ```
- `send` calls `nitro_send_message`, which requires an idempotency key. The CLI makes one for each run; pass your own `--idempotency-key` to retry the same send safely, since a retry with the same key never sends twice.
- The CLI exposes the full Nitrosend MCP surface — every tool an AI agent can call, you can call too:
- ```bash
- nitrosend mcp tools list
- nitrosend mcp tools call nitro_compose_campaign --args '{...}'
- nitrosend mcp tools call nitro_send_test_message --args '{...}'
- nitrosend mcp tools call nitro_get_status --args '{"include":["account"]}'
- ```
- Resources and prompts work the same way:
- ```bash
- nitrosend mcp resources list
- nitrosend mcp resources read nitro://account
- nitrosend mcp prompts list
- nitrosend mcp prompts get build-email --args '{"goal":"welcome series"}'
- ```
- ### Inspect, plan, and replay
- ```bash
- nitrosend describe campaigns list # schema + examples + safety class
- nitrosend recent # redacted history
- nitrosend redo 1 # re-run a previous command
- nitrosend redo 1 --explain # show the resolved plan, don't execute
- nitrosend <any-command> --dry-run # preview without persisting (where supported)
- ```
- ## Authentication
- OAuth (browser-based) is the default:
- ```bash
- nitrosend login
- ```
- It opens your browser and prints the sign-in URL to stderr. With `--no-browser` it only prints the URL, for a remote shell or another device.
- For CI or headless environments, use an API key — either as an environment variable (nothing written to disk):
- ```bash
- export NITROSEND_API_KEY=nskey_live_...
- nitrosend status
- ```
- …or stored in a local profile:
- ```bash
- nitrosend login --api-key nskey_live_...
- ```
- No account yet? Create one without a browser. The password is read from stdin, never from a flag:
- ```bash
- printf '%s' "$PASSWORD" | nitrosend signup --email you@example.com --password-stdin
- ```
- Signup returns `verification_required` and leaves your current profile untouched. Read the verification email, then supply JSON containing its `token` and your **final** `password` through stdin:
- ```bash
- nitrosend signup verify --verification-stdin --profile default < verification.json
- ```
- Keep that input file private and remove it after use, or stream the JSON directly from your secret store. Do not put passwords or verification tokens in command arguments. Verification creates the account, makes an API key, and saves that key as the profile. The final password replaces the password used to start signup.
- If the link expires, run `nitrosend signup resend --email you@example.com`. If verification succeeded but activation, key creation or local profile storage was interrupted, resume without another email:
- ```bash
- printf '%s' "$PASSWORD" | nitrosend signup resume --email you@example.com --password-stdin --profile default
- ```
- Use the same `--api-url` and `--profile` throughout. Resending has a one-minute cooldown and three-per-address daily limit; global acquisition limits also apply. Respect `Retry-After` on HTTP 429. Existing API-key and browser OAuth login remain available.
- `NITROSEND_BEARER_TOKEN` and `NITROSEND_API_KEY` always take precedence over stored profiles. `nitrosend logout` removes the active profile.
- Pass `--profile <name>` to `login`, `signup` or any command to keep several accounts side by side. A project's `.nitrosend.yml` can name one with `profile: <name>`, and its commands use that profile unless a flag says otherwise.
- Profiles live under your platform config directory (or `NITROSEND_CONFIG_DIR` if set), with directory permissions locked to your user. On shared machines, prefer the env-var form.
- ## Output and scripting
- Every command returns the same envelope under `--json`:
- ```json
- {
- "schema_version": 1,
- "ok": true,
- "command": "flows list",
- "data": { "rows": [ ... ] },
- "meta": { "duration_ms": 142 },
- "presentation": { "type": "table" }
- }
- ```
- Errors return `ok: false` with a structured `error` object (`code`, `message`, `retriable`).
- Useful flags:
- | Flag | Effect |
- |------|--------|
- | `--json`, `--ndjson`, `--csv` | Output mode |
- | `--machine` | Implies `--json --non-interactive --no-color --no-pager` |
- | `--explain` | Print the resolved plan; don't execute |
- | `--dry-run` | Preview changes without persisting (where supported) |
- | `--idempotency-key <key>` | Supply a stable retry key for idempotent mutations |
- | `--yes` | Skip non-destructive confirmations (typed confirmation still required for destructive ops) |
- | `--non-interactive` | Fail closed when input would be required |
- | `--trace` | Write a structured trace to stderr |
- JSON stdout is sacred: no spinners, prompts, or upgrade notices ever land there. Anything advisory goes to stderr.
- ### Exit codes
- | Code | Meaning |
- |------|---------|
- | `0` | Success |
- | `64` | Usage error |
- | `65` | Validation or data error |
- | `69` | Service unavailable / network error |
- | `70` | Internal error |
- | `75` | Temporary, retriable failure |
- | `77` | Authentication or permission error |
- | `78` | Unsupported / outdated CLI |
- See [`docs/ux-contract.md`](docs/ux-contract.md) for the full UX contract.
- ## Configuration
- Project-level defaults can live in `.nitrosend.yml`:
- ```yaml
- profile: default
- environment: production
- output: json
- ```
- `environment` is a local label: `production`, `staging`, `sandbox`, or `development`, and there is none unless the file sets one. The CLI shows it on command results and in `meta.environment`, and `production` makes every destructive command ask for a typed confirmation. It is not a sandbox. It does not change the endpoint, account, or brand, and commands send real mail under every label, `sandbox` included.
- Environment variables:
- | Variable | Purpose |
- |----------|---------|
- | `NITROSEND_API_KEY` | API key (highest precedence) |
- | `NITROSEND_BEARER_TOKEN` | Pre-issued OAuth token |
- | `NITROSEND_API_URL` | Override the default endpoint (`https://api.nitrosend.com/mcp`) |
- | `NITROSEND_CONFIG_DIR` | Custom profile storage path |
- ## Shell completion
- ```bash
- nitrosend completion bash >> ~/.bashrc
- nitrosend completion zsh > "${fpath[1]}/_nitrosend"
- nitrosend completion fish > ~/.config/fish/completions/nitrosend.fish
- ```
- ## Upgrades
- ```bash
- nitrosend update # show guidance for the installed CLI
- npm install -g @nitrosend/cli@latest # upgrade
- ```
- When the API signals a newer version is available, the CLI prints a one-line stderr notice. When the installed version is below the supported minimum, authenticated commands exit non-zero before running. The CLI does not poll the npm registry.
- ## Related packages
- `@nitrosend/cli` is the user-facing CLI. If you're integrating Nitrosend into an MCP-aware AI host (Claude Desktop, Cursor, etc.), use [`@nitrosend/mcp`](https://www.npmjs.com/package/@nitrosend/mcp) — a stdio bridge that proxies MCP traffic from the host to the Nitrosend HTTP endpoint.
- ## Issues
- Bug reports and feature requests: <https://github.com/nitrosend/cli/issues>.
- ## Working on the CLI
- ```bash
- npm ci
- npm run typecheck
- npm test
- npm run build
- node dist/index.js --help
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.