CLI Tool

The Kodo CLI lets you manage incidents, services, monitors, webhooks, and more from your terminal. Designed for both interactive use and CI/CD pipelines.

Installation

npm install -g kodo-cli

Requires Node.js 18 or later.

Authentication

# Login with your API key
kodo login YOUR_API_KEY

# Or use a custom API URL
kodo login YOUR_API_KEY --url https://your-instance.com

# Or set environment variable (recommended for CI/CD)
export KODO_API_KEY=your_api_key

# Check current config
kodo whoami

# Logout
kodo logout

JSON Output

All commands support the --json flag for structured JSON output. When --json is passed, spinners and colored formatting are suppressed, making it safe for scripting and pipelines.

# Human-readable (default)
kodo services list

# JSON output
kodo --json services list

# Use with jq
kodo --json incidents list | jq '.[].title'

Commands

Status Overview

# Quick overview of services and incidents
kodo status

Incidents

# List incidents
kodo incidents list
kodo incidents list --status investigating

# Create incident
kodo incidents create \
  --title "Database issues" \
  --status investigating \
  --severity major \
  --services "API,Database" \
  --message "We are investigating connection timeouts"

# Get incident details
kodo incidents get INCIDENT_ID

# Update incident
kodo incidents update INCIDENT_ID \
  --status identified \
  --message "Root cause identified"

# Resolve incident (shortcut)
kodo incidents resolve INCIDENT_ID \
  --message "Issue resolved"

# Delete incident
kodo incidents delete INCIDENT_ID --force

Services

# List services
kodo services list

# Create service
kodo services create \
  --name "Payment API" \
  --description "Handles payment processing"

# Update service status
kodo services status "Payment API" degraded

# Quick shortcuts
kodo services up "Payment API"      # Mark as operational
kodo services down "Payment API"    # Mark as major outage

# Delete service
kodo services delete SERVICE_ID --force

Uptime Monitors

# List monitors
kodo monitors list

# Create HTTP monitor
kodo monitors create \
  --name "API Health" \
  --type http \
  --url "https://api.example.com/health" \
  --interval 300

# Create heartbeat monitor
kodo monitors create \
  --name "Nightly Backup" \
  --type heartbeat

# Get monitor details
kodo monitors get MONITOR_ID

# Update monitor
kodo monitors update MONITOR_ID --interval 60 --enable

# Delete monitor
kodo monitors delete MONITOR_ID --force

Heartbeat

# Send a heartbeat ping
kodo heartbeat MONITOR_ID

# With status and response time
kodo heartbeat MONITOR_ID --status up --time 250

# Short alias
kodo hb MONITOR_ID

SSL Monitors

# List SSL monitors
kodo ssl list

# Add SSL monitor
kodo ssl add example.com
kodo ssl add api.example.com --port 443 --warn 14 --critical 7

# Get monitor details
kodo ssl get MONITOR_ID

# Trigger manual check
kodo ssl check MONITOR_ID

# Update thresholds
kodo ssl update MONITOR_ID --warn 21 --critical 7

# Enable/disable
kodo ssl update MONITOR_ID --disable
kodo ssl update MONITOR_ID --enable

# Delete
kodo ssl delete MONITOR_ID --force

Domain Monitors

# List domain monitors
kodo domains list

# Add domain monitor
kodo domains add example.com
kodo domains add example.com --warn 30 --critical 14

# Get monitor details
kodo domains get MONITOR_ID

# Trigger manual check
kodo domains check MONITOR_ID

# Update thresholds
kodo domains update MONITOR_ID --warn 60 --critical 30

# Delete
kodo domains delete MONITOR_ID --force

Webhooks

# List webhooks
kodo webhooks list

# Create webhook
kodo webhooks create \
  --name "Deploy notifications" \
  --url "https://example.com/webhook" \
  --events "incident.created,incident.resolved"

# Create with custom secret
kodo webhooks create \
  --name "Slack relay" \
  --url "https://example.com/hook" \
  --secret "my-signing-secret"

# Get webhook details and recent deliveries
kodo webhooks get WEBHOOK_ID

# Update webhook
kodo webhooks update WEBHOOK_ID --name "New Name" --active
kodo webhooks update WEBHOOK_ID --inactive

# Send test delivery
kodo webhooks test WEBHOOK_ID

# Delete
kodo webhooks delete WEBHOOK_ID --force

Notification Channels

# List channels
kodo notifications list

# Add channels (generic)
kodo notifications add slack "Alerts" --webhook-url "https://hooks.slack.com/..."

# Quick add shortcuts
kodo notifications add:slack "Alerts" "https://hooks.slack.com/..."
kodo notifications add:discord "Discord Alerts" "https://discord.com/api/webhooks/..."
kodo notifications add:webhook "Custom" "https://example.com/notify" --secret "my-secret"

# Test a channel
kodo notifications test CHANNEL_ID

# Enable/disable
kodo notifications enable CHANNEL_ID
kodo notifications disable CHANNEL_ID

# Delete
kodo notifications delete CHANNEL_ID --force

Status Page Config

# View current config
kodo config show

# Set individual values
kodo config set name "My Status Page"
kodo config set timezone "America/New_York"

# Update multiple values
kodo config update --name "Acme Status" --color "#FF5733" --timezone "UTC"

# Quick rename
kodo rename "New Name"

Status-as-Code

Manage services declaratively using a kodo.yaml file.

# Initialize a new kodo.yaml
kodo init

# Show differences between local config and remote
kodo diff

# Apply configuration
kodo apply

# Dry run (preview changes without applying)
kodo apply --dry-run

# Use a custom config file
kodo apply --file production.yaml

Example kodo.yaml:

services:
  - name: API
    description: Main REST API
  - name: Website
    description: Public marketing site
  - name: Database
    description: PostgreSQL cluster

CI/CD Integration

GitHub Actions

name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start maintenance
        env:
          KODO_API_KEY: ${{ secrets.KODO_API_KEY }}
        run: |
          npm install -g kodo-cli
          INCIDENT_ID=$(kodo --json incidents create \
            --title "Scheduled Deployment" \
            -s investigating \
            --severity minor | jq -r '.id')
          echo "INCIDENT_ID=$INCIDENT_ID" >> $GITHUB_ENV

      - name: Deploy
        run: ./deploy.sh

      - name: Resolve incident
        if: always()
        env:
          KODO_API_KEY: ${{ secrets.KODO_API_KEY }}
        run: |
          kodo incidents resolve $INCIDENT_ID \
            --message "Deployment complete"

GitLab CI

deploy:
  script:
    - npm install -g kodo-cli
    - export INCIDENT_ID=$(kodo --json incidents create --title "Deployment" -s investigating --severity minor | jq -r '.id')
    - ./deploy.sh
    - kodo incidents resolve $INCIDENT_ID --message "Deployed"
  environment: production

Scripting Example

#!/bin/bash
# deployment-wrapper.sh

export KODO_API_KEY="your_api_key"

# Create maintenance incident and capture ID
INCIDENT=$(kodo --json incidents create \
  --title "Scheduled Deployment" \
  -s investigating \
  --severity minor | jq -r '.id')

# Run deployment
if ./deploy.sh; then
  kodo incidents resolve "$INCIDENT" --message "Deployment successful"
  kodo services up "API"
else
  kodo incidents update "$INCIDENT" \
    -s investigating \
    --severity major \
    --message "Deployment failed, rolling back"
fi

Design Workflow

The CLI supports a git-like workflow for status page design changes:

# Pull the current published design to a local file
kodo status-pages design pull <page-id> -o design.json

# Edit design.json with your changes (theme, layout, template)

# Push the changes as a draft
kodo status-pages design push <page-id> -f design.json -s "Updated brand colors"

# Validate the draft before publishing
kodo status-pages design validate <page-id>

# Publish the draft to make it live
kodo status-pages design publish <page-id>

# View version history
kodo status-pages design versions <page-id>

All design commands support --json for machine-readable output.

Configuration

The CLI stores configuration in your OS config directory using the conf package:

macOS: ~/Library/Preferences/kodo-cli-nodejs/config.json
Linux: ~/.config/kodo-cli-nodejs/config.json
Windows: %APPDATA%\kodo-cli-nodejs\Config\config.json

You can override with environment variables:

Variable	Description
`KODO_API_KEY`	API key (overrides stored key)
`KODO_API_URL`	API URL (overrides stored URL)

Command Reference

Command	Description
`kodo login <key>`	Save API key
`kodo logout`	Clear saved config
`kodo status`	Status overview
`kodo whoami`	Show current config
`kodo incidents <cmd>`	Manage incidents
`kodo services <cmd>`	Manage services
`kodo monitors <cmd>`	Manage uptime monitors
`kodo heartbeat <id>`	Send heartbeat ping
`kodo ssl <cmd>`	Manage SSL monitors
`kodo domains <cmd>`	Manage domain monitors
`kodo webhooks <cmd>`	Manage webhooks
`kodo notifications <cmd>`	Manage notification channels
`kodo status-pages list`	List all status pages
`kodo status-pages create`	Create a new status page
`kodo status-pages get <id>`	Get status page details
`kodo status-pages update <id>`	Update status page settings
`kodo status-pages delete <id>`	Delete a status page
`kodo status-pages services <id>`	List assigned services
`kodo status-pages assign-services <id>`	Assign services to a page
`kodo status-pages design pull <id>`	Pull current design as JSON
`kodo status-pages design push <id>`	Push design draft from file
`kodo status-pages design validate <id>`	Validate current draft or file
`kodo status-pages design publish <id>`	Publish the current draft
`kodo status-pages design versions <id>`	List design version history
`kodo config <cmd>`	Organization configuration
`kodo init`	Create kodo.yaml
`kodo apply`	Apply kodo.yaml config
`kodo diff`	Show config differences
`kodo rename <name>`	Rename status page

Getting Started

Status Management

Monitoring

Alerting

Automation

Notifications

Client Tracking

Integrations

Installation

Authentication

JSON Output

Commands

Status Overview

Incidents

Services

Uptime Monitors

Heartbeat

SSL Monitors

Domain Monitors

Webhooks

Notification Channels

Status Page Config

Status-as-Code

CI/CD Integration

GitHub Actions

GitLab CI

Scripting Example

Design Workflow

Configuration

Command Reference

​Installation

​Authentication

​JSON Output

​Commands

​Status Overview

​Incidents

​Services

​Uptime Monitors

​Heartbeat

​SSL Monitors

​Domain Monitors

​Webhooks

​Notification Channels

​Status Page Config

​Status-as-Code

​CI/CD Integration

​GitHub Actions

​GitLab CI

​Scripting Example

​Design Workflow

​Configuration

​Command Reference

Installation

Authentication

JSON Output

Commands

Status Overview

Incidents

Services

Uptime Monitors

Heartbeat

SSL Monitors

Domain Monitors

Webhooks

Notification Channels

Status Page Config

Status-as-Code

CI/CD Integration

GitHub Actions

GitLab CI

Scripting Example

Design Workflow

Configuration

Command Reference