Kōdo CLI

Command-line interface for managing your Kōdo status page.

Installation

npm install -g kodo-cli

Or use directly with npx:

npx kodo-cli --help

Quick Start

# Login with your API key (found at /dashboard/api)
# Safer: avoid putting secrets in shell history
KODO_API_KEY=your-api-key-here kodo login --from-env

# View status overview
kodo status

# List services
kodo services list

# Create an incident
kodo incidents create -t "Database issues" --severity major -m "Investigating slow queries"

# Resolve an incident
kodo incidents resolve abc123 -m "Fixed the connection pool configuration"

Commands

Config as code (init / apply / diff)

Declare your services, monitors, and status pages in a kodo.yaml and manage them like infrastructure:

# Scaffold kodo.yaml + the SDK snippet (detects express / nextjs / fastify / node / deno)
kodo init

# Provision everything in kodo.yaml against your account
kodo apply

# Preview the difference between kodo.yaml and remote state (like `terraform plan`)
kodo diff

Drop kodo apply into CI (see CI/CD Integration) to keep monitoring in sync with your repo.

Live tail

Stream errors and incidents as they happen — the way you'd reach for fly logs / railway logs:

kodo tail                      # errors + incidents, live
kodo tail --errors -e production   # just production errors
kodo tail --incidents              # just incident lifecycle
kodo tail --json | jq .            # NDJSON, for piping
kodo tail -i 10 -n 20              # poll every 10s, 20 lines of initial context

Process Health (collect)

The zero-code Process Health source. If your runs already live in a table — a jobs queue, a saga table, webhook_deliveries — point Kōdo at it instead of wrapping code. The collector reads the table in your own infrastructure (the DB connection never leaves your network) and ships only normalized run summaries.

# kodo.yaml
processes:
  - name: webhook-delivery
    source: postgres
    connection: ${DATABASE_URL}   # resolved from your env, locally
    table: webhook_deliveries
    id: id
    status: status
    status_map: { delivered: ok, failed: failed, pending: running }
    started_at: created_at
    completed_at: updated_at       # optional — used for duration

kodo collect            # watch + ship continuously
kodo collect --once     # single pass (e.g. from your own cron)
kodo collect -i 30      # poll every 30s

status_map is optional — common values (success/completed/delivered → ok, failed/error → failed) are recognized by default. A per-source cursor is tracked in .kodo-collector-state.json so each run ships exactly once. Needs the pg package (npm install pg). Wrap code with the SDK's workflow() instead if you want live stuck detection.

Authentication

# Save API key
kodo login <api-key>
kodo login --from-env    # reads KODO_API_KEY from environment
kodo login <api-key> --url https://your-custom-domain.com

# Credentials are stored in your OS keychain when available
# (falls back to local config storage if keychain is unavailable)

# Remove saved credentials
kodo logout

# Show current config
kodo whoami

Status Overview

# Quick overview of services and incidents
kodo status

Incidents

# List all incidents
kodo incidents list
kodo incidents ls                           # alias
kodo incidents list --status investigating  # filter by status

# Create incident
kodo incidents create -t "Title" --severity major
kodo incidents create -t "API down" --severity critical -m "Investigating the issue" --services "API,Database"

# Update incident
kodo incidents update <id> -s identified -m "Found the root cause"

# Resolve incident
kodo incidents resolve <id>
kodo incidents resolve <id> -m "Deployed fix"

# Get incident details
kodo incidents get <id>

# Delete incident
kodo incidents delete <id> --force

Services

# List all services
kodo services list
kodo services ls                # alias

# Create service
kodo services create -n "API Gateway" -d "Main API service"

# Update service status
kodo services status "API" degraded
kodo services status <service-id> maintenance

# Quick status shortcuts
kodo services up "API"     # Set to operational
kodo services down "API"   # Set to major_outage

# Delete service
kodo services delete <id> --force

Heartbeat

# Simple heartbeat ping
kodo heartbeat <monitor-id>
kodo hb <monitor-id>        # alias

# With status details
kodo heartbeat <monitor-id> --status up --time 1523 --message "Backup completed"

Environment Variables

| Variable | Description | |----------|-------------| | KODO_API_KEY | API key (overrides saved config) | | KODO_API_URL | API base URL (default: https://kodostatus.com) |

CI/CD Integration

GitHub Actions

- name: Create incident on failure
  if: failure()
  run: npx kodo-cli incidents create -t "Deploy failed" --severity major
  env:
    KODO_API_KEY: ${{ secrets.KODO_API_KEY }}

Cron Job Heartbeat

# Add to crontab
0 * * * * /usr/local/bin/backup.sh && npx kodo-cli heartbeat my-backup-monitor

License

MIT