Skip to content

feat(cli): add alerts command for scriptable alarm-state scans#281

Open
jongio wants to merge 1 commit into
mainfrom
idea/cli-alerts
Open

feat(cli): add alerts command for scriptable alarm-state scans#281
jongio wants to merge 1 commit into
mainfrom
idea/cli-alerts

Conversation

@jongio

@jongio jongio commented Jul 12, 2026

Copy link
Copy Markdown
Owner

What

Adds a one-shot thermoworks alerts command that scans the current alarm state across your devices and reports any channel that is actively alarming. Without a serial it checks every device on the account; pass a serial to scope to one device.

npx thermoworks alerts           # all devices
npx thermoworks alerts <serial>  # one device
npx thermoworks alerts --json    # machine-readable

# fire a notification when anything is alarming
npx thermoworks alerts || notify-send "ThermoWorks alarm"

Why

The CLI can arm and list alarms (alarm set / alarm list), but there was no scriptable way to ask "is anything alarming right now?" watch shows live alarm state on screen, but you cannot drop it in a cron job or shell loop. alerts fills that gap with a plain exit-code contract.

How

  • Reuses the SDK getChannelAlarmState helper to classify each channel as high, low, or none.
  • Scans with getDevices / getDevice plus getAllDeviceChannels. Read-only, so it never writes to a device.
  • Exits 1 when at least one channel is alarming and 0 when everything is clear. The exit code is set in both human and --json modes so scripts can branch on it.
  • Human output groups alarming channels under a bold device header; --json prints an array of { serial, deviceLabel, channel, channelLabel, state, value, units }.

Testing

  • Added packages/cli/tests/alerts.test.ts: high and low alarm detection with a non-zero exit code, the clear case at exit 0, single-device scoping via getDevice, JSON output shape, empty JSON array, and the not-logged-in error path.
  • pnpm --dir packages/cli typecheck clean.
  • pnpm --dir packages/cli test green (883 tests).
  • pnpm lint clean.

Docs

  • packages/cli/README.md: new thermoworks alerts section.
  • docs/cli-reference.md: new thermoworks alerts reference plus added to the --json supported-commands list.

Closes #276

Add a one-shot `alerts` command that scans the current alarm state across
devices and reports any channel that is actively alarming. Without a serial it
checks every device on the account; pass a serial to scope to one device.

The command is built for scripting: it exits with code 1 when at least one
channel is alarming and 0 when everything is clear, so a cron job or shell loop
can trigger a webhook, text, or desktop notification when a cook goes out of
range. The exit code is set in both human and --json modes.

Reuses the SDK getChannelAlarmState helper for state classification. Read-only:
it never writes to a device. Adds unit tests covering high and low alarm
detection, single-device scoping, JSON output, the clear case, and the
not-logged-in error path. Docs updated in the CLI README and cli-reference.

Closes #276

Co-authored-by: Copilot App <[email protected]>
@jongio jongio added cli CLI package enhancement New feature or request idea Feature idea from the idea pipeline labels Jul 12, 2026
@jongio jongio self-assigned this Jul 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli CLI package enhancement New feature or request idea Feature idea from the idea pipeline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLI: Add alerts command for a one-shot alarm-state scan

1 participant