@postwave/cli

The official Postwave command-line interface. Drive migrations, run deliverability diagnostics, generate voice-trained sequences, manage subscribers and forms — all from your terminal or a CI pipeline.

Install

npm i -g @postwave/cli

Verify with postwave --version.

Authenticate

postwave login

This opens your browser, asks you to confirm in the dashboard, and stores an API key locally at ~/.config/postwave/credentials.json (mode 0600).

You can also skip the browser flow entirely:

postwave login --api-key pw_xxx
# or
export POSTWAVE_API_KEY=pw_xxx

Run postwave whoami to confirm the active tenant + email, and postwave logout to clear the stored credential.

Command reference

| Command | Purpose | |---|---| | postwave login | Browser-based or --api-key authentication. | | postwave logout | Remove stored credentials. | | postwave whoami | Show active tenant + user. | | postwave init | Interactive new-tenant onboarding. | | postwave migrate <source> | Run a migration (supports --dry-run, --commit, --rollback). | | postwave diagnose <campaign-id> | Pretty-printed Diagnostician output. | | postwave sequences {list, generate, regenerate} | Sequence operations. | | postwave templates {list, get} | Template browsing. | | postwave subscribers {list, search, suppress} | Subscriber operations. | | postwave forms {list, create} | Form operations. | | postwave inbox {report, predict, reputation, auth} | Deliverability suite. | | postwave automation {trigger, pause, resume} | Automation control. |

Add --output json|table|yaml to most read commands.

Examples

# Dry-run a Mailchimp migration
postwave migrate mailchimp --dry-run

# Diagnose the most recent campaign
postwave diagnose cmp_2026_05_01_a

# Predict inbox placement for a draft you have on disk
postwave inbox predict --file ./draft.html

Environment variables

| Var | Default | Purpose | |---|---|---| | POSTWAVE_API_KEY | — | Bypass stored credential. | | POSTWAVE_BASE_URL | https://api.postwave.app | API base; overridable for staging. | | POSTWAVE_TENANT_ID | — | Tenant slug when not encoded in the API key. |

Development

The CLI ships with a small set of authoring tools that complement the dashboard for people who live in the terminal.

postwave dev

Starts a local preview server that compiles *.email.tsx and *.mjml files in your current directory into email-safe HTML and renders them in a browser UI with hot-reload.

postwave dev
postwave dev --port 5173 --no-browser

Defaults:

• Port 4321 (or POSTWAVE_DEV_PORT).
• Watches the cwd recursively for *.email.tsx and *.mjml.
• Auto-opens http://localhost:<port>/ unless --no-browser is set.

The UI shows a file list, a desktop/mobile preview iframe with dark-mode toggle, an auto-detected variables form (driven by {{ .Field }} placeholders in the HTML), a persona switcher, a debounced subject co-pilot (3 ranked suggestions with predicted placement bars), and a "Send test to me" button that goes through pw.campaigns.sendTest.

Loading .email.tsx files requires tsx to be installed in your project (npm i -D tsx). The CLI prints a clear error if it is missing.

postwave logs tail

Streams live email events from pw.events.stream(...) straight to your terminal, pretty-printed with chalk. Ctrl-C to stop.

postwave logs tail
postwave logs tail --filter event_type=opened
postwave logs tail --filter campaign=cmp_2026_05_01_a

--filter may be repeated. Supported keys: event_type, campaign (alias campaign_id). Any other key=value filter is matched client-side against the event record.

postwave segments from-text

Compiles a natural-language description into a segment AST via pw.segments.compileFromNaturalLanguage(text), pretty-prints it, asks for confirmation, and saves it.

postwave segments from-text --query "premium VC subscribers in NYC"
echo "people who opened in the last 7 days" | postwave segments from-text --yes
postwave segments from-text --query "..." --name "premium-vc-nyc"

The segment name comes from --name, the server's suggested_name, or an auto-slug of the query.

postwave.test-personas.yaml

Optional file at the project root, used by postwave dev to populate the persona switcher. If absent, a single default persona is used.

personas:
  - name: VC Marc
    email: [email protected]
    custom_fields:
      first_name: Marc
      tier: premium
  - name: Free user
    email: [email protected]
    custom_fields:
      first_name: Pat
      tier: free

Credentials path

The CLI stores its credential file using conf:

• Linux/macOS: ~/.config/postwave/credentials.json
• Windows: %APPDATA%\postwave\Config\credentials.json

The file is written with 0600 permissions on POSIX systems.