happyuptime-cli

The official CLI for Happy Uptime — monitor uptime, manage incidents, and check site speed from your terminal.

Install

npm install -g happyuptime-cli

Or use without installing:

npx happyuptime-cli status

Quick Start

# 1. Authenticate (opens browser, auto-fills code)
happy login

# 2. Check your monitors
happy status

# 3. Speed test any URL
happy speed-test https://example.com

# Optional: install the agent skill
happy skill install

First-time users with zero monitors are walked through an interactive onboarding wizard that creates their first monitor and runs an initial check. No dashboard visit required.

Commands

Authentication

happy login                    # Device flow: opens browser, auto-fills code
happy login --api-key hu_xxx   # Direct key save (CI/CD)
happy login --no-browser       # Print URL+code without opening browser (SSH)
happy login --no-wizard        # Skip first-run onboarding wizard
happy whoami                   # Show current auth status
happy logout                   # Remove saved credentials

Device flow (default): happy login calls the API to generate a short-lived device code, opens happyuptime.com/device?code=XXXX-XXXX in your browser with the code pre-filled, and polls for authorization. Once you sign in, the CLI picks up a write-scoped API key named "CLI — YYYY-MM-DD" and saves it to ~/.happyuptime/config.json. The key is visible in your dashboard under Settings > API Keys.

You can also set the HAPPYUPTIME_API_KEY environment variable instead of using happy login (useful for CI/CD).

Agent Skill

happy skill install           # ~/.claude/skills/happyuptime/SKILL.md
happy skill install --codex   # ~/.codex/skills/happyuptime/SKILL.md
happy skill install --all     # both directories
happy skill print             # print the skill markdown
happy skill path              # show default install paths

The skill teaches Claude Code, Codex, and other markdown-based agent runtimes the Happy Uptime API, CLI commands, config-as-code format, and recommended monitoring workflows.

Status Overview

happy status          # Quick overview of all monitors
happy status --json   # JSON output for scripting

Example output:

  ● All systems operational

  Monitors
  ● Production API
  ● Marketing Site
  ▲ Staging API degraded
  ○ Dev Server (paused)

  10 monitors | 8 up | 0 down | 1 degraded

Monitors

happy monitors list                           # List all monitors
happy monitors list --status down             # Filter by status
happy monitors list --type http               # Filter by type
happy monitors get <id>                       # Show monitor details

happy monitors create \
  --name "Production API" \
  --url https://api.example.com/health \
  --type http \
  --interval 60 \
  --regions us-east,eu-west                   # Create a monitor

happy monitors pause <id>                     # Pause monitoring
happy monitors resume <id>                    # Resume monitoring
happy monitors delete <id>                    # Delete (with confirmation)
happy monitors check https://example.com      # Quick-check a URL

Incidents

happy incidents list                          # List incidents
happy incidents list --status investigating   # Filter by status
happy incidents get <id>                      # Show incident detail + timeline

happy incidents create "API is slow" \
  --severity major \
  --message "Investigating elevated latency"  # Create incident

happy incidents update <id> \
  --status identified \
  --message "Found root cause: database"      # Add status update

happy incidents resolve <id> \
  --message "Fix deployed, monitoring"        # Resolve incident

Alerts

happy alerts list                             # List alert channels

happy alerts create \
  --name "Slack Engineering" \
  --type slack \
  --webhook-url https://hooks.slack.com/...   # Create channel

happy alerts delete <id>                      # Delete channel

Speed Test

Test any URL from 6 global regions with timing waterfall:

happy speed-test https://example.com

Output includes a waterfall visualization:

  Speed Test: https://example.com
  Avg: 245ms  Min: 180ms  Max: 420ms

  ┌──────────┬────────┬──────┬───────┬─────┬─────────┬─────┬──────┐
  │ Region   │ Status │ Code │ Total │ DNS │ Connect │ TLS │ TTFB │
  ├──────────┼────────┼──────┼───────┼─────┼─────────┼─────┼──────┤
  │ us-east  │ up     │ 200  │ 180ms │ 12ms│ 25ms    │ 35ms│ 108ms│
  │ eu-west  │ up     │ 200  │ 245ms │ 15ms│ 45ms    │ 52ms│ 133ms│
  └──────────┴────────┴──────┴───────┴─────┴─────────┴─────┴──────┘

  Waterfall
  us-east         ██████████████████████ 180ms
  eu-west         ████████████████████████████ 245ms

  ■ DNS  ■ Connect  ■ TLS  ■ TTFB  ■ Transfer

No authentication required for speed tests.

Config-as-Code

Manage monitors declaratively with happyuptime.yml:

happy config pull                # Export current monitors to YAML
happy config push                # Sync YAML to Happy Uptime
happy config push --dry-run      # Preview changes without applying
happy config validate            # Validate YAML syntax

Example happyuptime.yml:

monitors:
  - name: Production API
    url: https://api.example.com/health
    type: http
    interval: 60
    regions:
      - us-east
      - eu-west
      - ap-southeast
    tags:
      - production
      - critical

  - name: Marketing Site
    url: https://example.com
    type: http
    interval: 300
    regions:
      - us-east
      - eu-west

  - name: Database Backup
    type: heartbeat
    interval: 3600

Environment variable substitution is supported:

monitors:
  - name: API
    url: ${API_URL}/health
    headers:
      Authorization: Bearer ${API_TOKEN}

Custom data sources

Connect a JSON health endpoint that exposes multiple subsystems (e.g. api.example.com/system-status). Each subsystem becomes a real monitor that participates in alerts, incidents, SLA, status pages, and widgets — all from a single fetch per tick.

Commands

happy data-sources list                        # List all data sources
happy data-sources get <id>                    # Full detail with fields + child monitors
happy data-sources create \
  --name "B3OS" \
  --url https://api.b3os.org/v1/system-status  # Create a new source
happy data-sources delete <id>                 # Remove a data source and all its children
happy data-sources fetch <id>                  # Trigger an immediate fetch
happy data-sources discover <url>              # Get AI-suggested field mapping for an endpoint
happy data-sources publish <id> \
  --status-page <status-page-id>               # Add all fields to a status page as components

Config-as-code (happyuptime.yml)

data_sources:
  - name: B3OS
    url: https://api.b3os.org/v1/system-status
    fetch_interval: 60
    root_path: subsystems
    fields:
      - path: price_websocket.status
        name_template: Price WebSocket
        rule: { type: in, values: [connected, healthy] }
      - path: evm_log_pollers.chains.*
        name_template: EVM Chain {key}
        rule: { type: diff_lte, fieldA: head_block, fieldB: last_block, max: 5 }

Use happy config push to sync, happy config pull to export, happy config validate to lint.

Rule types: eq, ne, gt, lt, gte, lte, in, not_in, contains, not_contains, regex, diff_lte, diff_gte, truthy, falsy.

The YAML uses a merged rule shape rule: { type, ...config }. The API splits this into rule_type + rule_config internally — the CLI converts automatically.

Environment Variables

| Variable | Description | |---|---| | HAPPYUPTIME_API_KEY | API key (alternative to happy login) | | HAPPYUPTIME_API_URL | Custom API base URL (default: https://happyuptime.com) |

JSON Output

All commands support --json for machine-readable output:

happy status --json | jq '.monitors | length'
happy monitors list --json | jq '.data[] | select(.status == "down")'

CI/CD Usage

Use in GitHub Actions or other CI pipelines:

# .github/workflows/deploy.yml
- name: Check monitors after deploy
  run: |
    npx happyuptime-cli status --json
  env:
    HAPPYUPTIME_API_KEY: ${{ secrets.HAPPYUPTIME_API_KEY }}

# Create incident on deploy failure
- name: Report deploy failure
  if: failure()
  run: |
    npx happyuptime-cli incidents create "Deploy failed" \
      --severity major \
      --message "Deploy to production failed in CI"
  env:
    HAPPYUPTIME_API_KEY: ${{ secrets.HAPPYUPTIME_API_KEY }}

Config File

Credentials are stored in ~/.happyuptime/config.json:

{
  "apiKey": "hu_xxx",
  "apiUrl": "https://happyuptime.com"
}

Requirements

• Node.js 18+

Links

• Happy Uptime
• API Documentation
• Dashboard
• GitHub

License

MIT