kuma-cli

CLI for managing Uptime Kuma via its native Socket.IO API. No more clicking through the web panel — manage monitors, status pages, and heartbeats from your terminal.

Install

npm install -g @blackasteroid/kuma-cli

Or use without installing:

npx @blackasteroid/kuma-cli login https://kuma.example.com

Quick start

# 1. Authenticate
kuma login https://kuma.example.com

# 2. List monitors
kuma monitors list

# 3. Create a monitor
kuma monitors create --name "My API" --type http --url https://api.example.com

Commands

Auth

Command	Description
kuma login <url>	Authenticate with Uptime Kuma and save session
kuma logout	Clear saved session credentials
kuma status	Show current connection config

Monitors

Command	Description
kuma monitors list	List all monitors with status + uptime
kuma monitors list --json	Output raw JSON (for scripting)
kuma monitors list --status down --json	Filter by status
kuma monitors list --tag <tag> --json	Filter by tag
kuma monitors add	Add a monitor interactively
kuma monitors add --name <n> --type http --url <url>	Add non-interactively
kuma monitors create --type http --name <n> --url <url>	Create monitor non-interactively (pipeline-safe)
kuma monitors create --type push --name <n> --json	Create push monitor, returns pushToken
kuma monitors update <id>	Update name/url/interval of a monitor
kuma monitors delete <id>	Delete a monitor (with confirmation)
kuma monitors delete <id> --force	Delete without confirmation prompt
kuma monitors pause <id>	Pause a monitor
kuma monitors resume <id>	Resume a paused monitor
kuma monitors bulk-pause --tag <tag>	Pause all monitors matching tag
kuma monitors bulk-pause --tag <tag> --dry-run	Preview without touching anything
kuma monitors bulk-resume --tag <tag>	Resume all monitors matching tag
kuma monitors set-notification <id> --notification-id <id>	Assign notification to monitor

Heartbeats

Command	Description
kuma heartbeat view <monitor-id>	View last 20 heartbeats
kuma heartbeat view <monitor-id> --limit 50	Show last N heartbeats
kuma heartbeat view <monitor-id> --json	Output raw JSON
kuma heartbeat send <push-token>	Send push heartbeat (no auth needed)
kuma heartbeat send <push-token> --status down --msg "text"	Send with status/message

Notifications

Command	Description
kuma notifications list	List all notification channels
kuma notifications create --type discord --name <n> --url <webhook>	Create Discord notification channel

Status pages

Command	Description
kuma status-pages list	List all status pages
kuma status-pages list --json	Output raw JSON

Config Export/Import

Command	Description
kuma config export --output <file>	Export monitors and notifications to a JSON/YAML file
kuma config import <file>	Import monitors and notifications from a file

For detailed usage, check Config Export & Import.

Using with AI agents

kuma-cli works well in agent and automation contexts. Every command supports --json output and exits non-zero on errors, so you can parse results reliably and short-circuit on failure.

For more details, see Agent Mode (JSON).

Set KUMA_JSON=1 to force JSON output on all commands — useful when you don't control the call site.

Check what's down:

kuma monitors list --status down --json

Pause/resume around a deploy:

kuma monitors bulk-pause --tag Production --dry-run   # preview first
kuma monitors bulk-pause --tag Production
./deploy.sh
kuma monitors bulk-resume --tag Production

Create a monitor and wire up a notification in one shot:

MONITOR_ID=$(kuma monitors create --type http --name "my-service" \
  --url https://my-service.com --tag Production --json | jq -r '.data.id')
kuma monitors set-notification $MONITOR_ID --notification-id 1

Push monitor for a GitHub Actions runner:

# Create the monitor, capture the token
TOKEN=$(kuma monitors create --type push --name "runner-aang" --json | jq -r '.data.pushToken')

# In the workflow:
- name: Heartbeat
  run: kuma heartbeat send ${{ secrets.RUNNER_PUSH_TOKEN }}

Connect a notification channel to all production monitors:

NOTIF_ID=$(kuma notifications create --type discord --name "alerts" \
  --url $WEBHOOK --json | jq -r '.data.id')
kuma monitors list --tag Production --json | jq -r '.[].id' | \
  xargs -I{} kuma monitors set-notification {} --notification-id $NOTIF_ID

Config

After login, your session is saved automatically — you won't need to re-authenticate on every command:

~/.config/kuma-cli-nodejs/config.json  (Linux/macOS)
%APPDATA%\kuma-cli-nodejs\Config       (Windows)

{
  "url": "https://kuma.example.com",
  "token": "***"
}

Run kuma status to see the exact config path on your machine.

Architecture

kuma-cli talks to Uptime Kuma through its native Socket.IO API — the same protocol the web UI uses. No REST shims, no scraping, no hacks.

kuma login  → socket.emit("login")         → receives token
kuma *      → socket.emit("loginByToken")  → authenticated session

Development

git clone https://github.com/BlackAsteroid/kuma-cli
cd kuma-cli
npm install
npm run dev        # watch mode (tsup)
npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit

Directory Structure

src/
├── index.ts          # Entry point, CLI setup
├── client.ts         # Socket.IO connection + auth
├── config.ts         # ~/.kuma-cli.json persistence
├── commands/
│   ├── login.ts
│   ├── logout.ts
│   ├── monitors.ts
│   ├── status-pages.ts
│   └── heartbeat.ts
└── utils/
    ├── output.ts     # Table rendering, chalk helpers
    └── errors.ts     # Error formatting + exit codes

License

MIT — Black Asteroid