Command-line Interface

The official postscale CLI supports domain setup, email sending, outbound and inbound inspection, and webhook delivery diagnostics. Version 1.0.0 is available for macOS, Linux, and Windows.

For a walkthrough of your first simulated send, follow the Postscale CLI quickstart.

Install

On macOS or Linux with Homebrew:

brew install postscale/tap/postscale

Download the matching archive and checksums.txt from the 1.0.0 release. Prebuilt binaries do not require Go.

Compare the archive's SHA-256 with its entry in checksums.txt before installing. For example, on macOS Apple Silicon:

shasum -a 256 postscale_1.0.0_darwin_arm64.tar.gz
tar -xzf postscale_1.0.0_darwin_arm64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 postscale "$HOME/.local/bin/postscale"
export PATH="$HOME/.local/bin:$PATH"
postscale --version

On Linux, use the Linux archive and sha256sum to check the hash. Add the PATH export to your shell startup file to keep it across sessions.

On Windows, verify with Get-FileHash, extract the ZIP, and add the directory containing postscale.exe to your user PATH. Full platform instructions are in the CLI README.

With Go 1.25 or newer, you can also install from source:

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

Add GOBIN, or $(go env GOPATH)/bin when GOBIN is unset, to your PATH.

Authentication and profiles

Set POSTSCALE_API_KEY through your shell or secret manager. The CLI can use that environment key directly, or save it in the OS keychain as a named profile:

postscale auth login --profile test
postscale auth status --profile test
postscale auth profiles
postscale auth use test

Use a ps_test_ key to simulate sending. A profile named test does not itself enable test mode. The output's context.credential_environment reports the selected key's environment. A ps_live_ key submits real email.

To read a key from a secret manager over stdin, add --key-stdin to auth login. Keys are saved in macOS Keychain, Windows Credential Manager, or Linux Secret Service. On headless systems without a keychain, use environment authentication.

An explicit --profile selects its stored credential and endpoint, ignoring ambient POSTSCALE_API_KEY and POSTSCALE_BASE_URL. auth status reports local configuration without verifying the key with the API.

Set up a domain

postscale domains create example.com --profile test
postscale domains dns example.com --profile test
postscale domains verify example.com --profile test
postscale domains list --all --json --profile test

Add the returned DNS records with your DNS provider before verification. Get, DNS, and verification commands accept a domain name or resource UUID. Creation defaults to outbound; --type also accepts inbound, both, and alias. See Domain Setup for DNS requirements.

Validate and send email

Create message.json with your sender and recipient addresses:

{
  "from": "sender@example.com",
  "to": ["recipient@example.net"],
  "subject": "Hello from Postscale",
  "text_body": "Hello"
}

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

The dry-run validates input locally without credentials or API requests. It does not verify domain ownership or sending eligibility. Test credentials record a simulated message without delivery, quota usage, or delivery webhooks.

Use API-native fields for HTML bodies, templates, variables, and base64 attachments. Sends are never automatically retried. After a network failure with an uncertain result, inspect email history before submitting again.

Inspect email and webhooks

postscale emails list --subject receipt --limit 25 --profile test
postscale emails get EMAIL_RESOURCE_UUID --profile test
postscale emails events EMAIL_RESOURCE_UUID --profile test
postscale inbound list --query invoice --all --profile test
postscale inbound get EMAIL_RESOURCE_UUID --profile test
postscale webhooks list --profile test
postscale webhooks deliveries list --status failed --days 7 --profile test

Use the id from email listing for get/events commands. The message_id returned by sending is an SMTP identifier and cannot be used in those commands.

Paginated lists support --limit (1–100, default 50), --offset, and --all. Webhook endpoint listing returns all endpoints in one request.

Scripts, upgrades, and support

Results are JSON by default; --json makes them compact. Errors are JSON on stderr. --timeout defaults to 30 seconds for the complete API operation, and --retries applies only to reads. Unverified domains and incomplete webhook history return nonzero exit codes while preserving diagnostic output.

Use postscale --help and postscale COMMAND --help to discover commands. postscale completion generates Bash, Zsh, Fish, or PowerShell completions.

Upgrade by downloading and verifying a newer archive, then replacing the binary. Go users can install a newer version tag. To remove saved credentials before uninstalling, run postscale auth logout --profile NAME for each profile; this does not revoke the API keys.

The CLI repository contains full installation instructions, release notes, and the issue tracker.