@samva/cli

The samva CLI sends and operates email from a terminal. The npm package includes the JavaScript implementation and selects a self-contained native executable when one is available. Template authoring commands run the project's @samva/vite toolchain under Node.js 22 or newer.

Install

npm install -g @samva/cli
samva --help

The npm package prefers the matching macOS or Linux executable. If npm omits optional dependencies, the same command falls back to the packaged JavaScript implementation when Bun is installed. Compiled binaries are also available from GitHub releases.

Shell completions

Generate a completion script from the installed CLI. Regenerate it after upgrading the CLI.

# Bash
samva --completions bash >> ~/.bashrc

# Zsh
mkdir -p ~/.zsh/completions
samva --completions zsh > ~/.zsh/completions/_samva
# Add ~/.zsh/completions to fpath, then run `autoload -Uz compinit && compinit` in .zshrc.

# Fish
mkdir -p ~/.config/fish/completions
samva --completions fish > ~/.config/fish/completions/samva.fish

# sh is an alias for the Bash-compatible script
samva --completions sh

Authentication and execution context

For agents and CI, set an organization-scoped API key:

export SAMVA_API_KEY="samva_sk_live_..."

For interactive use, sign in with OAuth and choose an organization:

samva login
samva org list
samva org use <slug>

SAMVA_API_KEY takes precedence over a stored OAuth credential. An API key is already scoped to one organization, so --org and SAMVA_ORG are rejected when it is set. With OAuth, organization selection resolves as --org, then SAMVA_ORG, then the selected profile's organization.

samva login is interactive. In a non-TTY, use SAMVA_API_KEY for automation or explicitly choose the device flow with samva login --no-browser; --no-input, --json, and --jsonl reject login. If a stored OAuth record is malformed, run samva logout and then samva login; API-key calls do not read or decode stored OAuth credentials.

Profiles hold non-secret target and organization settings. Credentials stay in the OS keyring.

samva profile create local --target local
samva profile use local
samva --profile local email doctor

The profile resolves as --profile, then SAMVA_PROFILE, then the active profile, then default. The API URL resolves as --api-url, then SAMVA_API_URL, then the profile target. local targets the Portless API origin https://api.samva.localhost. production targets https://api.samva.dev.

Common operations

# Send an inline email. --to is repeatable.
samva email send --to [email protected] --subject "Hello" --text "Hi!"

# Pipe the plain-text body from stdin.
printf 'Hi from a pipeline' | samva email send \
  --to [email protected] --subject "Hello" --text -

# Pipe a rendered HTML body from stdin.
render-email | samva email send \
  --to [email protected] --subject "Hello" --html -

# Render a published template.
samva email send --to [email protected] --template-slug welcome-email \
  --template-data '{"name":"Ada"}'

# Wait for delivery or a terminal delivery outcome.
samva email send --to [email protected] --subject "Hello" --text "Hi!" \
  --wait --timeout 2m

# Inspect a message and its events.
samva messages get <message-id>
samva messages events <message-id> --json

# Inspect configuration and remote email state without mutating it.
samva email doctor --json

# Read and set organization open/click tracking defaults.
samva email tracking defaults get
samva email tracking defaults set --opens on --clicks off

# Pull and push the organization email design kit as Tailwind `@theme` CSS.
samva email design pull
samva email design push --dry-run

Template projects

Scaffold a project with the Samva TSX runtime, visual editor, and pinned authoring dependencies:

mkdir transactional-email && cd transactional-email
samva templates init
npm install
npm run samva:dev

The generated project lists @samva/markup and @samva/vite as development dependencies and Vite as the editor peer. The compiled CLI deliberately loads @samva/vite/build from the current project, so preview and push use the compiler version recorded in that project's lockfile.

samva templates push --dir emails --dry-run
samva templates push --dir emails

Inline email requires --subject and exactly one body source: --html or --text. Pass - as the value to read that body from stdin: --text - reads a plain-text body and --html - reads an HTML body. Only one body may come from stdin, so passing both --text - and --html - is rejected. Template sends use exactly one of --template-id or --template-slug, with optional --template-data, and omit --subject.

--wait polls until the message is delivered or read, or reaches a terminal failure. It defaults to a two-minute timeout. --timeout is valid only with --wait, and --wait cannot combine with --dry-run, since a dry run makes no API call and has nothing to wait on. A timeout or terminal delivery failure returns non-zero after printing the last message state.

Scheduling and campaigns

samva scheduled-messages create --to [email protected] --template-slug welcome-email \
  --template-data '{"name":"Ada"}' --at 2026-08-01T09:00:00Z \
  --timezone America/New_York --idempotency-key welcome-ada
samva scheduled-messages list --status pending
samva scheduled-messages get <scheduled-message-id>
samva scheduled-messages cancel <scheduled-message-id> --yes

samva campaigns create --name "August launch" --template-slug august-launch \
  --include-tags newsletter
samva campaigns runs create <campaign-id> --at 2026-08-01T09:00:00Z \
  --idempotency-key august-launch
samva campaigns runs recipients <campaign-id> <run-id> --status failed

--at is an absolute ISO 8601 instant. --timezone is display and audit metadata for a scheduled message. Campaign definitions freeze after their first run. Cancelling a scheduled message or campaign run requires confirmation, and dispatch already in progress may still finish.

Automation contract

Use --dry-run on supported mutations to validate input and preview the intended request. email send --dry-run does not use credentials or call the API. Other previews may read state when needed to show the resulting change. Destructive operations prompt in a TTY; automation must use --yes, or it fails without changing state. --no-input prevents prompts and browser launches.

# Review a request without authentication or an API call.
samva email send --to [email protected] --subject "Hello" --text "Hi!" --dry-run --json

# Traverse every page as one JSON record per line.
samva messages list --all --jsonl

# Suppress successful human output.
samva --quiet profile use local

--json writes one bounded, versioned result envelope to stdout: {schemaVersion:1,type:"result",command,data}. For resource lists, --jsonl writes one flat, independently parseable outer result envelope per resource. Errors use the corresponding {schemaVersion:1,type:"error",command,reason,message,next?} envelope on stderr and exit non-zero. --json, --jsonl, and --quiet are mutually exclusive; assignment forms such as --json=true are usage errors. --quiet suppresses successful output only. In machine modes, stdout contains only result data; warnings and errors go to stderr.

Lists are paginated by default. Use --page and --limit for a bounded page. --all requires --jsonl, so an automated traversal stays streamable rather than producing an unbounded JSON document. --all changes traversal only: bounded and unbounded JSONL records have the same outer envelope, with the resource itself in data. Empty lists emit no records.

Exit codes are stable for automation:

| Code | Meaning | | ----: | ------------------------------------------------------------------------ | | 0 | Success | | 1 | API, operational, or terminal delivery failure | | 2 | Command syntax, validation, configuration, or confirmation failure | | 4 | Authentication or organization-context failure, incl. an expired session | | 124 | Wait or credential timeout | | 130 | Interrupted with SIGINT | | 143 | Terminated with SIGTERM |

When --json or --jsonl is set, failures are emitted as JSON diagnostics on stderr, while stdout remains a clean data stream. Lifecycle timeout, terminal delivery failure, and a later observation failure are the intentional exception: they first preserve the last authoritative Message in a result envelope with partial:true on stdout.

samva webhooks test is another result-bearing failure: an endpoint timeout, transport failure, or non-2xx response preserves the complete test result on stdout, emits a typed diagnostic on stderr, and exits 1. Unlike lifecycle polling, that result is complete and does not set partial:true.

Help and command map

samva --help
samva help --json
samva email send --help

Released top-level commands are login, logout, org, email, messages, campaigns, scheduled-messages, templates, webhooks, profile, and help. Use samva <command> --help for flags and runnable examples.

Test a configured webhook against its real endpoint with an optional JSON payload. --data accepts inline JSON or @file; omit it for Samva's default test event. --dry-run validates and previews the request without credentials, an API call, or an endpoint delivery.

samva webhooks test wep_abc123 --dry-run
samva webhooks test wep_abc123 --data '{"event":"webhook.test"}' --json
samva webhooks test wep_abc123 --data @payload.json --json

samva email doctor reports resolved profile, target, API URL, auth source, organization access, sending domains, senders, and domain-verification readback. It is read-only and does not inspect receiving configuration, verify DNS, send an email, replay fixtures, or check provider readiness. Use samva email receiving status <domain-id> to read a domain's receiving prerequisite status. samva email receiving enable <domain-id> ... acts by default; its --dry-run is offline and does not require credentials or call the API. Each check is passed, failed, or unavailable. A failed check carries the underlying error detail; unavailable, such as no sending domain configured yet, is informational. The command always prints the full report, then exits 1 if any check failed and 0 otherwise. The --json result's data adds an aggregate ok boolean, and human output marks checks with ✓, !, and ✗ respectively.

A command that needs a subcommand, such as a bare samva or a group like samva email, prints its help to stdout and exits 2, so a script never mistakes a missing subcommand for success.