CLI

unitpost is the official command line: one command per API operation, generated from the same OpenAPI contract as the SDKs. Install it, sign in once, and send from your shell, your scripts, and your agents.

Install

No runtime dependencies. Homebrew and the install scripts give you a standalone binary that doesn't need Node.js, and the scripts check the download's SHA-256 first. With Node.js 20+ you can use npm instead. Each command below installs it on its own; pick the one for your machine.

Homebrew (macOS, Linux)
brew install unitpostcom/tap/unitpost
Install script (macOS, Linux)
curl -fsSL https://www.unitpost.com/install.sh | sh
PowerShell (Windows)
irm https://www.unitpost.com/install.ps1 | iex
npm (Node.js 20+)
npm install -g unitpost-cli

For a one-off without installing: npx unitpost-cli@latest --help.

Sign in

On your own machine, unitpost login opens your browser and completes an OAuth 2.1 authorization-code flow with PKCE against the same authorization server the MCP server uses, so one sign-in model covers both. The token lives in the macOS Keychain (a 0600 file elsewhere) and refreshes automatically. By default it asks for every permission its commands use, the same set the MCP server asks for. Untick any you don't want on the approval page, or ask for less with repeated --scope flags. Your workspace role caps what is granted either way. See and revoke sign-ins in Settings → Connected apps.

Sign in
unitpost login                  # browser sign-in (OAuth 2.1 + PKCE)
unitpost login --no-browser   # prints the URL, for SSH and remote shells
unitpost login --key          # paste a key instead (headless, CI-friendly)
unitpost whoami               # which credential is in effect, and its scopes

First commands

Commands read as unitpost <resource> <action>. Required fields are flags; ids are positional. Append --help to any command to see its flags, with required-ness, enum values, and the spec's own descriptions.

First run
unitpost whoami           # credential check that actually hits the API
unitpost --help            # 18 resources, 256 commands
unitpost email send --help # flags for one command
unitpost doctor            # diagnose the whole setup in one command

Credentials

Every run resolves one credential, in this order: --api-key, then UNITPOST_API_KEY, then your saved login. An environment variable always wins over a saved login, which is what you want on a shared machine or in CI. unitpost logout removes the local credential and revokes the server grant (best-effort offline). A key's scope (full access, sending, read only, or a custom list) limits every command it runs; see API keys.

Profiles

Each sign-in is a named profile. Keep one per workspace or environment and switch between them without signing in again. The CLI never prints a secret: listings show a masked form.

Profiles
unitpost login --profile staging   # a second credential
unitpost auth list                   # all profiles, masked
unitpost auth switch staging         # change the default
unitpost email list --profile staging  # one command, another profile

Organization keys

A platform that gives each customer a workspace, or someone running several businesses, drives the organization API with an organization key (ok_live_…, made by an Owner on Organization → API → Create key). unitpost org … uses only that key and the organization's id, never your workspace sign-in; every other command uses only the workspace credential. Tick "Can change plans and use the shared plan" (organizations:billing) when you make the key if it will put workspaces on the shared plan or change their plans. See Organizations, workspaces and billing.

Organization keys
export UNITPOST_ORG_KEY=ok_live_…        # or --org-key
export UNITPOST_ORGANIZATION_ID=org_…    # or --org
unitpost org workspaces create --name "Acme Bakery" --external-id cust_42 \
  --shared-plan --idempotency-key cust_42-create
unitpost org workspace-keys create ws_123 --name Production --scope sending
unitpost org shared-plan get
unitpost org shared-plan update-workspace ws_123 --cap-cents 2500
unitpost org shared-plan remove-workspace ws_123 --yes

Commands

The tree is generated from the OpenAPI snapshot, 256 commands, one per operation, so a new endpoint becomes a documented, shell-completable command with no CLI code change, and drift fails CI. A few convenience flags (--html-file, --attach, --var, --file) rewrite into real flags for things shells express badly: --file ./optin.png on files create and the image uploads (library-images create, branding set-logo, workspace set-image) reads the file and sends it as base64, up to about 4 MB. One deliberate absence: creating and revoking keys. unitpost api-keys list and api-keys usage read them; any other api-keys command explains that keys are created and revoked in the dashboard, because those endpoints take a session, not a Bearer token.

Global flags

Every command accepts these. Environment fallbacks where they exist.

FlagWhat it does
--api-keyOne-off credential. Prefer the env var or a profile: flags leak into shell history and ps.
-p, --profileUse a named saved credential for one command.
--base-urlOverride the API origin (or UNITPOST_BASE_URL).
--jsonMachine output: exactly one JSON document on stdout, notes on stderr.
-q, --quietImplies --json and prints only the result document.
-y, --yesAnswer yes to confirmations. Required in non-interactive shells.
--debugLog method, path, status, and request id to stderr (or UNITPOST_DEBUG).
--dry-runValidate and print the resolved request. Exit 0, no network.
--idempotency-keyOverride the auto-generated key on writes.
--bodyRaw JSON document, inline, from @file, or from stdin with -.
--no-colorPlain output (also honors NO_COLOR and dumb terminals).

Output modes

Two modes, picked for you. On a terminal you get formatted, colored output and tables. When stdout is piped, CI is set, or you pass --json, you get exactly one JSON document on stdout and nothing else. Progress always goes to stderr, so a redirect is always valid JSON. Exit codes: 0 success, 1 the request failed, 2 the command itself was wrong (with a closest-match suggestion).

Scripting
# Pipe straight into jq: stdout is only ever the result document
unitpost email list --limit 100 | jq -r '.data[] | select(.status=="bounced") | .to'

# Capture an id for the next step
id=$(unitpost email send --from you@yourdomain.com --to a@acme.com \
  --subject Hi --text Hi --json | jq -r .id)

# Preview a send without touching the network
unitpost email send --from you@yourdomain.com --to a@acme.com \
  --subject Hi --text Hi --dry-run

Safety

Destructive commands ask first and refuse to guess in a non-interactive shell without --yes. Every write carries an idempotency key, generated for you and overridable with --idempotency-key, so a retried request replays the original result instead of sending twice. Preview anything with --dry-run: it validates and prints the resolved request, then exits 0 without touching the network. Shell completion covers commands and flags:

Completion
# Tab completion for every command and flag, generated from the API catalog
eval "$(unitpost completion bash)"   # or: zsh
unitpost completion fish > ~/.config/fish/completions/unitpost.fish

Agents

The CLI is built to be driven. The agent skill teaches the mapping (email_send becomes unitpost email send), JSON on stdout and stable exit codes make output parseable, and --dry-run lets an agent show its work before anything sends. Prefer MCP for tool calls inside a chat session and the CLI for shells, scripts, and CI: same operations, same scopes, same gates either way.

From a script
# CI: no login step, just the key
export UNITPOST_API_KEY="pk_live_..."
unitpost email send --from you@yourdomain.com --to ops@acme.com \
  --subject "Deploy finished" --text "All green."

CI

No login step: put the key in the environment, pass --yes where a command would confirm, and gate the job on unitpost doctor, which exits non-zero when anything is off. The CLI checks for updates about once a day on stderr; silence it with NO_UPDATE_CHECK=1.

Troubleshooting

Start with unitpost doctor: version, credential source, storage, base URL, API acceptance, and sending domain in one pass. Credential rejections name the fix (unitpost whoami, unitpost login). Every failure carries the API request id; rerun with --debug to see method, path, status, and id on stderr.

Search docs and guides

Search the docs and product guides.