Introducing the Postscale CLI

The official Postscale CLI is here. Version 1.0.0 brings domain setup, email sending, and delivery inspection to your terminal on macOS, Linux, and Windows.

When you are connecting an application to Postscale, the work often moves between code, DNS settings, and delivery history. The CLI gives those tasks a shared interface: check a domain's DNS records, submit a message from a JSON file, then look up what happened to it. The same commands also work in shell scripts and CI jobs.

Install and get started

On macOS or Linux with Homebrew:

brew install postscale/tap/postscale
postscale --version

You can also download a prebuilt binary for your platform from the 1.0.0 release. The release includes SHA-256 checksums, and the binaries do not require Go. If you prefer to build from source, Go 1.25 or newer can install the release directly:

go install github.com/postscale/postscale-cli/cmd/postscale@v1.0.0

The CLI quickstart covers installation, authentication, and your first simulated send.

Keep credentials in named profiles

Use a test API key for your first send. Set POSTSCALE_API_KEY through your shell or secret manager, then save it in your operating system's keychain:

postscale auth login --profile test
postscale auth status --profile test

Profiles let you choose credentials explicitly on each command. For example, you can keep separate test and live profiles and select one with --profile. The key determines how sending behaves: ps_test_ keys simulate sending, while ps_live_ keys submit real email. Naming a profile test does not change a live key into a test key.

For CI or a headless server without a supported keychain, use POSTSCALE_API_KEY directly and omit the profile flag. The CLI also accepts a key piped from a secret manager through auth login --key-stdin.

Check domain setup from the terminal

Adding a sending domain gives you a familiar sequence:

postscale domains create example.com --profile test
postscale domains dns example.com --profile test
postscale domains verify example.com --profile test

Replace example.com with a domain you control. Skip creation if it is already in your account. The DNS command shows the records to add at your DNS provider; run verification after you have published them.

Verification returns diagnostics and a nonzero exit code when the domain is not ready, so a script can stop before attempting a send. Test sends also require a verified sending domain. Domain commands update your account normally, even when you use a test key.

See the domain setup guide for SPF, DKIM, DMARC, and Return-Path configuration.

Try a message before sending it live

The CLI accepts the same JSON fields as the Postscale API. Save this as message.json, replacing the sender with an address on your verified domain:

{
  "from": "hello@example.com",
  "to": ["recipient@example.net"],
  "subject": "Hello from the Postscale CLI",
  "text_body": "This message started in a terminal."
}

First, check the payload locally:

postscale emails send --file message.json --dry-run

Dry-run validates the input without credentials or API requests. It is useful while editing a payload or checking a generated JSON file, but it does not check domain ownership or account eligibility.

Next, submit the message with your test key:

postscale emails send --file message.json --profile test

Postscale validates the request and records a simulated message you can inspect. It does not deliver email, consume sending quota, or emit delivery webhooks. Once your account is approved for live sending, use a profile containing a live key and your intended recipient to make a real send.

Messages can also come from stdin, which makes the CLI useful alongside an application's own payload generator:

cat message.json | postscale emails send --file - --profile test

HTML, templates, variables, and base64 attachments use the API's existing fields.

Follow an email through delivery

Search the message history to inspect your test send:

postscale emails list --subject "Hello from the Postscale CLI" --profile test
postscale emails get EMAIL_RESOURCE_UUID --profile test

Use the id returned by the list command for EMAIL_RESOURCE_UUID. The message_id returned by sending is an SMTP identifier and is different from this resource ID.

For production diagnostics, configure a live profile with a live API key. You can then inspect a live message's events, search received email, or find failed webhook deliveries:

postscale emails events EMAIL_RESOURCE_UUID --profile live
postscale inbound list --query invoice --profile live
postscale webhooks deliveries list --status failed --days 7 --profile live

These commands help answer practical questions: what events are recorded for this message, did an inbound email arrive, and which webhook deliveries failed? You can also list webhook endpoints and retrieve individual inbound messages.

Use the same commands in scripts

Results are JSON by default, with --json producing compact output. Errors go to stderr, and failed commands return nonzero exit codes. Paginated lists support --limit, --offset, and --all, so scripts can collect more than the first page of results.

Read requests support retries. Sends and other mutations are never automatically retried; if a network failure leaves a send's outcome uncertain, inspect the message history before submitting it again.

For interactive use, the CLI includes Bash, Zsh, Fish, and PowerShell completion. Run postscale --help to explore the commands or open the CLI reference for profiles, filtering, timeouts, and output details.

Start with the Postscale CLI quickstart, or visit the repository on GitHub for source code, releases, and the issue tracker.