> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Tool

> Manage your status page from the command line

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

```bash theme={null}
npm install -g kodo-cli
```

Requires Node.js 18 or later.

## Authentication

```bash theme={null}
# 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.

```bash theme={null}
# Human-readable (default)
kodo services list

# JSON output
kodo --json services list

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

## Commands

### Status Overview

```bash theme={null}
# Quick overview of services and incidents
kodo status
```

### Incidents

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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.

```bash theme={null}
# 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`:

```yaml theme={null}
services:
  - name: API
    description: Main REST API
  - name: Website
    description: Public marketing site
  - name: Database
    description: PostgreSQL cluster
```

## CI/CD Integration

### GitHub Actions

```yaml theme={null}
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

```yaml theme={null}
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

```bash theme={null}
#!/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:

```bash theme={null}
# 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             |