Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nitrosend--cli/badge.svg)](/listings/nitrosend--cli)

HTML

<a href="/listings/nitrosend--cli"><img src="/api/listings/nitrosend--cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. # @nitrosend/cli
  2. The Nitrosend command-line interface. Draft campaigns, send tests, run flows, query contacts, and inspect account state — from your terminal or a CI pipeline.
  3. 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.
  4. ```bash
  5. npm install -g @nitrosend/cli
  6. nitrosend login
  7. nitrosend
  8. ```
  9. Requires Node.js 18+.
  10. ## Quick start
  11. ```bash
  12. nitrosend login # browser-based OAuth (recommended)
  13. nitrosend # dashboard: account state, blockers, next actions
  14. nitrosend status # account health, onboarding, billing
  15. nitrosend flows list # your flows
  16. nitrosend campaigns list # your campaigns
  17. ```
  18. 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.
  19. ## What you can do
  20. ### Inspect
  21. ```bash
  22. nitrosend whoami # active profile + the MCP endpoint the CLI calls
  23. nitrosend status # live account, billing, preflight checks
  24. nitrosend flows list # --status --search --page --per
  25. nitrosend campaigns list
  26. nitrosend contacts list # --query --list-id
  27. nitrosend lists list
  28. nitrosend templates list
  29. ```
  30. ### Agent Inbox
  31. Agent Inbox commands are thin adapters over the existing `nitro_inbox` and
  32. `nitro_inbox_action` tools. They require Agent Inbox access for the active
  33. account and brand.
  34. ```bash
  35. nitrosend inbox list --query billing # search mailbox conversations
  36. nitrosend inbox queue # prioritized items needing attention
  37. nitrosend inbox get 123 # bounded, sanitized thread context
  38. nitrosend inbox item 456 # one queue item and its thread context
  39. nitrosend inbox reply 123 --body 'Thanks, we are on it.' --dry-run
  40. nitrosend inbox reply 123 --body 'Thanks, we are on it.' --confirm 123
  41. nitrosend inbox reply 123 --body 'Draft reply' --test-to me@example.com --confirm 123
  42. nitrosend inbox action 456 mark-handled
  43. nitrosend inbox action 456 request-human
  44. nitrosend inbox action 456 release-to-agent
  45. nitrosend inbox action 456 mark-quarantine
  46. ```
  47. Reply and action commands receive an automatic idempotency key. Pass
  48. `--idempotency-key <key>` when a caller needs to retry the same operation with a
  49. stable key. Real replies and test sends require typed conversation confirmation;
  50. `--dry-run` validates a reply without sending.
  51. ### Send and automate
  52. Send one email (or SMS with `--channel sms`) from your account's sender:
  53. ```bash
  54. nitrosend send --to you@example.com --subject 'Hello' --body 'First send.'
  55. nitrosend send --to you@example.com --subject 'Hello' --body 'First send.' --dry-run
  56. ```
  57. `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.
  58. The CLI exposes the full Nitrosend MCP surface — every tool an AI agent can call, you can call too:
  59. ```bash
  60. nitrosend mcp tools list
  61. nitrosend mcp tools call nitro_compose_campaign --args '{...}'
  62. nitrosend mcp tools call nitro_send_test_message --args '{...}'
  63. nitrosend mcp tools call nitro_get_status --args '{"include":["account"]}'
  64. ```
  65. Resources and prompts work the same way:
  66. ```bash
  67. nitrosend mcp resources list
  68. nitrosend mcp resources read nitro://account
  69. nitrosend mcp prompts list
  70. nitrosend mcp prompts get build-email --args '{"goal":"welcome series"}'
  71. ```
  72. ### Inspect, plan, and replay
  73. ```bash
  74. nitrosend describe campaigns list # schema + examples + safety class
  75. nitrosend recent # redacted history
  76. nitrosend redo 1 # re-run a previous command
  77. nitrosend redo 1 --explain # show the resolved plan, don't execute
  78. nitrosend <any-command> --dry-run # preview without persisting (where supported)
  79. ```
  80. ## Authentication
  81. OAuth (browser-based) is the default:
  82. ```bash
  83. nitrosend login
  84. ```
  85. 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.
  86. For CI or headless environments, use an API key — either as an environment variable (nothing written to disk):
  87. ```bash
  88. export NITROSEND_API_KEY=nskey_live_...
  89. nitrosend status
  90. ```
  91. …or stored in a local profile:
  92. ```bash
  93. nitrosend login --api-key nskey_live_...
  94. ```
  95. No account yet? Create one without a browser. The password is read from stdin, never from a flag:
  96. ```bash
  97. printf '%s' "$PASSWORD" | nitrosend signup --email you@example.com --password-stdin
  98. ```
  99. 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:
  100. ```bash
  101. nitrosend signup verify --verification-stdin --profile default < verification.json
  102. ```
  103. 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.
  104. 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:
  105. ```bash
  106. printf '%s' "$PASSWORD" | nitrosend signup resume --email you@example.com --password-stdin --profile default
  107. ```
  108. 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.
  109. `NITROSEND_BEARER_TOKEN` and `NITROSEND_API_KEY` always take precedence over stored profiles. `nitrosend logout` removes the active profile.
  110. 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.
  111. 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.
  112. ## Output and scripting
  113. Every command returns the same envelope under `--json`:
  114. ```json
  115. {
  116. "schema_version": 1,
  117. "ok": true,
  118. "command": "flows list",
  119. "data": { "rows": [ ... ] },
  120. "meta": { "duration_ms": 142 },
  121. "presentation": { "type": "table" }
  122. }
  123. ```
  124. Errors return `ok: false` with a structured `error` object (`code`, `message`, `retriable`).
  125. Useful flags:
  126. | Flag | Effect |
  127. |------|--------|
  128. | `--json`, `--ndjson`, `--csv` | Output mode |
  129. | `--machine` | Implies `--json --non-interactive --no-color --no-pager` |
  130. | `--explain` | Print the resolved plan; don't execute |
  131. | `--dry-run` | Preview changes without persisting (where supported) |
  132. | `--idempotency-key <key>` | Supply a stable retry key for idempotent mutations |
  133. | `--yes` | Skip non-destructive confirmations (typed confirmation still required for destructive ops) |
  134. | `--non-interactive` | Fail closed when input would be required |
  135. | `--trace` | Write a structured trace to stderr |
  136. JSON stdout is sacred: no spinners, prompts, or upgrade notices ever land there. Anything advisory goes to stderr.
  137. ### Exit codes
  138. | Code | Meaning |
  139. |------|---------|
  140. | `0` | Success |
  141. | `64` | Usage error |
  142. | `65` | Validation or data error |
  143. | `69` | Service unavailable / network error |
  144. | `70` | Internal error |
  145. | `75` | Temporary, retriable failure |
  146. | `77` | Authentication or permission error |
  147. | `78` | Unsupported / outdated CLI |
  148. See [`docs/ux-contract.md`](docs/ux-contract.md) for the full UX contract.
  149. ## Configuration
  150. Project-level defaults can live in `.nitrosend.yml`:
  151. ```yaml
  152. profile: default
  153. environment: production
  154. output: json
  155. ```
  156. `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.
  157. Environment variables:
  158. | Variable | Purpose |
  159. |----------|---------|
  160. | `NITROSEND_API_KEY` | API key (highest precedence) |
  161. | `NITROSEND_BEARER_TOKEN` | Pre-issued OAuth token |
  162. | `NITROSEND_API_URL` | Override the default endpoint (`https://api.nitrosend.com/mcp`) |
  163. | `NITROSEND_CONFIG_DIR` | Custom profile storage path |
  164. ## Shell completion
  165. ```bash
  166. nitrosend completion bash >> ~/.bashrc
  167. nitrosend completion zsh > "${fpath[1]}/_nitrosend"
  168. nitrosend completion fish > ~/.config/fish/completions/nitrosend.fish
  169. ```
  170. ## Upgrades
  171. ```bash
  172. nitrosend update # show guidance for the installed CLI
  173. npm install -g @nitrosend/cli@latest # upgrade
  174. ```
  175. 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.
  176. ## Related packages
  177. `@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.
  178. ## Issues
  179. Bug reports and feature requests: <https://github.com/nitrosend/cli/issues>.
  180. ## Working on the CLI
  181. ```bash
  182. npm ci
  183. npm run typecheck
  184. npm test
  185. npm run build
  186. node dist/index.js --help
  187. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.