Use the CLI
Sign in, select an organization, and send email from your terminal with the Samva 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.
Email first. Samva is launching with email. SMS, WhatsApp, and voice are staged and will be documented as they ship.
Private beta. The CLI ships as @samva/cli and is not yet published to npm. The command
surface below is stable; install instructions come with your beta access. 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.
Sign in interactively with the OAuth device flow — it opens your browser to approve the session:
samva login # add --no-browser to print the URL instead
samva logout # sign out and clear the stored sessionFor non-interactive use, set an API key in the environment:
export SAMVA_API_KEY="sk_sm_your_api_key"When both are present, an OAuth session takes precedence over SAMVA_API_KEY. Sessions have
no refresh token — run samva login again after one expires.
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 currentThe 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 \
--subject "Welcome to Samva" \
--html "<h1>Welcome!</h1>"
samva email status --message-id <id>--tois repeatable to address multiple recipients.- 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
--jsonto 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.
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 flagsConfiguration
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.