Commands - Alertee

Targeting an account or organization. To use a different saved account for one invocation without changing the active account, pass the global --account <email|prefix> flag before the subcommand — for example, alertee --account work@ checks list. Likewise, --org <id> overrides that account’s linked organization for one invocation. Both flags work with every command and do not change saved defaults. The backend still checks your access.

Authenticate through your browser.

alertee login

Opens your browser to authorize the CLI against your Alertee account (using PKCE), then saves credentials to ~/.config/alertee/config.json. Use --no-browser to print the URL instead of opening one (handy over SSH). See Authentication for the full flow and CI usage.

`alertee logout`

Log out of an account — the active one by default, or a named one.

alertee logout                  # log out of the active account
alertee logout [email protected]    # log out of a specific account

If other accounts remain, the CLI switches to one of them automatically.

`alertee whoami`

Show current authentication status.

alertee whoami

API URL:      https://prod-neon-alertee-gru2.encr.app
Account:      [email protected]
Token:        alrt_X7kQ2mNp…
Organization: Acme Corp

`alertee update`

Update the CLI to the latest published version (checks npm, then installs).

alertee update

Updating @alertee/cli v0.19.0 → v0.20.0…
Updated to v0.20.0.

`alertee auth`

Manage multiple accounts. alertee login and alertee logout are aliases for auth login / auth logout, so you only need this group when juggling more than one account. Each account keeps its own token and linked organization.

alertee auth login              # add another account (run login again)
alertee auth status             # list accounts; the active one is marked *
alertee auth switch             # switch account (prompts; toggles when there are two)
alertee auth switch work@       # switch by email or unique prefix
alertee auth logout work@       # remove one account, keep the rest

$ alertee auth status
* [email protected]
    Token: alrt_X7kQ2mNp…
    Organization: Acme Corp
  [email protected]
    Token: alrt_J2wRtJq8…
    Organization: Personal

* = active account. Switch with: alertee auth switch

Switching takes effect immediately for every CLI command and the local MCP server (it reads the active account on each tool call — no restart needed). To pin a shell session or an MCP server config to one account regardless of the active switch, set ALERTEE_ACCOUNT=<email>.

`alertee link`

Link to an organization. Required before running any check commands.

alertee link

Fetches your organizations and prompts you to select one. Run again to switch organizations.

`alertee plan`

Show the linked org’s plan, price, next invoice, estimated current-period spend, and usage. Handy before creating checks to confirm there’s headroom.

alertee plan
alertee plan --format json

JSON reports monetary values in integer cents (monthly_price_cents and estimated_spend_cents) with currency, plus next_invoice_at and billing_period_end timestamps.

Plan:          Starter (active)
Price:         $29 / month
Next invoice:  est. $29 on 30 Sep 2026
Est. spend:    $29 this billing period
Checks:        8 / 25
Data sources:  2 / 5
Min interval:  5 min

`alertee org create [name]`

Create a new organization and link to it (so the next connections create / checks create target it). You become the organization’s owner.

alertee org create "Acme"
alertee org create "Acme" --slug acme
alertee org create            # prompts for the name

Flags: --slug <slug> (custom URL-safe slug; auto-generated from the name if omitted), --no-link (create without switching your linked organization).

`alertee org list`

List the organizations you belong to. The linked one is marked with *.

alertee org list
alertee org list --format json

`alertee checks list`

List all checks in the linked organization.

alertee checks list
alertee checks list --compact

NAME                STATUS    TYPE         INTERVAL  ID                                    QUIET
───────────────────────────────────────────────────────────────────────────────────────────────
Orders last 5 min   success   sql          5 min     6f1a…                                 —
Failed payments     failure   sql          15 min    a2c4…                                 —
Replication lag     success   api_metric   1 min     b9e7…                                 yes — Manually snoozed

The QUIET column shows whether each check’s alerts are currently suppressed and why — a snooze, a calendar holiday, or off-hours. --compact trims the table to name, status, and active/paused/muted state. Add --format json for machine-readable output. Its fields use plain values (enabled: true, not Enabled.Bool), and request credentials are always redacted. Add --compact to omit configuration, descriptions, and runbook text:

alertee checks list --format json
alertee checks list --format json --compact

`alertee checks get <id>`

Show a single check’s detail (status, interval, type, connection, query). JSON uses the same flattened fields as checks list; request credentials are redacted in both table and JSON output.

alertee checks get <id>
alertee checks get <id> --format json

`alertee checks pause [checks...]`

Pause one or more checks so they stop running. Names and IDs can be mixed, and --all pauses the entire organization in one batch. Pausing does not change a check’s alert mute setting.

alertee checks pause "Orders freshness" "Archive completed"
alertee checks pause --all
alertee checks pause --all --format json

Use the matching resume command to start them again:

alertee checks resume "Orders freshness"
alertee checks resume --all

`alertee checks history <id>`

Show a check’s recent run history. Defaults to the last 24 hours.

alertee checks history <id>
alertee checks history <id> --hours 168     # last 7 days
alertee checks history <id> --format json

CHECKED AT             STATUS
─────────────────────────────
01/06/2026, 22:45:08   success
01/06/2026, 22:30:03   success

`alertee checks changelog <id>`

Show a check’s change history — config edits, Alertee AI reviews, and schedule/calendar/snooze changes, newest first. This is the what-changed log (distinct from checks history, which is run/status over time).

alertee checks changelog <id>
alertee checks changelog <id> --limit 100
alertee checks changelog <id> --format json

20/06/2026, 12:14:02  [schedule]  Set calendar: NYSE calendar
  by user

20/06/2026, 12:14:02  [edit]  Updated interval, cron schedule
  by Niall Brickell
  Interval: custom → fifteen_minutes
  Cron schedule: */15 14-20 * * 1-5 → (empty)

`alertee checks run <id>`

Run a check immediately and print the result — handy for testing without waiting for the schedule.

alertee checks run <id>
alertee checks run <id> --format json

The first line is a plain-English verdict that spells out the polarity, so there’s no guessing which way round the comparison fires:

ALERTING — Value 0.00 is not greater than 0.00. Healthy when value > 0; the check alerts when that's violated.

The comparison you configure describes the healthy state and the check alerts on violation — see Conditions.

`alertee checks preview-api`

Probe a JSON API and list its extractable gjson paths, for authoring an api_metric check without curling first. Saves nothing.

alertee checks preview-api \
  --url "https://api.tinybird.co/v0/sql" \
  --query-param "q=SELECT count() AS value FROM events" \
  --header "Authorization: Bearer $TINYBIRD_TOKEN"

HTTP 200 in 142ms

Extractable paths (use one as --value-path):
  data.0.value  =  1234
  rows          =  1

Flags: --url, --http-method, --header "Key: Value" (repeatable), --query-param "key=value" (repeatable, auto-encoded), --request-body, --value-path (to confirm what a specific path extracts). See API metric checks.

`alertee checks open <id>`

Open a check’s page in your browser.

alertee checks open <id>

`alertee connections list`

List the database connections in the linked organization (use the ID when creating checks).

alertee connections list
alertee connections list --format json

`alertee connections create`

Create a database connection in the linked organization. Pass flags, or omit them to be prompted (the URI is hidden-prompted). The connection URI is sent to the API over HTTPS and encrypted server-side — the CLI never stores it. The backend tests the connection before saving, so a bad URI or unreachable host fails here rather than saving a broken connection.

alertee connections create --name "Acme prod" --type postgres \
  --uri "postgres://user:pass@host:5432/acme"
alertee connections create     # prompts for name, type, and URI (hidden)

Flags: --name, --type postgres|clickhouse, --uri <connection-string>.

`alertee connections update <connection>`

Update an existing connection — rotate its credentials (--uri) or rename it. Re-tested before saving. The URI is encrypted server-side and never stored by the CLI.

# Rotate the password / connection string
alertee connections update "Acme prod" --uri "postgres://user:newpass@host:5432/acme"
alertee connections update "Acme prod"     # prompts for the new URI (hidden)

Flags: --uri <connection-string> (new URI), --name (rename), --type postgres|clickhouse.

`alertee connections test <connection>`

Test an existing connection by name or ID. Reports detected permissions.

alertee connections test "Acme prod"
alertee connections test <id>

`alertee connections delete <connection>`

Delete a connection by name or ID. Prompts for confirmation first.

alertee connections delete "Acme prod"
alertee connections delete <id> --yes      # skip the confirmation

`alertee checks create`

Create a new check — a SQL check (single-value or grid), a website/API check, an API metric check, a heartbeat, or a push check. Pass flags for non-interactive use (CI, or an AI assistant driving the CLI), or omit them to be prompted for each field at a terminal. The condition describes the healthy state and the check alerts when it’s violated — see Conditions.

# SQL single-value: healthy while at least one order arrives in the last 5 minutes
alertee checks create --name "Orders (5 min)" --connection "Acme prod" \
  --query "SELECT COUNT(*) FROM orders WHERE created_at > now() - interval '5 minutes'" \
  --condition greater_than --threshold 0 --interval five_minutes

# SQL freshness: alert if the newest event is more than 15 minutes old
alertee checks create --name "Events fresh" --connection "Acme prod" \
  --query "SELECT MAX(created_at) FROM events" \
  --condition timestamp_age --threshold 15 --interval five_minutes

# Grid: alert if any store has fewer than 5 orders
alertee checks create --name "Orders per store" --connection "Acme prod" \
  --query "SELECT store_id AS name, COUNT(*) AS value FROM orders GROUP BY store_id" \
  --grid --evaluation-type all_cells --condition greater_or_equal --threshold 5 \
  --interval fifteen_minutes

# Website/API: alert if the site stops returning 200 or gets slow
alertee checks create --type http --name "Marketing site" \
  --url https://example.com --expected-status 200 --max-response-time 2000 \
  --interval five_minutes

# API metric: track a number from a JSON API and alert on a threshold
alertee checks create --type api_metric --name "Daily signups" \
  --url https://api.example.com/stats --value-path signups.today \
  --header "Authorization: Bearer $TOKEN" \
  --condition greater_or_equal --threshold 10 --interval hourly

# Heartbeat: a once-a-day cron job (prints the ping URL to curl on success)
alertee checks create --type heartbeat --name "Nightly ETL" \
  --expected-interval 1440 --interval hourly

# Push: your own cron POSTs the number (prints the ingest URL); no credentials
alertee checks create --type push --name "Nightly load rows" \
  --staleness-mins 30 --condition greater_or_equal --threshold 100 \
  --interval fifteen_minutes

# Interactive — prompts for anything you don't pass
alertee checks create

Flags: --name, --type <sql|http|api_metric|heartbeat|push>, --interval, --alert-level, --alert-message <text> (custom alert/incident text replacing the auto-generated message — supports {check_name}, {value}, {threshold}; see custom alert messages), --alert-group <name|id> (route alerts to a specific group), --calendar <name> (follow a calendar — NYSE, LSE, TSX, XETRA, EURONEXT, UK — quiet on its holidays/weekends), --description <text> (short note on what the check covers/why — also fed to Alertee’s AI incident advisory as domain context), --documentation <text> (longer-form runbook/notes), --justification <text> (why the check exists), --mute (create muted — runs but sends no alerts), --grace <count> / --grace-type / --grace-window (tolerate failures before alerting — see grace periods), --exclude-query / --include-rows / --max-rows <n> (control what webhook alerts send — the SQL query is included by default, raw rows are not).

SQL (--type sql, default): --connection <name|id>, --query; single-value/per-cell --condition (greater_than, less_than, greater_or_equal, less_or_equal, equals, not_equals, between, not_between, contains, regex, timestamp_age, is_null, is_not_null, exists) with its value flag --threshold, --match-value, or --min/--max; escalation levels with repeatable --extra-threshold "comparison:value:level" (e.g. --extra-threshold "less_than:100000:critical" — worst violated level wins); grid --grid, --evaluation-type, --severity, --label-query. The check is single-value unless --grid or --evaluation-type is given.
Website/API (--type http): --url, --http-method, --expected-status, --timeout, --max-response-time, --body-contains, --ssl-expiry-days.
API metric (--type api_metric): --url, --value-path (gjson path to the metric in the JSON response), --header "Key: Value" (repeatable — auth tokens), --query-param "key=value" (repeatable, auto-encoded — e.g. --query-param "q=SELECT count() AS value FROM events" for Tinybird/HTTP-SQL), --http-method, --request-body, --expected-status, --timeout; plus the same condition flags as SQL (--condition + --threshold, or --grid / --evaluation-type when the path yields {name,value} rows). See API metric checks. Use alertee checks preview-api (below) to discover value paths before saving.
Heartbeat (--type heartbeat): --expected-interval (minutes), --heartbeat-grace, --last-ping-status.
Push (--type push): --staleness-mins (the dead-man window — alert if nothing is pushed within this many minutes, default 60), plus the same condition flags as SQL (--condition + --threshold, or --grid / --evaluation-type for a grid push). Creating one prints the ingest URL your job POSTs to — see push checks and alertee push below.

`alertee checks update <check>`

Update a check’s common fields by name or ID. This is a partial update — only the flags you pass change. With no flags at a terminal it drops into an interactive editor for the same fields.

alertee checks update "Orders last 5 min" --name "Orders (5 min)"
alertee checks update <id> --query "SELECT COUNT(*) FROM orders WHERE …"
alertee checks update <id> --interval fifteen_minutes --alert-level critical
alertee checks update <id> --threshold 850000           # change the comparison value
alertee checks update <id> --condition less_than --threshold 100   # change operator + value
alertee checks update <id> --extra-threshold "less_than:1000:critical"  # replace escalation tiers
alertee checks update <id> --alert-message "{check_name} stale: {value} rows, want {threshold}"
alertee checks update <id> --pause      # disable (stops running entirely)
alertee checks update <id> --resume     # enable
alertee checks update <id> --mute       # keep running, but send no alerts
alertee checks update <id> --unmute     # re-enable alerts
alertee checks update <id> --grace 3    # tolerate 3 consecutive failures first
alertee checks update <id> --grace 0    # turn grace off
alertee checks update <id>              # interactive: pick fields to edit
alertee checks update <id> --managed-by alertee   # let Alertee maintain it
alertee checks update <id> --calendar NYSE        # quiet on its holidays/weekends
alertee checks update <id> --clear-calendar       # stop following a calendar
alertee checks update <id> --include-rows         # send failing rows to webhooks
alertee checks update <id> --exclude-query        # stop sending the SQL query
alertee checks update <id> --staleness-mins 15    # push: retune the dead-man window

Flags: --name, --query, --staleness-mins (push checks: retune the dead-man window — the existing ingest URL keeps working), --label-query, --interval, --alert-level, --alert-message, --description, --documentation, --justification (set the author notes — --description is also fed to Alertee’s AI incident advisory; pass "" to clear any of them), --condition, --threshold, --match-value, --min, --max, --evaluation-type, --severity, --extra-threshold, --pause, --resume, --mute, --unmute, --grace <count>, --grace-type, --grace-window, --managed-by, --calendar, --clear-calendar, --tz, --include-query / --exclude-query, --include-rows / --exclude-rows, --max-rows <n> (control what webhook alerts send).

The condition flags (--condition, --threshold, --match-value, --min/--max, --evaluation-type, --severity, --extra-threshold) edit the check’s condition in place — they’re the same flags as checks create and only the ones you pass change; the rest of the condition (including escalation tiers) is preserved. See conditions.
--mute silences a check’s notifications without stopping it — it keeps running and updating its status, just doesn’t alert. Stays muted until --unmute. Good for a noisy, not-yet-tuned check. (Contrast with --pause, which stops the check running, and snooze, which skips runs for a short window.)
--grace <count> tolerates that many failures before alerting (for spiky metrics); --grace-type within_window + --grace-window <minutes> counts failures in a rolling window instead of consecutively. --grace 0 turns it off. See grace periods.
--managed-by user|alertee switches who maintains the check. alertee hands it to Alertee, which re-authors and re-reviews it on a cadence.
--calendar makes the check follow a calendar (NYSE = US market holidays, UK = UK bank holidays, plus LSE, TSX, XETRA, EURONEXT) so it stays quiet on that calendar’s closed days — weekends and its holidays. It’s day-level only: time-of-day stays with the check’s schedule, and the two compose.

Editing the condition itself (especially grid conditions) is done in the web UI or via the MCP update_check tool.

`alertee push <token> [values...]`

Push a number to a push check’s ingest URL. This is the one command that needs no login — the token in the URL is the credential, which is what lets a cron inside a private network use it.

# Single value
alertee push <token> 42

# Grid: one name=value pair per dimension
alertee push <token> eu-west=12 us-east=9

# The full ingest URL works in place of the bare token
alertee push https://api.alertee.app/ingest/<token> 42

Pushed value 42.
Verdict: healthy — the condition is satisfied
Check: 8f1c…

Each push is evaluated against the check’s condition immediately, so the printed verdict (healthy, alerting, or error) is the real result — not a queued acknowledgement. Flags: --metadata <json> (optional JSON attached to the pushed batch).

`alertee checks delete <check>`

Delete a check by name or ID. Prompts for confirmation first.

alertee checks delete "Orders last 5 min"
alertee checks delete <id> --yes      # skip the confirmation

`alertee checks snooze <check>`

Silence a check for the rest of today (it’s skipped until then). Auto-expires, or end it early with checks unsnooze. See Active schedule & snooze.

alertee checks snooze "Orders (5 min)"
alertee checks snooze <id> --until 2026-06-03T09:00:00Z --reason "deploy in progress"

Flags: --until <iso-ts> (silence until a timestamp instead of end of day), --tz <zone> (local day boundary, default America/New_York), --reason.

`alertee checks unsnooze <check>`

End a check’s active snooze now, so its alerts resume immediately instead of waiting for the snooze to expire. No-op if the check isn’t snoozed; leaves recurring quiet windows and calendars untouched.

alertee checks unsnooze "Replication lag"

Past snoozes show up under alertee checks history <id> (a SNOOZES section).

`alertee checks schedule <check>`

Set a check’s custom schedule — the recurring hours/days it’s expected to be active. Outside it the check is skipped, so it won’t alert. This handles time-of-day; to also stay quiet on a calendar’s holidays (and weekends), add --calendar — the two compose. See Active schedule & snooze.

alertee checks schedule "Trade volume" --before 09:30 --after 16:00 --weekdays --tz America/New_York
alertee checks schedule "Trade volume" --clear      # remove the schedule

Flags: --before <hh:mm>, --after <hh:mm>, --weekdays (quiet all weekend), --tz <zone>, --reason, --clear.

`alertee checks suggest-schedule <check>`

Infer an active schedule from the check’s run history — Alertee looks at when the check normally has data and proposes hours/days. A suggestion only; pass --apply to set it as the check’s custom schedule. See Active schedule & snooze.

alertee checks suggest-schedule "Trade volume"            # show the suggestion
alertee checks suggest-schedule "Trade volume" --apply    # and apply it

Flags: --days <n> (history window, default 30), --tz <zone>, --apply.

`alertee alert-groups`

Manage alert groups and their recipients. An alert group is a named set of recipients; a check routes its alerts to one group (the org default if none is set). See Alert groups for the model.

alertee alert-groups list                       # default group marked *
alertee alert-groups create "Acme oncall"
alertee alert-groups update "Acme oncall" --name "Acme on-call" --default
alertee alert-groups delete "Acme oncall"    # --yes to skip confirmation
alertee alert-groups test "Acme oncall"      # send a test alert

Recipients (channels) within a group:

# List recipients (shows each channel's ID for removal)
alertee alert-groups recipients "Acme oncall"

# Add a webhook (optionally with headers)
alertee alert-groups add-webhook "Acme oncall" \
  --url https://hooks.example.com/abc --header "Authorization: Bearer xyz"

# Add an email group (recipient list — see email-groups below)
alertee alert-groups add-email-group "Acme oncall" --email-group "Acme emails"

# Remove a recipient by its channel ID (from `recipients`)
alertee alert-groups remove-recipient <channel-id> --yes

Slack recipients are configured in the web UI (they need a connected Slack workspace).

`alertee email-groups`

Manage email groups — reusable lists of email recipients (external addresses or organization members). Attach one to an alert group with alert-groups add-email-group.

alertee email-groups list
alertee email-groups create "Acme emails" --email [email protected] --email [email protected]
alertee email-groups update "Acme emails" --name "On-call emails"   # rename / --description / --auto-add
alertee email-groups members "Acme emails"
alertee email-groups add "Acme emails" [email protected] [email protected]
alertee email-groups remove "Acme emails" [email protected]
alertee email-groups delete "Acme emails"    # --yes to skip confirmation

`alertee inbox`

View and triage inbox items (incidents). See Inbox.

alertee inbox list                              # all items
alertee inbox list --status open --severity critical --limit 20
alertee inbox list --check <check-id> --status resolved   # a check's past incidents
alertee inbox list --format json
alertee inbox get <id>                          # detail + timeline + comments
alertee inbox comment <id> "Root cause: ETL cron was paused; resumed it"
alertee inbox comment <id> "internal note" --no-notify   # skip the email fan-out
alertee inbox edit-comment <id> <comment-id> "Corrected: cron was paused, not failing"
alertee inbox delete-comment <id> <comment-id>
alertee inbox ack <id> --note "looking into it"
alertee inbox resolve <id> --outcome resolved_fix        # resolved_fix | resolved_transient | ignored | suppressed | expected | duplicate | check_changed
alertee inbox digest                            # briefing + counts

`alertee receivers`

Manage inbound webhook receivers — external tools POST to a receiver’s URL to open an inbox incident. create prints the URL; copy it into the other tool.

alertee receivers list
alertee receivers create --name "Cron jobs" --severity warning \
  --alert-group "Acme oncall" --auto-resolve
alertee receivers delete "Cron jobs"            # --yes to skip confirmation

Flags for create: --name, --severity info|warning|error|critical, --title-template, --description-template, --alert-group <name|id...>, --auto-resolve. POST a JSON body like {"title":"…","severity":"critical","dedup_key":"…"} to the printed URL.

`alertee mcp`

Start the MCP server for use with agents like Claude Code, or any MCP-compatible AI tool.

alertee mcp

This is normally invoked automatically via your .mcp.json config — you don’t need to run it directly. See MCP setup for details.

​alertee login

​alertee logout

​alertee whoami

​alertee update

​alertee auth

​alertee link

​alertee plan

​alertee org create [name]

​alertee org list

​alertee checks list

​alertee checks get <id>

​alertee checks pause [checks...]

​alertee checks history <id>

​alertee checks changelog <id>

​alertee checks run <id>

​alertee checks preview-api

​alertee checks open <id>

​alertee connections list

​alertee connections create

​alertee connections update <connection>

​alertee connections test <connection>

​alertee connections delete <connection>

​alertee checks create

​alertee checks update <check>

​alertee push <token> [values...]

​alertee checks delete <check>

​alertee checks snooze <check>

​alertee checks unsnooze <check>

​alertee checks schedule <check>

​alertee checks suggest-schedule <check>

​alertee alert-groups

​alertee email-groups

​alertee inbox

​alertee receivers

​alertee mcp

`alertee login`

`alertee logout`

`alertee whoami`

`alertee update`

`alertee auth`

`alertee link`

`alertee plan`

`alertee org create [name]`

`alertee org list`

`alertee checks list`

`alertee checks get <id>`

`alertee checks pause [checks...]`

`alertee checks history <id>`

`alertee checks changelog <id>`

`alertee checks run <id>`

`alertee checks preview-api`

`alertee checks open <id>`

`alertee connections list`

`alertee connections create`

`alertee connections update <connection>`

`alertee connections test <connection>`

`alertee connections delete <connection>`

`alertee checks create`

`alertee checks update <check>`

`alertee push <token> [values...]`

`alertee checks delete <check>`

`alertee checks snooze <check>`

`alertee checks unsnooze <check>`

`alertee checks schedule <check>`

`alertee checks suggest-schedule <check>`

`alertee alert-groups`

`alertee email-groups`

`alertee inbox`

`alertee receivers`

`alertee mcp`