Use the CLI

The samva CLI drives the same email API from your terminal, handy for trying things out, scripting, and working across multiple organizations without writing code.

Install

npm install -g @samva/cli

npm install -g @samva/cli

yarn global add @samva/cli

pnpm add -g @samva/cli

bun add -g @samva/cli

Once installed, the samva command is on your PATH.

Authenticate

The CLI accepts either of Samva's two credential types. For when to use which, see API keys and OAuth sessions.

samva login            # add --no-browser to print the URL instead
samva logout           # sign out and clear the stored session

export SAMVA_API_KEY="samva_sk_live_your_api_key"

Select an organization

An API key is already scoped to one organization. An OAuth session is tied to your user, so it can act on any organization you belong to; pick the active one:

samva org list
samva org use <slug>
samva org current

The active organization is remembered between commands and sent as the x-org-slug header.

Send an email and check status

samva email send \
  --to ada@example.com \
  --cc grace@example.com \
  --reply-to support@example.com \
  --subject "Welcome to Samva" \
  --html "<h1>Welcome!</h1>"

samva email status --message-id <id>

• --to is repeatable to address multiple recipients.
• Use --cc, --bcc, and --reply-to for copy recipients and Reply-To headers.
• Provide exactly one body: --html, --text, or --template-id (with optional --template-data '<json>').
• --reply-to-message-id <id> threads the email into an existing conversation.
• Add --json to any command to print raw JSON for scripting.

Manage domains and senders

samva email domains list
samva email domains add --domain <domain>   # dry-run by default; pass --execute to apply
samva email domains check --id <id>          # check verification status

samva email senders list
samva email senders add --email <address>    # dry-run by default; pass --execute to apply
samva email senders check --id <id>

See Verify your domain for the full DNS walkthrough.

Schedule email and run campaigns

The CLI exposes the complete email scheduling lifecycle. Use the task guides for the exact commands, content rules, time semantics, and cancellation behavior.

Run a channel proof

The proof runners walk the email channel end to end, useful before you ship. Both default to a dry run that lists the checks; pass --execute to run them:

samva email proof local --execute              # against a local or dev API
samva email proof production --execute --yes    # production needs both flags

Configuration

The CLI keeps state under ~/.config/samva/: config.json for preferences (including the active organization) and credentials.json (mode 0600) for the OAuth session token. Override the API base URL with the SAMVA_API_URL environment variable.

Next steps