CLI Reference

The SteadyStack CLI (pulse, also installed as ss and steadystack) brings

Monitoring as Code, live debugging, and CI/CD gates to the terminal. This page

mirrors pulse --help output as of v0.1.0.

For the conceptual overview and Docker probes, see CLI & Docker Probes;

for the YAML file format, see Monitoring as Code.

Installation

# Bun or npm — installs pulse, ss, and steadystack binaries
bun add -g @steadystack/cli
npm install -g @steadystack/cli

Requires Node.js ≥ 18.

Global behavior

steadystack [global options] <command> [subcommand] [args]

Global options:
  -V, --version          output the version number
  --locale <locale>      Output language: en, es, fr, de, pt-BR, ja, ko, zh-CN, ar
  -h, --help             display help

• --locale wins over the STEADYSTACK_LOCALE environment variable, which

wins over your system locale; anything unrecognized falls back to English.

• Every command that talks to the API requires authentication (see `auth

login`).

• Commands that check health exit 0 on success and 1 on failure — designed

for CI gates.

auth — manage authentication

pulse auth login --key <apiKey> [--url <baseUrl>]

Validate and store an API key. The key is verified against your workspace

before being persisted; a failed validation leaves no stored credentials.

# Key from Workspace Settings → API Keys (format pg_live_…)
pulse auth login --key pg_live_xxxxxxxxxxxxxxxx

# Self-hosted instance
pulse auth login --key pg_live_xxx --url https://steadystack.internal.example.com

Credentials are stored in a local config file managed by the CLI. Without

--key, the command prints where to generate a key and exits.

pulse auth status

Show whether you're logged in, the stored key prefix, and the base URL.

pulse auth logout

Clear stored credentials.

monitors — manage monitors

pulse monitors list (alias ls)

Table of all monitors: status (colored), name, type, URL (truncated), interval,

last check.

pulse monitors get <id>

Details for one monitor plus its recent check events (timestamp, status,

latency, error reason).

pulse monitors create

Interactive wizard: name, URL, type (all 19 monitor types offered), interval.

Creates the monitor immediately.

pulse monitors apply [-f <path>] [--dry-run]

Create or update monitors from a

steadystack.yaml file or a whole directory of

YAML files. Idempotent: monitors are matched by name — existing names

are updated, new names are created.

$ pulse monitors apply -f monitors/ --dry-run
DRY RUN — previewing changes without applying

  [+] CREATE checkout-api (HTTP: https://api.acme.com/health)
  [~] UPDATE marketing-site (HTTP: https://acme.com)

$ pulse monitors apply -f monitors/
✔ Applied: 1 created, 1 updated

pulse monitors diff [-f <path>]

Read-only comparison of local YAML against remote state. Prints [+] NEW,

[~] MODIFY (with per-field changes: url, type, interval), or `[=]

UNCHANGED` per monitor. Exits without changes to remote state — use it in CI to

detect drift:

pulse monitors diff -f monitors/ || echo "config drift detected"

pulse monitors import [-o <path>]

The reverse of apply: export all current monitors to YAML (default

steadystack.yaml) with a generated-timestamp header. Great seed for

adopting Monitoring as Code on an existing workspace.

pulse monitors delete <id>

Delete a monitor. Immediate, cascades to its events and alert rules.

trigger — force an immediate check

pulse trigger <id> [--url <url>] [--json]

Runs an instant check on an HTTP monitor and prints status, latency, HTTP

code, and any error reason. Exits 1 if the result is DOWN — usable as a

quick smoke test.

Only HTTP monitors support instant trigger; the API answers 422 otherwise.

logs — stream monitor events

pulse logs tail <id> [-n <lines>] [--interval <ms>]

tail -f for check events: prints the last N events, then polls for new ones.

Each line: timestamp, colored status dot, latency (right-aligned), region, and

error reason when present. Ctrl+C stops cleanly.

wait — CI/CD deployment gate

pulse wait <id> [--timeout <seconds>] [--interval <seconds>] [--json]

Blocks until the monitor is UP, then exits 0. On timeout (default 300 s,

max 600 s) it exits 1 with a link to the monitor — failing the CI job.

GitHub Actions example:

- name: Deploy
  run: ./deploy.sh

- name: Wait for production to be healthy
  run: pulse wait "$MONITOR_ID" --timeout 300
  env:
    MONITOR_ID: ${{ vars.PROD_HEALTH_MONITOR_ID }}

import — migrate from other platforms

pulse import kuma <file> [--dry-run] [--overwrite] [-t <tags>]

Imports monitors from an Uptime Kuma JSON backup. Type mapping is automatic

(http/keyword/json-query → HTTP, port/steam/mqtt → PORT, ping →

PING, dns → DNS, push → HEARTBEAT, postgres/mysql/redis/mongodb/

sqlserver → DATABASE, real-browser → BROWSER). Keyword and status-code

expectations carry over, maxretries maps to alertThreshold (minimum 30 s

interval enforced), and every imported monitor is tagged imported,

uptime-kuma plus anything from -t.

pulse import kuma kuma-backup.json --dry-run   # preview
pulse import kuma kuma-backup.json -t prod,eu  # apply

Environment variables

Exit codes