Skip to content

README.md

Latest commit

 

History

History
192 lines (141 loc) · 5.64 KB

README.md

File metadata and controls

192 lines (141 loc) · 5.64 KB

@nitrosend/cli

The Nitrosend command-line interface. Send email and SMS, run flows and campaigns, query contacts, and inspect account state — from your terminal or a CI pipeline.

npm install -g @nitrosend/cli
nitrosend login
nitrosend

Requires Node.js 18+.

Quick start

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 you can do

Inspect

nitrosend whoami                # active profile + endpoint
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

Send and automate

The CLI exposes the full Nitrosend MCP surface — every tool an AI agent can call, you can call too:

nitrosend mcp tools list
nitrosend mcp tools call nitro_send_message --args '{...}'
nitrosend mcp tools call nitro_compose_campaign --args '{...}'
nitrosend mcp tools call nitro_get_status --args '{"include":["account"]}'

Resources and prompts work the same way:

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

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:

nitrosend login

For CI or headless environments, use an API key — either as an environment variable (nothing written to disk):

export NITROSEND_API_KEY=nskey_live_...
nitrosend status

…or stored in a local profile:

nitrosend login --api-key nskey_live_...

NITROSEND_BEARER_TOKEN and NITROSEND_API_KEY always take precedence over stored profiles. nitrosend logout removes the active profile.

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:

{
  "schema_version": 1,
  "ok": true,
  "command": "flows list",
  "data": { "rows": [ ... ] },
  "meta": { "duration_ms": 142, "environment": "production" },
  "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)
--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 for the full UX contract.

Configuration

Project-level defaults can live in .nitrosend.yml:

profile: sandbox
environment: sandbox
output: json

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

nitrosend completion bash >> ~/.bashrc
nitrosend completion zsh > "${fpath[1]}/_nitrosend"
nitrosend completion fish > ~/.config/fish/completions/nitrosend.fish

Upgrades

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 — 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

npm ci
npm run typecheck
npm test
npm run build
node dist/index.js --help