servosity/msp-skills/betterstack

Better Stack - Claude Code Skill

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:

1. macOS / Linux:

``bash bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/betterstack/install.sh) ``

1. Windows (PowerShell):

``powershell iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/betterstack/install.ps1 | iex ``

1. Verify: betterstack-cli --version
2. 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

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._

``bash betterstack-cli fleet --agent ``

• `coverage` - 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._

``bash betterstack-cli coverage --agent ``

• `down` - 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._

``bash betterstack-cli down --agent ``

• `triage` - 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._

``bash betterstack-cli triage --agent ``

• `statuspage-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._

``bash betterstack-cli statuspage-audit --agent ``

• `group-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._

``bash 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._

``bash betterstack-cli mttr --days 30 --agent ``

• `flapping` - 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._

``bash 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._

``bash betterstack-cli oncall-gaps --agent ``

• `heartbeat-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._

``bash betterstack-cli heartbeat-risk --agent ``

Command Reference

heartbeat-groups - Heartbeat groups

• betterstack-cli heartbeat-groups create - Create a heartbeat group
• betterstack-cli heartbeat-groups delete - Delete a heartbeat group
• betterstack-cli heartbeat-groups get - Get a heartbeat group by ID
• betterstack-cli heartbeat-groups list - List heartbeat groups

heartbeats - Heartbeats - cron/scheduled-task check-ins

• betterstack-cli heartbeats create - Create a heartbeat
• betterstack-cli heartbeats delete - Delete a heartbeat
• betterstack-cli heartbeats get - Get a heartbeat by ID
• betterstack-cli heartbeats list - List heartbeats
• betterstack-cli heartbeats update - Update a heartbeat (sends PATCH)

incidents - Incidents - outages and alerts across monitors and heartbeats

• betterstack-cli incidents acknowledge - Acknowledge an incident
• betterstack-cli incidents delete - Delete an incident
• betterstack-cli incidents get - Get an incident by ID
• betterstack-cli incidents list - List incidents
• betterstack-cli incidents resolve - Resolve an incident

monitor-groups - Monitor groups

• betterstack-cli monitor-groups create - Create a monitor group
• betterstack-cli monitor-groups delete - Delete a monitor group
• betterstack-cli monitor-groups get - Get a monitor group by ID
• betterstack-cli monitor-groups list - List monitor groups

monitors - Uptime monitors (HTTP, keyword, ping, TCP, heartbeat-backed)

• betterstack-cli monitors create - Create a monitor
• betterstack-cli monitors delete - Delete a monitor
• betterstack-cli monitors get - Get a monitor by ID
• betterstack-cli monitors list - List all monitors
• betterstack-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 policy
• betterstack-cli policies delete - Delete an escalation policy
• betterstack-cli policies get - Get an escalation policy by ID
• betterstack-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 page
• betterstack-cli status-page-resources get - Get a status page resource
• betterstack-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 section
• betterstack-cli status-page-sections delete - Delete a status page section
• betterstack-cli status-page-sections get - Get a status page section
• betterstack-cli status-page-sections list - List sections of a status page

status-pages - Public status pages

• betterstack-cli status-pages create - Create a status page
• betterstack-cli status-pages delete - Delete a status page
• betterstack-cli status-pages get - Get a status page by ID
• betterstack-cli status-pages list - List status pages

coverage

• betterstack-cli coverage - Find monitors with no escalation policy or no alert channel - the ones that will go down silently and page no one.

down

• betterstack-cli down - Focused triage list of monitors currently down or degraded, joined to their open incidents and whether anyone is actually paged for each.

flapping

• betterstack-cli flapping - Rank monitors by how many incidents they generated in a window to surface the noisy, flapping, or misconfigured ones.

fleet

• betterstack-cli fleet - One-screen health of the whole Better Stack account: monitors up/down/paused, heartbeats, open incidents, and who's on call now.

group-health

• betterstack-cli group-health - Per-group health rollup: monitor and heartbeat up/down counts plus open incidents for every monitor group and heartbeat group.

heartbeat-risk

• betterstack-cli heartbeat-risk - Rank heartbeats by risk: tight period+grace windows, paused-but-expected, and non-up status.

mttr

• betterstack-cli mttr - Mean time to acknowledge and resolve, computed across incidents over a window and broken down by monitor.

oncall-gaps

• betterstack-cli oncall-gaps - Detect on-call calendars with nobody currently on call.

statuspage-audit

• betterstack-cli statuspage-audit - Flags status pages showing operational while a backing monitor has an open incident, and status-page resources pointing at missing or paused monitors.

triage

• betterstack-cli triage - Open incidents ranked by age and acknowledgement state - never-acknowledged first - joined to the affected monitor.

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 coverage
• betterstack-cli down
• betterstack-cli flapping
• betterstack-cli fleet
• betterstack-cli group-health
• betterstack-cli heartbeat-groups
• betterstack-cli heartbeat-groups get
• betterstack-cli heartbeat-groups list
• betterstack-cli heartbeat-risk
• betterstack-cli heartbeats
• betterstack-cli heartbeats get
• betterstack-cli heartbeats list
• betterstack-cli incidents
• betterstack-cli incidents get
• betterstack-cli incidents list
• betterstack-cli monitor-groups
• betterstack-cli monitor-groups get
• betterstack-cli monitor-groups list
• betterstack-cli monitors
• betterstack-cli monitors get
• betterstack-cli monitors list
• betterstack-cli mttr
• betterstack-cli on-calls
• betterstack-cli on-calls get
• betterstack-cli on-calls list
• betterstack-cli oncall-gaps
• betterstack-cli policies
• betterstack-cli policies get
• betterstack-cli policies list
• betterstack-cli status-pages
• betterstack-cli status-pages get
• betterstack-cli status-pages list
• betterstack-cli statuspage-audit
• betterstack-cli triage