Pushrail Docs
Open app
CLI

CLI command reference

Every pushrail command, flag, and exit code.

CLI command reference

Every pushrail command, grouped by area. Flags shown here come straight from the CLI source; anything not listed isn't a real flag. See CLI configuration for profiles, environment variables, and project config.

Global flags

These apply to every command:

  • --profile <name>, use a named profile.
  • --workspace <id> / --tenant <id>, the workspace (tenant) id.
  • --env <dev|staging|prod>, target environment.
  • --api-key <key>, API key for this invocation only.
  • --base-url <url>, override the API base URL.
  • --output <text|json|yaml>, output format (default text).
  • --json, shorthand for --output json.

--since / --until filters accept either a duration (24h, 1h) or an ISO timestamp.

Exit codes

| Code | Meaning | |---|---| | 0 | Success | | 1 | Request failed | | 2 | Usage error | | 3 | Not authenticated | | 4 | Not found | | 5 | Validation error | | 6 | Confirmation required |

profiles

Manage local CLI profiles (stored under ~/.pushrail/).

pushrail profiles list
pushrail profiles get <name>
pushrail profiles create <name> [flags]
pushrail profiles use <name>
pushrail profiles delete <name>

create flags: --base-url <url>, --tenant <id>, --env <env>, --api-key <key>.

login / logout / auth

Authenticate and inspect the active identity. By default login signs you in through your browser — no key to paste; you approve access and pick a workspace. For CI or machines without a browser, use --api-key or --device.

pushrail login                          # browser sign-in (default)
pushrail login --device                 # headless / SSH: enter a code in a browser
pushrail login --api-key pr_dev_…       # CI: sign in with an API key
pushrail logout [--profile <name>]
pushrail auth whoami
pushrail auth status
pushrail auth token --reveal
pushrail auth refresh
  • login flags: --api-key <key> (sign in with a key, for CI/headless), --device (device-code flow for machines without a browser), --oauth (force browser sign-in — the default when no key is given), --profile <name>.
  • logout flag: --profile <name>.
  • auth whoami, print the principal, auth method, workspace, environment, and scopes.
  • auth status, print whether you're authenticated and whether the API is reachable.
  • auth token, print the active credential; requires --reveal (refuses to print a secret otherwise).
  • auth refresh, renew the active browser sign-in's access token without signing in again. Flag: --profile <name>. (Browser sessions refresh automatically; this is the manual escape hatch.)

keys

Manage API keys.

pushrail keys list
pushrail keys create --name <name> [--scope <scope...>] [--env <env>]
pushrail keys revoke <id> --confirm
  • create flags: --name <name> (required), --scope <scope...> (ingest | manage | read, repeatable; defaults to ingest); --env <env>.
  • revoke requires --confirm (the operation is irreversible).

destinations

Inspect and manage delivery destinations.

pushrail destinations list [--type <type>] [--status <status>] [--customer <id>]
pushrail destinations get <id>
pushrail destinations create <type> [flags]
pushrail destinations enable <id>
pushrail destinations disable <id>
pushrail destinations delete <id> --confirm
pushrail destinations test <id>
  • list flags: --type <type>, --status <status>, --customer <id>.
  • create <type> flags: --name <name>, --customer <id>, --env <env>, --config <json>, --config-file <path>, --event-types <csv>, --secret <secret>, --dry-run. Webhook convenience: --url <url>, --method <method>. S3 convenience: --bucket <bucket>, --region <region>, --prefix <prefix>.
  • delete requires --confirm.
  • test runs a preflight check against the destination.

customers

Manage customer accounts (the routing groups your end-customers map to).

pushrail customers list
pushrail customers get <id>
pushrail customers create --external-id <id> --name <name> [--metadata <json>]
pushrail customers update <id> [--name <name>] [--metadata <json>]
pushrail customers delete <id> --confirm
  • create flags: --external-id <id> (required), --name <name> (required), --metadata <json>.
  • update flags: --name <name>, --metadata <json>.
  • delete requires --confirm.

events

Publish events to Pushrail.

pushrail events send <event-type> [flags]
pushrail events send-batch --payload-file <path> [--source <source>] [--customer <id>]
  • send flags: --source <source>, --customer <external-id>, --payload <json>, --payload-file <path>, --subject <subject>, --idempotency-key <key>, --timestamp <iso>, --metadata <json>, --dry-run. --source and --customer are required.
  • send-batch flags: --payload-file <path> (required; a JSON array or JSONL of event bodies), --source <source>, --customer <external-id>.

init

Scaffold a Pushrail integration in the current project (writes .env.example, example publish code, and pushrail.config.json).

pushrail init [flags]

Flags: --language <node|python|go>, --framework <framework>, --source <source>, --customer <external-id>, --event-types <csv>, --write-env, --write-example, --write-config, --dry-run, --non-interactive.

doctor

Diagnose your setup, credential, API reachability, scope, tenant, environment, SDK install, and project config.

pushrail doctor [--send-test] [--fail-on-warning]
  • --send-test, also send a test event to verify ingestion.
  • --fail-on-warning, exit non-zero on warnings, not just failures.

trigger

Send a test event (a convenience wrapper over events send that fills --source/--customer from your project config).

pushrail trigger <event-type> [flags]

Flags mirror events send: --source, --customer, --payload, --payload-file, --subject, --idempotency-key, --timestamp, --metadata, --dry-run.

listen

Stream live events for a customer and forward them to a local endpoint.

pushrail listen --customer <external-id> --forward-to <url> [flags]

Flags: --customer <external-id>, --forward-to <url>, --event-types <csv>, --ttl <seconds>, --redact-secrets (default), --no-redact-secrets.

dev

One-command dev loop: print a trigger hint, then listen and forward.

pushrail dev --customer <external-id> --forward-to <url> [flags]

Flags match listen: --customer, --forward-to, --event-types, --ttl, --redact-secrets, --no-redact-secrets.

mcp

Configure MCP clients to use the hosted Pushrail MCP server. See the MCP integration guide.

pushrail mcp install --client <claude|cursor|windsurf|codex>
pushrail mcp config
  • install flags: --client <client>, --url <url>.
  • config flag: --url <url>, prints the MCP client config snippet.

ci

CI-friendly checks and deploy gates.

pushrail ci check [--fail-on-warning]
pushrail ci smoke-test [flags]
  • check, the non-interactive doctor (config + auth + reachability). Flag: --fail-on-warning.
  • smoke-test, ingest a tagged event and assert it gets delivered. Flags: --source <source>, --customer <id>, --destination <id>, --event-type <type>, --payload-file <path>, --timeout <dur> (default 30s).

metrics

Delivery and throughput metrics.

pushrail metrics summary [--period <1h|24h|7d>]
pushrail metrics destinations [--period <7d|30d|90d>]
pushrail metrics events [--env <env>]
  • summary, events accepted, deliveries, DLQ count, fleet success rate and p95 latency. --period defaults to 24h.
  • destinations, per-destination success rate and p50/p95/p99 latency. --period defaults to 7d.
  • events, ingestion throughput for one environment. --env <env>.

logs

Delivery-centric activity stream.

pushrail logs [flags]

Flags: --destination <id>, --event <event-id>, --status <status>, --since <dur|ts>, --until <dur|ts>, --limit <n>, --follow (poll for new deliveries).

audit

Audit trail for config, secret, and replay changes.

pushrail audit list [flags]

Flags: --action <action>, --object-type <type>, --object-id <id>, --actor <actorId>, --since <dur|ts>, --until <dur|ts>, --limit <n>, --cursor <cursor>.

dlq

Inspect and requeue dead-lettered deliveries.

pushrail dlq list [flags]
pushrail dlq requeue <deliveryId>
  • list flags: --destination <id>, --event-type <type>, --error-category <cat>, --since <dur|ts>, --until <dur|ts>, --limit <n>, --cursor <cursor>.
  • requeue <deliveryId>, requeue a dead-lettered delivery as a fresh delivery.

portal

Embed portal sessions and hosted dashboard links.

pushrail portal sessions create --customer <id> [flags]
pushrail portal sessions open --customer <id> [flags]
pushrail portal links create --customer <id> [flags]
  • sessions create, mint an embed session token. Flags: --customer <id>, --permissions <csv>, --expires-in <dur> (default 1h).
  • sessions open, create a hosted portal link and open it in the browser. Flags: --customer <id>, --permissions <csv>, --redirect-to <path> (must start with /), --expires-in <dur>.
  • links create, create a hosted dashboard link. Flags: --customer <id>, --permissions <csv>, --redirect-to <path>, --expires-in <dur>.