Servosity Better Stack - Printing Press CLI
Prerequisites: Install the CLI
This skill drives the betterstack-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
- macOS / Linux:
bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/betterstack/install.sh) - Windows (PowerShell):
iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/betterstack/install.ps1 | iex - Verify:
betterstack-cli --version - Ensure
~/.local/bin(macOS / Linux) or%LOCALAPPDATA%\Programs\msp-skills(Windows) is on$PATH.
The installer downloads the betterstack-cli and betterstack-mcp binaries into ~/.local/bin
(macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not
register the skill with your agent and writes no MCP client config - see
mcp-install.md for that wire-up.
If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.
betterstack-cli mirrors your whole Better Stack Uptime account (monitors, heartbeats, incidents, on-call, escalation policies, status pages) into a local SQLite store, then answers operational questions no single API call can: coverage finds monitors that won't page anyone, mttr rolls up incident response times, flapping ranks your noisiest monitors, and fleet shows the whole account on one screen. Covers the official Terraform provider's resource surface (full create/update/delete on monitors and heartbeats; create/delete on groups, policies, and status pages), with agent-native output and typed exit codes throughout.
When to Use This CLI
Use this CLI when an agent or operator needs to query, audit, or provision a Better Stack Uptime account from the terminal - especially for cross-resource questions (which monitors are unprotected, how fast incidents resolve, which monitors flap, who is on call) that the one-resource-at-a-time API can't answer directly. Prefer it over raw API calls whenever the answer spans more than one resource type or needs to work offline.
Unique Capabilities
These capabilities aren't available in any other tool for this API.
Cross-resource analytics the API can't answer
fleet- One-screen health of the whole Better Stack account: monitors up/down/paused, heartbeats, open incidents, and who's on call now.Reach for this first when an agent needs the operational state of the entire account in one call instead of five.
betterstack-cli fleet --agentcoverage- Find monitors with no escalation policy or no alert channel - the ones that will go down silently and page no one.Use before an incident to prove every monitor actually escalates to a human.
betterstack-cli coverage --agentdown- Focused triage list of monitors currently down or degraded, joined to their open incidents and whether anyone is actually paged for each.Reach for this at the start of a shift or during an outage to see what is down and who is (or is not) being paged, in one call.
betterstack-cli down --agenttriage- Open incidents ranked by age and acknowledgement state - never-acknowledged first - joined to the affected monitor.Use this to prioritize incident response: it surfaces the open incidents nobody has acknowledged yet, oldest first.
betterstack-cli triage --agentstatuspage-audit- Flags status pages showing operational while a backing monitor has an open incident, and status-page resources pointing at missing or paused monitors.Use this before or during an incident to catch public status pages that are silently out of sync with reality.
betterstack-cli statuspage-audit --agentgroup-health- Per-group health rollup: monitor and heartbeat up/down counts plus open incidents for every monitor group and heartbeat group.For MSP-style accounts where one group is one client, this answers per-client health in a single call.
betterstack-cli group-health --agent
Incident intelligence
mttr- Mean time to acknowledge and resolve, computed across incidents over a window and broken down by monitor.Use for on-call retros and SLA reporting without exporting to a spreadsheet.
betterstack-cli mttr --days 30 --agentflapping- Rank monitors by how many incidents they generated in a window to surface the noisy, flapping, or misconfigured ones.Use to find alert fatigue sources before tuning thresholds.
betterstack-cli flapping --days 7 --top 10 --agent
On-call and resilience
oncall-gaps- Detect on-call calendars with nobody currently on call.Use to confirm someone is actually reachable on every rotation before relying on paging.
betterstack-cli oncall-gaps --agentheartbeat-risk- Rank heartbeats by risk: tight period+grace windows, paused-but-expected, and non-up status.Use to catch fragile cron/scheduled-task check-ins before they false-alarm or silently miss.
betterstack-cli heartbeat-risk --agent
Command Reference
heartbeat-groups - Heartbeat groups
betterstack-cli heartbeat-groups create- Create a heartbeat groupbetterstack-cli heartbeat-groups delete- Delete a heartbeat groupbetterstack-cli heartbeat-groups get- Get a heartbeat group by IDbetterstack-cli heartbeat-groups list- List heartbeat groups
heartbeats - Heartbeats - cron/scheduled-task check-ins
betterstack-cli heartbeats create- Create a heartbeatbetterstack-cli heartbeats delete- Delete a heartbeatbetterstack-cli heartbeats get- Get a heartbeat by IDbetterstack-cli heartbeats list- List heartbeatsbetterstack-cli heartbeats update- Update a heartbeat (sends PATCH)
incidents - Incidents - outages and alerts across monitors and heartbeats
betterstack-cli incidents acknowledge- Acknowledge an incidentbetterstack-cli incidents delete- Delete an incidentbetterstack-cli incidents get- Get an incident by IDbetterstack-cli incidents list- List incidentsbetterstack-cli incidents resolve- Resolve an incident
monitor-groups - Monitor groups
betterstack-cli monitor-groups create- Create a monitor groupbetterstack-cli monitor-groups delete- Delete a monitor groupbetterstack-cli monitor-groups get- Get a monitor group by IDbetterstack-cli monitor-groups list- List monitor groups
monitors - Uptime monitors (HTTP, keyword, ping, TCP, heartbeat-backed)
betterstack-cli monitors create- Create a monitorbetterstack-cli monitors delete- Delete a monitorbetterstack-cli monitors get- Get a monitor by IDbetterstack-cli monitors list- List all monitorsbetterstack-cli monitors update- Update a monitor (sends PATCH)
on-calls - On-call calendars and current on-call shifts
betterstack-cli on-calls get- Get an on-call calendar by ID (includes current on-call users)betterstack-cli on-calls list- List on-call calendars
policies - Escalation policies
betterstack-cli policies create- Create an escalation policybetterstack-cli policies delete- Delete an escalation policybetterstack-cli policies get- Get an escalation policy by IDbetterstack-cli policies list- List escalation policies
status-page-resources - Resources (monitored components) shown on a status page
betterstack-cli status-page-resources delete- Remove a resource from a status pagebetterstack-cli status-page-resources get- Get a status page resourcebetterstack-cli status-page-resources list- List resources on a status page
status-page-sections - Sections within a status page
betterstack-cli status-page-sections create- Create a status page sectionbetterstack-cli status-page-sections delete- Delete a status page sectionbetterstack-cli status-page-sections get- Get a status page sectionbetterstack-cli status-page-sections list- List sections of a status page
status-pages - Public status pages
betterstack-cli status-pages create- Create a status pagebetterstack-cli status-pages delete- Delete a status pagebetterstack-cli status-pages get- Get a status page by IDbetterstack-cli status-pages list- List status pages
Freshness Contract
This printed CLI owns bounded freshness only for registered store-backed read command paths. In --data-source auto mode, those paths check sync_state and may run a bounded refresh before reading local data. --data-source local never refreshes. --data-source live reads the API and does not mutate the local store. Set BETTERSTACK_NO_AUTO_REFRESH=1 to skip the freshness hook without changing source selection.
Covered paths:
betterstack-cli coveragebetterstack-cli downbetterstack-cli flappingbetterstack-cli fleetbetterstack-cli group-healthbetterstack-cli heartbeat-groupsbetterstack-cli heartbeat-groups getbetterstack-cli heartbeat-groups listbetterstack-cli heartbeat-riskbetterstack-cli heartbeatsbetterstack-cli heartbeats getbetterstack-cli heartbeats listbetterstack-cli incidentsbetterstack-cli incidents getbetterstack-cli incidents listbetterstack-cli monitor-groupsbetterstack-cli monitor-groups getbetterstack-cli monitor-groups listbetterstack-cli monitorsbetterstack-cli monitors getbetterstack-cli monitors listbetterstack-cli mttrbetterstack-cli on-callsbetterstack-cli on-calls getbetterstack-cli on-calls listbetterstack-cli oncall-gapsbetterstack-cli policiesbetterstack-cli policies getbetterstack-cli policies listbetterstack-cli status-pagesbetterstack-cli status-pages getbetterstack-cli status-pages listbetterstack-cli statuspage-auditbetterstack-cli triage
When JSON output uses the generated provenance envelope, freshness metadata appears at meta.freshness. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment.
Finding the right command
When you know what you want to do but not which command does it, ask the CLI directly:
betterstack-cli which "<capability in your own words>"
which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query.
Recipes
Find unprotected monitors
betterstack-cli coverage --agent
Lists monitors with no escalation policy or alert channel so you can fix paging gaps before an outage.
30-day incident response report
betterstack-cli mttr --days 30 --agent
Computes MTTA and MTTR across the window from the local mirror - no spreadsheet export needed.
Narrow a verbose monitor payload
betterstack-cli monitors list --per-page 250 --agent --select data.id,data.attributes.pronounceable_name,data.attributes.status
Uses --select dotted paths to pull only id, name, and status from the JSON:API envelope so agents don't burn context on full monitor objects.
Acknowledge an incident safely
betterstack-cli incidents acknowledge 12345 --by oncall@example.com --dry-run
Shows the exact request without sending; drop --dry-run to actually acknowledge.
Rank the noisiest monitors
betterstack-cli flapping --days 7 --top 10 --agent
Surfaces the monitors generating the most incidents so you can tune alert thresholds.
Auth Setup
Auth is a Better Stack Uptime API token (Authorization: Bearer). Create one under Better Stack → Settings → API tokens, then set BETTERSTACK_API_TOKEN. Run betterstack-cli doctor to confirm the token and reachability.
Agent Mode
Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.
Pipeable - JSON on stdout, errors on stderr
Filterable -
--selectkeeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:betterstack-cli heartbeat-groups list --agent --select id,name,statusPreviewable -
--dry-runshows the request without sendingOffline-friendly - sync/search commands can use the local SQLite store when available
Non-interactive - never prompts, every input is a flag
Explicit retries - use
--idempotentonly when an already-existing create should count as success, and--ignore-missingonly when a missing delete target should count as success
Response envelope
Commands that read from the local store or the API wrap output in a provenance envelope:
{
"meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
"results": <data>
}
Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.
Agent Feedback
When you (or the agent) notice something off about this CLI, record it:
betterstack-cli feedback "the --since flag is inclusive but docs say exclusive"
betterstack-cli feedback --stdin < notes.txt
betterstack-cli feedback list --json --limit 10
Entries are stored locally at ~/.local/share/betterstack-cli/feedback.jsonl. They are never POSTed unless BETTERSTACK_FEEDBACK_ENDPOINT is set AND either --send is passed or BETTERSTACK_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
Output Delivery
Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
| Sink | Effect |
|---|---|
stdout |
Default; write to stdout only |
file:<path> |
Atomically write output to <path> (tmp + rename) |
webhook:<url> |
POST the output body to the URL (application/json or application/x-ndjson when --compact) |
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
Named Profiles
A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
betterstack-cli profile save briefing --json
betterstack-cli --profile briefing heartbeat-groups list
betterstack-cli profile list --json
betterstack-cli profile show briefing
betterstack-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Usage error (wrong arguments) |
| 3 | Resource not found |
| 4 | Authentication required |
| 5 | API error (upstream issue) |
| 7 | Rate limited (wait and retry) |
| 10 | Config error |
Argument Parsing
Parse $ARGUMENTS:
- Empty,
help, or--help→ showbetterstack-cli --helpoutput - Starts with
install→ ends withmcp→ MCP installation; otherwise → see Prerequisites above - Anything else → Direct Use (execute as CLI command with
--agent)
MCP Server Installation
- Install the MCP binary (run the install script from the Prerequisites section, or see mcp-install.md for per-agent wire-up).
- Register with Claude Code:
claude mcp add betterstack-mcp -- betterstack-mcp - Verify:
claude mcp list
Direct Use
- Check if installed:
which betterstack-cliIf not found, offer to install (see Prerequisites at the top of this skill). - Match the user query to the best command from the Unique Capabilities and Command Reference above.
- Execute with the
--agentflag:betterstack-cli <command> [subcommand] [args] --agent - If ambiguous, drill into subcommand help:
betterstack-cli <command> --help.