CLI quickstart

The pushrail command-line tool drives your workspace from a terminal or a CI job: manage destinations and customers, send and replay events, stream live deliveries to a local endpoint, and inspect metrics, logs, and the audit trail. This page takes you from install to your first delivered event.

1. Install

Install the CLI globally with your package manager of choice:

npm install -g @pushrail/cli

pnpm add -g @pushrail/cli

The binary is pushrail. Confirm it's on your path:

pushrail --version

2. Log in

The fastest way to sign in is through your browser — no key to paste:

pushrail login

This opens your browser to approve access, where you pick the workspace to use. Your session refreshes automatically. On a headless box or over SSH, run pushrail login --device and enter the displayed code in any browser.

For CI — or any time you'd rather use a key — sign in with one instead:

pushrail login --api-key pr_dev_…

Create a key from Settings → API keys in the dashboard (see Authentication for scopes and rotation). The key's prefix encodes its environment, pr_dev_, pr_sta_, or pr_pro_.

The CLI stores credentials under ~/.pushrail/ (file mode 0600). For CI, or when you'd rather not persist a key, set PUSHRAIL_API_KEY in the environment instead of running login.

3. Check your setup

pushrail doctor diagnoses your config, authentication, and API reachability in one pass:

pushrail doctor

To confirm which credential is active and which workspace and environment it resolves to:

pushrail auth whoami

4. Send your first event

pushrail events send order.completed \
  --source checkout-service \
  --customer cust_42 \
  --payload '{"orderId":"ord_9001","totalCents":4999,"currency":"USD"}'

--customer is the customer's external id (customerExternalId). On success the CLI prints the event status and id. Add --dry-run to print the request body without sending it.

5. Watch deliveries

Tail the delivery activity stream as events flow through:

pushrail logs --follow

For a rollup of events accepted, deliveries, dead-lettered count, and fleet success rate:

pushrail metrics summary

6. Local dev loop

pushrail listen opens a live stream of deliveries for one customer and forwards each matching payload to a local URL, handy for developing a webhook receiver against real events:

pushrail listen \
  --customer cust_42 \
  --forward-to http://localhost:3000/webhooks

pushrail dev wraps listen and also prints a trigger hint so you can fire a test event from another shell:

pushrail dev --customer cust_42 --forward-to http://localhost:3000/webhooks

What's next

• CLI command reference, every command, flag, and exit code.
• CLI configuration, profiles, environment variables, and project config.

Every command accepts --json (or --output json|yaml) for machine-readable output you can pipe into other tools.