Sitealarm CLI

The official command-line interface for Sitealarm.app. Manage monitors and heartbeats from your terminal, scripts, or CI — readable tables by default, compact JSON on request.

Installation

Requires Node.js 22.12 or newer.

npm install --global @sitealarm/cli

Verify the installation:

sitealarm --help
sitealarm version

Authentication

Create an API token in your Sitealarm account settings, then log in:

sitealarm auth login

Paste the token at the masked prompt (it never echoes back or lands in shell history). For scripts and CI, provide it through the environment instead:

export SITEALARM_API_TOKEN='your-api-token'
sitealarm monitors list

Tokens are resolved in this order: --token flag, then SITEALARM_API_TOKEN, then whatever auth login last stored in ~/.config/sitealarm/credentials.json (0600 permissions; %APPDATA%\sitealarm on Windows).

sitealarm auth status   # where the active token comes from
sitealarm auth whoami   # which account it belongs to
sitealarm auth logout   # remove the stored token

Quick start

sitealarm monitors list
sitealarm monitors get 3xK6JaeqVJqGR2BlVO
sitealarm monitors pause 3xK6JaeqVJqGR2BlVO
sitealarm monitors start 3xK6JaeqVJqGR2BlVO

sitealarm heartbeats list
sitealarm heartbeats create --name "Nightly backup"
sitealarm heartbeats create --name "Nightly backup" --period 1800 --grace 900
sitealarm heartbeats get 3xK6JaeqVJqGR2BlVO --reveal-secrets
sitealarm heartbeats delete 3xK6JaeqVJqGR2BlVO --confirm

A heartbeat's ping URL and token are redacted by default in both table and --json output — anyone holding the raw ping URL can report the heartbeat on your behalf. Pass --reveal-secrets when you actually need it, typically once, to wire up the job that pings it.

heartbeats create accepts either flags or a full JSON body:

sitealarm heartbeats create --body '{"name":"Nightly backup","period":3600,"grace":3600}'
sitealarm heartbeats create --body @heartbeat.json
cat heartbeat.json | sitealarm heartbeats create --body -

Output

Tables are the default everywhere — they stay the default even when output is piped, so a human reading logs later still gets something readable. Pass --json for a single compact line, suited for scripts and CI:

sitealarm monitors list --json

Destructive commands (heartbeats delete) prompt for confirmation in an interactive terminal; non-interactive shells must pass --confirm explicitly.

Exit codes identify the failure without parsing the message:

| Exit code | Meaning | |-----------|--------------------------------------------------------------| | 0 | Success | | 1 | Generic failure | | 2 | Invalid input, rejected locally or by the API (HTTP 400/422) | | 4 | Unauthenticated (HTTP 401) | | 5 | Forbidden (HTTP 403) | | 6 | Not found (HTTP 404) | | 7 | Rate limited (HTTP 429) | | 8 | Conflict with the current state (HTTP 409) |

Configuration

Persist defaults so you don't have to repeat flags every time — useful for pointing at a non-production API:

sitealarm config set api-url https://sitealarm.test/api/v2
sitealarm config set insecure true   # skip TLS verification; trusted local/dev hosts only
sitealarm config get api-url
sitealarm config list
sitealarm config unset api-url

Resolution order for both is the same as the token: flag, then environment variable (SITEALARM_API_URL, SITEALARM_INSECURE), then the stored config, then the default (https://sitealarm.app/api/v2).

Development

This project uses pnpm and oclif.

pnpm install
pnpm build
pnpm test
pnpm watch   # rebuilds on save; run `node bin/run.js <command>` in another terminal

Commands are hand-written under src/commands/, not generated from a spec. src/lib/ is organized by concern: resources/ (per-API-resource types and logic), store/ (local config/credential persistence), terminal/ (table rendering, colors, prompts), plus api-client.ts and base-command.ts at the top level.

License

MIT