oncall

GoAlert CLI toolkit. Five zero-dependency TypeScript tools for on-call status, alerts, users, services, and escalation policies. Runs with bun.

| CLI | File | Purpose | |-----|------|---------| | oncall | oncall.ts | On-call status, schedules, shift lookup | | alerts | alerts.ts | Alert listing, ack, close, escalate, bulk ops | | users | users.ts | User profiles, contacts, notification rules | | services | services.ts | Service details, integration keys, heartbeats, maintenance | | ep | ep.ts | Escalation policy inspection and dry-run testing |

All tools share a single config.json for GoAlert session auth — run oncall login once and everything works.

Quick Start

# Login to GoAlert
oncall login --user myuser --password mypass

# Check if you're on-call
oncall status

# Check on-call at a specific time
oncall status --at "9am"

# List all schedules
oncall schedules

# See who's on-call for a specific schedule
oncall who "FAST"

Installation

# Install from npm (provides oncall, goalert-alerts, goalert-users, goalert-services, goalert-ep commands)
npm install -g goalert-cli

# Or clone and run directly with bun
git clone https://github.com/agileguy/oncall.git ~/repos/oncall
bun run ~/repos/oncall/oncall.ts

# All CLIs run the same way
bun run ~/repos/oncall/alerts.ts
bun run ~/repos/oncall/users.ts
bun run ~/repos/oncall/services.ts
bun run ~/repos/oncall/ep.ts

Commands

oncall login

Authenticate with GoAlert. Stores session cookie locally.

Flags:

• --host - GoAlert URL (default: https://goalert.example.com)
• --user, -u - Username (or set GOALERT_USER env var)
• --password, -p - Password (or set GOALERT_PASSWORD env var)

oncall status

Check if you're currently on-call. Shows all on-call users with you highlighted. Default command when run with no args.

• Exit code 0 = you are on-call, 1 = you are not (useful for scripting)
• --at - Check a specific time (e.g. "9am", "Monday 10am", "tomorrow 3pm", "fri 9am", "2026-02-21T16:00")
• --schedule, -s - Schedule ID to check
• --json - Machine-readable output (includes me and allOncall fields)

oncall schedules

List all GoAlert schedules. Results are cached locally.

• --json - Machine-readable output

oncall who [name|id]

Show who is currently on-call for a schedule. Accepts schedule name (fuzzy match) or ID.

• --json - Machine-readable output

oncall set-default <name|id>

Set the default schedule used by status and who when no schedule is specified. Accepts schedule name (fuzzy match) or ID.

Global Flags

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --no-color | Disable ANSI colors | | --help, -h | Show help | | --version, -v | Show version |

Environment Variables

Set in ~/.claude/.env or export directly:

| Variable | Description | |----------|-------------| | GOALERT_HOST | GoAlert base URL | | GOALERT_USER | Login username | | GOALERT_PASSWORD | Login password | | GOALERT_SCHEDULE | Default schedule ID |

Scripting Example

# Use in a script to check on-call status
if oncall status --json | jq -e '.oncall' > /dev/null 2>&1; then
  echo "You're on-call!"
fi

Alerts CLI

alerts.ts is a companion CLI for managing GoAlert alerts. It uses the same session as oncall — run oncall login once and both tools work.

bun run ~/repos/oncall/alerts.ts [command] [flags]

Quick Start

# List open alerts
bun run alerts.ts

# See alert counts by service (exits 1 if any unacked)
bun run alerts.ts count

# Acknowledge all unacked alerts
bun run alerts.ts ack-all

# Close all open alerts
bun run alerts.ts close-all

Commands

| Command | Description | |---------|-------------| | list | List alerts (default: open). Supports filters. | | show <id> | Show full alert details with event log | | ack <id...> | Acknowledge one or more alerts by ID | | close <id...> | Close one or more alerts by ID | | escalate <id...> | Escalate one or more alerts to the next step | | services | List all GoAlert services (name + UUID) | | count | Show alert counts by service and status | | ack-all | Acknowledge all unacknowledged alerts | | close-all | Close all open alerts (unacked + acked) |

Flags Reference

list flags:

| Flag | Default | Description | |------|---------|-------------| | --status | open | Filter: unacked, acked, closed, open, all | | --service | — | Filter by service name or UUID | | --search | — | Full-text search on summary/details | | --limit | 20 | Max results |

ack-all / close-all flags:

| Flag | Description | |------|-------------| | --service | Filter by service UUID (use alerts services to find IDs) |

Global flags:

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --no-color | Disable ANSI color output | | --help, -h | Show help | | --version, -v | Show version |

Example Usage

# List only unacknowledged alerts for a specific service
bun run alerts.ts list --status unacked --service My-Service

# Show full details for alert #53
bun run alerts.ts show 53

# Acknowledge specific alerts
bun run alerts.ts ack 53 52 51

# Alert counts as JSON (for dashboards/scripts)
bun run alerts.ts count --json

# Ack all unacked alerts for one service
bun run alerts.ts ack-all --service <service-uuid>

# Scripting: exit 1 if there are unacked alerts
if ! bun run alerts.ts count --no-color > /dev/null 2>&1; then
  echo "Unacked alerts detected!"
fi

Authentication

Authentication is shared with the oncall CLI. Run oncall login once and alerts will use the same session automatically.

oncall login --user myuser --password mypass
bun run alerts.ts count   # works immediately

Users CLI

users.ts is a companion CLI for inspecting GoAlert users, their contact methods, and notification rules. It uses the same session as oncall — run oncall login once and all tools work.

bun run ~/repos/oncall/users.ts [command] [flags]

Quick Start

# List all users
bun run users.ts

# Show your own profile
bun run users.ts me

# See who's on-call right now
bun run users.ts oncall

# View a user's contact methods
bun run users.ts contacts <user-uuid>

Commands

| Command | Description | |---------|-------------| | list | List all users (default). Supports filters. | | show <id> | Show full user details with contacts, rules, on-call | | me | Show current authenticated user's details | | oncall | Show all users currently on-call across services | | contacts <id> | List contact methods for a user | | rules <id> | List notification rules for a user |

Flags Reference

list flags:

| Flag | Default | Description | |------|---------|-------------| | --search | — | Filter by name or email | | --role | — | Filter: admin, user, unknown | | --limit | 50 | Max results |

oncall flags:

| Flag | Description | |------|-------------| | --service | Filter by service name or UUID |

Global flags:

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --no-color | Disable ANSI color output | | --help, -h | Show help | | --version, -v | Show version |

Example Usage

# List all admin users
bun run users.ts list --role admin

# Show your own profile
bun run users.ts me

# See who's on-call right now
bun run users.ts oncall

# Check on-call for specific service
bun run users.ts oncall --service My-Service

# View contact methods
bun run users.ts contacts <user-uuid>

# View notification rules as JSON
bun run users.ts rules <user-uuid> --json

Authentication

Authentication is shared with the oncall CLI. Run oncall login once and users will use the same session automatically.

oncall login --user myuser --password mypass
bun run users.ts me   # works immediately

Services CLI

services.ts is a companion CLI for inspecting GoAlert services. Shares auth with oncall CLI.

bun run ~/repos/oncall/services.ts [command] [flags]

Quick Start

# List all services with alert counts
bun run services.ts

# Show full service details
bun run services.ts show My-Service

# Check who's on-call for a service
bun run services.ts oncall My-Service

# Set a 60-minute maintenance window
bun run services.ts maintenance My-Service --duration 60

Commands

| Command | Description | |---------|-------------| | list | List all services with alert counts (default) | | show <id\|name> | Show full service details | | oncall <id\|name> | Show who is on-call for a service | | alerts <id\|name> | Show active alerts for a service | | keys <id\|name> | List integration keys with URLs | | heartbeats <id\|name> | List heartbeat monitors with state | | maintenance <id\|name> | Check or set maintenance mode |

Flags Reference

list flags:

| Flag | Description | |------|-------------| | --search | Filter by service name | | --json | Machine-readable JSON output |

alerts flags:

| Flag | Default | Description | |------|---------|-------------| | --status | open | Filter: unacked, acked, open, closed, all | | --limit | 20 | Max results |

maintenance flags:

| Flag | Description | |------|-------------| | --duration | Set maintenance window duration in minutes | | --clear | Clear active maintenance mode |

Global flags:

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --no-color | Disable ANSI color output | | --help, -h | Show help | | --version, -v | Show version |

Example Usage

# List all services
bun run services.ts

# Show full details for a service
bun run services.ts show My-Service

# Check who's on-call
bun run services.ts oncall My-Service

# View active alerts
bun run services.ts alerts My-Service --status unacked

# List integration keys
bun run services.ts keys My-Service

# Check heartbeat monitors
bun run services.ts heartbeats My-Service

# Set 60-minute maintenance window
bun run services.ts maintenance My-Service --duration 60

# Clear maintenance mode
bun run services.ts maintenance My-Service --clear

Authentication

Authentication is shared with the oncall CLI. Run oncall login once and services will use the same session automatically.

oncall login --user myuser --password mypass
bun run services.ts list   # works immediately

Escalation Policy CLI

ep.ts is a companion CLI for inspecting GoAlert escalation policies. It uses the same session as oncall — run oncall login once and all tools work.

bun run ~/repos/oncall/ep.ts [command] [flags]

Quick Start

# List all escalation policies
bun run ep.ts

# Show full policy details
bun run ep.ts show My-Policy

# View escalation flow with timing
bun run ep.ts steps My-Policy

# Dry-run: who gets notified right now?
bun run ep.ts test My-Policy

Commands

| Command | Description | |---------|-------------| | list | List all escalation policies (default). Supports filters. | | show <id\|name> | Show full policy details with steps and assigned services | | steps <id\|name> | Show escalation flow with cumulative timing | | test <id\|name> | Dry-run: who gets notified at each step right now |

Flags Reference

list flags:

| Flag | Description | |------|-------------| | --search | Filter by policy name |

Global flags:

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --no-color | Disable ANSI color output | | --help, -h | Show help | | --version, -v | Show version |

Example Usage

# List policies filtered by name
bun run ep.ts list --search my-team

# Show full details as JSON
bun run ep.ts show My-Policy --json

# View escalation flow with cumulative timing
bun run ep.ts steps My-Policy

# JSON escalation flow (for scripting)
bun run ep.ts steps My-Policy --json

# Dry-run notification test
bun run ep.ts test My-Policy

Authentication

Authentication is shared with the oncall CLI. Run oncall login once and ep will use the same session automatically.

oncall login --user myuser --password mypass
bun run ep.ts list   # works immediately

Research Documents

| Document | Description | |----------|-------------| | ntfy.sh Deployment Guide | Secure self-hosting of ntfy.sh in Docker | | Escalation Solutions Guide | Comprehensive comparison of open source alternatives | | Quick Comparison | Feature matrix and recommendations |

License

MIT