CLI & monitors as code

The sutramx command line tool lets you list and change monitors from your terminal, and keep your whole monitoring setup in a version-controlled sutramx.yml file. You describe monitors, status pages and alert channels in the file, review what would change with sutramx plan, then make it so with sutramx apply.

Install#

The CLI is the npm package @sutramx/cli. It needs Node.js 20 or newer.

npm install -g @sutramx/cli      # or run it without installing: npx @sutramx/cli <command>
sutramx login                    # paste an API key
sutramx monitors list

The source is at github.com/SutramX/cli.

Authenticate#

The CLI uses a workspace API key (it starts with sk_). Create one in Account settings → API keys → Create API key. A key acts on the one workspace it was created in. Whether you can create API keys, and how many, depends on your plan: see Plans & limits.

Every key has one of three access levels, chosen when you create it. The dashboard selects Read-only by default, and the level can't be changed later, so pick the level that the commands you run need:

login works with any level. regions, validate and init without --from-workspace don't need a key at all. plan and diff of a file that sets config.notification_emails also need the Automation level: with any other key the API refuses them with 403 ALERT_ROUTING_NOT_ALLOWED. See REST API for more about keys.

Log in interactively#

sutramx login

The key is read from a hidden prompt (or from stdin when you pipe it in), checked against the API, and saved to a credentials file with permissions 0600. You can also pass it directly with sutramx login --api-key sk_..., but that leaves the key in your shell history.

To remove the saved key:

sutramx logout

Environment variables#

Environment variables take priority over the saved file, which makes them the right choice for CI.

The default credentials file is ~/.config/sutramx/credentials.json. It holds JSON with api_key, and optionally api_url and workspace_id.

Commands#

Every command supports --help. The global flags are --api-url <url> (also SUTRAMX_API_URL), -V, --version and -h, --help.

"Key level" is the lowest access level the command works with; a higher level works too.

monitors also works as monitor, incidents as incident, status-pages as status-page, uptime as report, and list as ls (monitors ls, incidents ls, maintenance ls, status-pages ls). monitors delete also works as monitors rm, and incidents ack as incidents acknowledge. Wherever a command takes <id-or-key>, you can pass the monitor's UUID or its monitors-as-code key. Incident commands take the incident's UUID, which incidents list shows.

whoami#

Prints the workspace id, plan and billing market, the key's access level (read_only, standard or automation), the plan's limits (monitors, minimum interval, locations per monitor, status pages) and whether the key can manage integrations. Add --json for the raw response, which also has read_only: true for a read-only key.

monitors list#

The table shows ID, KEY, NAME, TYPE, STATUS, 24H uptime, EVERY (interval in seconds) and TARGET.

monitors create#

# A website check from two locations
sutramx monitors create --name "Homepage" --url https://example.com --region fra1 --region usa-az-probe --tag prod

# A TCP port check, idempotent thanks to --key
sutramx monitors create --key infra/postgres --name "Postgres" --type port \
  --config '{"host":"db.example.com","port":5432}'

Without --key, every run creates a new monitor. With --key, the first run creates it and later runs update it, so the command is safe to repeat in scripts. The settings available in --config depend on the monitor type; see Monitors overview and the page for each type.

monitors update#

Takes the same --name, --url, --interval, --tag, --region, --config and --json flags as create, and changes only what you pass. --tag and --region replace all tags or locations, and --config replaces the whole config, so start from sutramx monitors get <id-or-key>.

monitors checks and run-check#

sutramx monitors checks <id-or-key> lists checks, newest first. Flags: --limit <n> (1–500, default 50), --before <time> (ISO-8601, to page back), --region <code>, --status <status> and --json. sutramx monitors run-check <id-or-key> runs one real check now and records it.

monitors delete#

Asks you to type yes before deleting. In scripts, pass -y or --yes; without it, a non-interactive run refuses to delete. Deleting removes the monitor's check history.

monitors adopt#

sutramx monitors adopt 6f1c8f7e-6f2a-4a71-9d0b-0b8c1d2e3f40 web/home

Sets the key of a monitor that was created in the dashboard, so the sutramx.yml entry with that key manages it from now on instead of creating a duplicate.

incidents list#

The table shows ID, MONITOR, STATE (ongoing, acknowledged or resolved), STARTED, DURATION and the REGIONS that confirmed the outage. When there are more incidents, the last line tells you the --page to ask for next.

sutramx incidents list --status ongoing
sutramx incidents list --monitor api/health --from 2026-09-01

incidents get, ack and resolve#

sutramx incidents note <id> <text> adds an internal note to the timeline. With --public, it's published as a public update on your status pages; the CLI asks you to confirm unless you pass -y or --yes.

Acknowledging an ongoing incident marks that someone is on it and stops escalation to the next on-call step. Incidents resolve on their own when checks recover, so resolve by hand only when you know the issue is fixed. See Incidents.

sutramx incidents ack 0d7c2a9e-4b1f-4e8a-9c3d-6f2e1a0b9c8d
sutramx incidents resolve 0d7c2a9e-4b1f-4e8a-9c3d-6f2e1a0b9c8d --note "Rolled back the release"

why#

sutramx why <target> prints the Why this alert explanation in the terminal. The target is an incident id, or a monitor id, key, exact name or part of its name or URL.

The output starts with a one-line summary, then the verdict, whose fault it is (yours, external, checker or unknown), the failure class, the quorum rule and whether it was met, and a table of region votes. Regions whose checks were blocked by bot protection or were inconclusive on our side are marked "abstains": they don't count toward the quorum. Vendor signals and the 7- and 30-day flakiness score follow. A monitor with an open incident explains that incident; otherwise you get its current state and its most recent incident. Paused monitors and active maintenance windows are called out. When several monitors match, the CLI lists them and exits with status 1 instead of guessing.

sutramx why checkout-api
sutramx why 0d7c2a9e-4b1f-4e8a-9c3d-6f2e1a0b9c8d --json

maintenance list#

The table shows ID, TITLE, STATUS, STARTS, ENDS, REPEATS and SCOPE (all monitors, or the monitors or groups the window covers). The status is the window's live state, so a scheduled window whose start time has passed shows as ongoing. Alerts are silenced while a window is active. The CLI only lists windows: creating, changing and deleting them is done by the workspace owner in the dashboard, see Maintenance windows.

status-pages and uptime#

sutramx status-pages list and sutramx status-pages get <id-or-slug> show your status pages; manage them with sutramx.yml or the dashboard. sutramx uptime prints uptime, incidents, MTTR and health per monitor, plus SLO error budgets. Flags: --days 7|14|30|90 (default 30), --monitor <id-or-key> and --json.

init#

Without --from-workspace, init writes a commented starter file. With it, init exports every monitor with a key, except browser checks, which it skips with a warning. Monitors that had no key get one made from their name (for example "Checkout API" becomes checkout-api), and the file sets adopt_by_name: true so the first apply links them instead of creating copies. If several monitors share a name and type, init lists them: give each one a key with sutramx monitors adopt before you apply.

The export leaves out per-monitor alert recipients (config.notification_emails). Stored credentials, such as secret header values, are written as [REDACTED] because the API never reveals them; apply keeps the stored value as long as the URL's origin is unchanged. Replace [REDACTED] with a value, for example ${ENV_VAR}, to manage it from the file.

validate#

Checks the file's structure, environment variable references and duplicate keys without calling the API. Field rules such as intervals, config and plan limits are checked by plan.

plan, diff and apply#

These three share the same flags:

plan and diff also take --detailed-exitcode. apply also takes:

--allow-delete-all is a safety catch: when pruning is on and the file has no monitors at all (for example an empty or truncated file), apply refuses to start unless you pass it.

The sutramx.yml file#

By default the CLI reads sutramx.yml from the current directory; use -f for another path. The file is YAML, and because YAML accepts JSON, a JSON file works too.

version: 1

defaults:                 # merged into every monitor
  interval_seconds: 60
  tags: [prod]

settings:
  adopt_by_name: false    # true: first apply links existing monitors with the same name and type

monitors:
  - key: web/home
    name: Website
    url: https://www.example.com
    regions: [fra1, usa-az-probe]
    config:
      keyword: Example Domain

  - key: api/health
    name: Public API
    type: api
    url: https://api.example.com/v1/health
    interval_seconds: 30
    config:
      method: GET
      expected_status_codes: [200]
      headers:
        Accept: application/json

  - key: infra/postgres
    name: Postgres
    type: port
    config:
      host: db.example.com
      port: 5432

  - key: jobs/nightly-report
    name: Nightly report job
    type: cron
    config:
      cron_expression: "30 1 * * *"

status_pages:
  - slug: example-status
    title: Example status
    description: Live status of Example's website and API.
    is_public: true
    show_response_times: true
    monitors:
      - web/home
      - key: api/health
        section: API

integrations:             # needs an API key with the Automation access level
  - name: Ops alerts
    type: slack
    config:
      webhook_url: ${SLACK_WEBHOOK_URL}
    routing:
      scope: monitors
      monitors: [web/home, api/health]

The same idea as JSON:

{
  "version": 1,
  "monitors": [
    { "key": "homepage", "name": "Homepage", "url": "https://example.com" },
    { "key": "nightly-backup", "name": "Nightly backup", "type": "cron", "config": { "cron_expression": "0 2 * * *" } }
  ]
}

sutramx plan -f sutramx.json

Top-level fields#

Unknown fields anywhere in the file are an error, so typos don't go unnoticed.

defaults#

settings#

--adopt-by-name on the command line overrides adopt_by_name for a single run. Deleting is never turned on by the file.

monitors#

The config keys for each type are the same as in the dashboard and API. See HTTP & keyword, API & multi-step checks, Ping, TCP & UDP, DNS and Heartbeat & cron. Run sutramx regions for the location codes.

status_pages#

Fields you leave out are not changed. Custom domains, private access and subscribers are set up in the dashboard: see Status pages overview.

integrations#

The config fields for each channel are described in Slack, Teams & chat apps, Webhooks and PagerDuty & Opsgenie.

Environment variables in the file#

String values can read from the environment, so secrets stay out of your repository:

A file can never read the CLI's own credentials or CI tokens, such as SUTRAMX_API_KEY, SUTRAMX_CONFIG, GITHUB_TOKEN, GH_TOKEN, ACTIONS_*, INPUT_*, NPM_TOKEN or CI_JOB_TOKEN. When SUTRAMX_ALLOWED_ENV is set, for example SUTRAMX_ALLOWED_ENV=SLACK_WEBHOOK_URL,MYAPP_*, only the listed names and prefixes can be read. Set it in CI, where a pull request may have changed the file. A reference that isn't allowed fails with sutramx.yml references environment variables it may not read.

How plan and apply reconcile#

plan reads the file, asks the SutramX API what would change and prints it. Nothing is changed. Each line has a symbol:

Monitors
  + create  api/health "Public API" [api]
  ~ update  web/home "Website" [http]
      interval_seconds, regions

Plan: 1 to create, 1 to update, 0 to replace, 0 to delete.

apply builds the same plan, shows it, asks you to type yes, then makes the changes and prints one line per change (✓ applied, ✗ failed, · skipped).

Monitors#

• Monitors are matched by key. Monitors created in the dashboard have no key and are never changed or deleted by apply, unless you adopt them with sutramx monitors adopt or adopt_by_name.
• A field you leave out is not managed: an existing monitor keeps its current value, and a new monitor gets the same default as in the dashboard.
• config, when present, is managed as a whole: keys you remove from the file are removed from the monitor. The one exception is notification_emails (per-monitor alert recipients), which is kept unless the file sets it. Setting it needs a key with the Automation access level; with any other key, plan and apply fail with 403 ALERT_ROUTING_NOT_ALLOWED.
• Changing type shows as a replace: the old monitor is deleted, with its check history and incidents, and a new one is created. apply refuses a replace unless you pass --allow-replace (or --prune).
• Monitors are validated by the API with the same rules as the dashboard: plan limits, minimum interval, allowed locations and URL safety. plan warns when your plan's monitor allowance or minimum interval would make apply fail.

Status pages#

Status pages are matched by slug and are created or updated. apply never deletes a status page, because pages have public subscribers; delete a page in the dashboard. A page's monitor list can refer to monitors created in the same run.

Integrations#

Integrations are created or updated. Secrets are stored encrypted and only read back masked (for example …abcd), so the CLI compares the visible part: a secret counts as changed when its visible tail differs from your value. A secret changed in the dashboard to something with the same tail isn't detected.

Order and failures#

Apply runs in this order: monitors first, then integrations, then status pages. That way new monitors can be referenced by key in the same file.

By default, apply stops at the first failed change. Changes that already succeeded are kept, and later changes are skipped. Fix the problem and run apply again: only what is still different is changed. With --continue-on-error, apply keeps going and reports every failure at the end.

If the file changes integrations but the key doesn't have the Automation access level, plan shows an error line and apply refuses to start and changes nothing. A read-only key can still run plan and diff, but apply fails with 403 READ_ONLY_ACCESS and changes nothing.

Pruning#

Pruning deletes keyed monitors that exist in the workspace but are no longer in the file.

• Turn it on for a run with --prune. settings.prune: true in the file only prints a warning.
• It only touches monitors that have a key. That includes monitors created by the Terraform provider or by an AI tool through the MCP server with a key, so don't enable pruning if other tools manage keyed monitors in the same workspace.
• Deleting a monitor removes its check history.
• --prune-integrations deletes integrations that aren't in the file, but only of the types the file declares. A file that only lists Slack channels never removes a PagerDuty connection.
• If the file declares no monitors at all, apply refuses a prune that would delete every managed monitor unless you pass --allow-delete-all.

Always run sutramx plan before an apply that prunes and check the - lines.

Move an existing workspace to code#

1. Run sutramx init --from-workspace. It writes a key for every monitor and sets adopt_by_name: true.
2. Run sutramx plan. It should show no changes except the links to existing monitors, marked "(adopting existing monitor)".
3. Run sutramx apply.
4. Commit sutramx.yml. You can remove adopt_by_name once the monitors are linked.

Exit codes#

Without --detailed-exitcode, plan and diff exit 0 whether or not there are changes.

Use in CI#

In CI, pass the key with SUTRAMX_API_KEY from your CI secrets and use --auto-approve, because apply refuses to run without confirmation when there is no terminal. A job that only runs validate, plan or diff (for example on pull requests or to detect drift) can use a read-only key, unless the file sets config.notification_emails, which needs an Automation key even to plan; the job that runs apply needs a Standard key, or an Automation key when the file manages integrations or alert recipients.

export SUTRAMX_API_KEY="$SUTRAMX_API_KEY_SECRET"
sutramx validate
sutramx plan --detailed-exitcode   # exit 2 = there are changes to review
sutramx apply --auto-approve

For GitHub, the GitHub Action wraps these steps, posts the plan on pull requests and applies on merge.

For machine-readable output, add --json. plan --json returns the full plan (monitor changes, status page and integration changes, warnings, blockers and hasChanges); apply --json returns { ok, changed, steps }.

Troubleshooting#

Validation errors from the API name the monitor key and the field, for example monitor api/health: interval_seconds: ....

Common questions#

Will apply touch monitors I made in the dashboard? No. Only monitors with a key are managed. Adopt a dashboard monitor if you want the file to manage it.

Can I split the configuration over several files? Each run reads one file. If you use several files against one workspace, give them different keys and leave pruning off, or one file's apply will delete the other's monitors.

What happens if apply fails half-way? Completed changes stay. Run apply again after fixing the cause; it only changes what is still different.