Pushrail Docs
Open app
CLI

CLI configuration

Profiles, environment variables, and project config for the pushrail CLI.

CLI configuration

The pushrail CLI reads settings from three layers, named profiles on your machine, environment variables, and a repo-local project config, so you can keep multiple workspaces and environments straight without retyping flags.

Where things live

The CLI stores state under ~/.pushrail/:

  • profiles.json, named profiles, each holding a baseUrl, authMethod, optional tenant, and optional env. One profile is marked active.
  • credentials.json, API key tokens, keyed by profile name. Written with file mode 0600.

Override the config directory with the PUSHRAIL_CONFIG_DIR environment variable (useful for sandboxed CI or to isolate multiple identities).

Profiles

A profile bundles a base URL, environment, and stored credential under a name. Create one and switch to it:

pushrail profiles create staging --base-url https://api.pushrail.io --env staging
pushrail profiles use staging

To use a profile for a single command without changing the active one, pass --profile <name>. Profiles are the cleanest way to juggle multiple workspaces or environments from one machine.

pushrail logs --profile staging

Credential resolution order

When a command needs an API key, the CLI resolves it in this order, stopping at the first match:

  1. The --api-key flag.
  2. The PUSHRAIL_API_KEY environment variable.
  3. The active (or --profile-selected) profile's stored credential.

This means a flag always wins over the environment, and the environment always wins over a saved profile.

Environment variables

| Variable | Effect | |---|---| | PUSHRAIL_API_KEY | API key to authenticate with. | | PUSHRAIL_BASE_URL | API base URL. | | PUSHRAIL_ENV | Target environment (dev, staging, prod). | | PUSHRAIL_WORKSPACE_ID | Workspace (tenant) id. | | PUSHRAIL_PROFILE | Profile to use instead of the active one. | | PUSHRAIL_CONFIG_DIR | Override the ~/.pushrail config directory. |

Project config (pushrail.config.json)

pushrail init writes a repo-local pushrail.config.json. Commit it so everyone on the team shares the same defaults, source, default customer, event types, and detected SDK. Its values are merged underneath the environment and flags, so a flag or env var always overrides the file.

{
  "tenant": "ten_…",
  "defaultEnv": "development",
  "source": "checkout-service",
  "defaultCustomer": "cust_42",
  "eventTypes": ["order.completed", "order.refunded"],
  "sdk": { "language": "node", "framework": "nextjs" }
}

All fields are optional. eventTypes is an array of strings; sdk is an object with optional language and framework.

Output formats

Most commands print a human-readable table by default. Pass --output json (or its shorthand --json) or --output yaml for structured output:

pushrail destinations list --json

JSON output is intended for scripting and is stable for piping into tools like jq.