CLI Reference

Install

# From npm
npm install -g @kill-switch/cli

# From source
git clone https://github.com/divinci-ai/kill-switch.git
cd kill-switch/packages/cli
npm install && npm run build
npm link  # makes `kill-switch` and `ks` available globally

Quick Start

# 1. Authenticate (browser device flow — or pass --api-key)
ks auth setup

# 2. One-command setup (connects provider + applies shields + sets up alerts)
ks onboard --provider cloudflare \
  --account-id YOUR_ACCOUNT_ID \
  --token YOUR_API_TOKEN \
  --name "Production" \
  --shields cost-runaway,ddos \
  --alert-email you@example.com

# 3. Run a monitoring check
ks check

# 4. View results
ks accounts list

Authentication

The CLI authenticates with personal API keys (prefixed with ks_) or a browser device flow. Create a key from the web dashboard at app.kill-switch.net (Settings → API Keys), or via the API.

Auth Resolution Order

1. KILL_SWITCH_API_KEY environment variable (best for CI/CD and AI agents)
2. --api-key flag on any command
3. ~/.kill-switch/config.json file (set by ks auth login / ks auth setup)

Onboard (One-Command Setup)

The fastest way to get protected. Connects a cloud provider, applies shield presets, and configures alerts — all in a single command. Designed for both humans and AI agents. (ks setup is an alias for ks onboard.)

# Interactive onboarding (prompts for each value)
ks onboard

# Non-interactive: connect Cloudflare (for AI agents like Claude Code)
ks onboard \
  --provider cloudflare \
  --account-id 14a6fa23390363382f378b5bd4a0f849 \
  --token your-cf-api-token \
  --name "Production" \
  --shields cost-runaway,ddos \
  --alert-email you@example.com

# Connect AWS
ks onboard \
  --provider aws \
  --access-key AKIA... \
  --secret-key wJalr... \
  --region us-east-1 \
  --shields aws-cost-runaway,gpu-runaway

# Connect GCP
ks onboard \
  --provider gcp \
  --project-id my-project-123 \
  --service-account "$(cat service-account-key.json)" \
  --shields cost-runaway

# Connect RunPod
ks onboard \
  --provider runpod \
  --runpod-api-key "YOUR_RUNPOD_API_KEY" \
  --shields cost-runaway,gpu-runaway

# Connect Neo4j Aura
ks onboard \
  --provider neo4j \
  --neo4j-client-id "YOUR_CLIENT_ID" \
  --neo4j-client-secret "YOUR_CLIENT_SECRET" \
  --shields cost-runaway

# Connect MongoDB Atlas
ks onboard \
  --provider mongodb \
  --mongodb-subtype atlas \
  --atlas-public-key "YOUR_PUBLIC_KEY" \
  --atlas-private-key "YOUR_PRIVATE_KEY" \
  --atlas-project-id "YOUR_PROJECT_ID" \
  --shields cost-runaway

# Show how to get credentials for a provider
ks onboard --help-provider cloudflare
ks onboard --help-provider aws
ks onboard --help-provider gcp
ks onboard --help-provider runpod
ks onboard --help-provider neo4j
ks onboard --help-provider mongodb

Onboard Options

Shield (Quick Protect)

The fastest way to add protection. One command applies a preset rule.

# Apply cost runaway protection
ks shield cost-runaway

# List all available shields
ks shield --list

# Preview without applying
ks shield gpu-runaway --dry-run

# Apply with JSON output (for automation)
ks shield gpu-runaway --json

Available Shields

Cloud Accounts

# Connect Cloudflare
ks accounts add cloudflare \
  --name "Production" \
  --token "your-cf-api-token" \
  --account-id "your-account-id"

# Connect MongoDB Atlas
ks accounts add mongodb \
  --name "Prod Atlas" \
  --atlas-public-key PUB --atlas-private-key PRIV \
  --atlas-project-id PROJ --atlas-cluster-name my-cluster

# Redis Cloud / Neo4j Aura
ks accounts add redis --name "Redis Cloud" --redis-cloud-key K --redis-cloud-secret S --redis-subscription-id ID
ks accounts add neo4j --name "Aura" --neo4j-client-id ID --neo4j-client-secret SECRET

Integration-as-Code (ks apply)

Declare an integration in a version-controlled YAML or JSON file and reconcile it idempotently — no hand-rolled scripts. Secrets stay in the environment via ${ENV} interpolation. Re-running converges and reports each change as + create / ~ update / = unchanged.

# ks.yaml — apply with: ks apply -f ks.yaml
account:
  provider: mongodb
  name: Production Atlas
  credential:                       # only needed to create; ${ENV} interpolated
    mongodbSubType: atlas
    atlasPublicKey: ${ATLAS_PUBLIC_KEY}
    atlasPrivateKey: ${ATLAS_PRIVATE_KEY}
    atlasProjectId: ${ATLAS_PROJECT_ID}
    atlasClusterName: prod-cluster0
  thresholds: { mongodbDailyCostUSD: 40, monthlySpendLimitUSD: 1200 }
  protectedServices: [prod-cluster0]
  productionProtected: true
shields: [cost-runaway]
alerts:
  - { type: pagerduty, routingKey: ${PD_ROUTING_KEY}, name: On-Call }

Diagnostics (ks doctor)

Monitoring

$ ks check
Checked 2 account(s) — 1 violation(s)

✓ cloudflare     Production CF
✗ gcp            GCP Staging

Service               Metric          Current   Threshold   Over    Severity
─────────────────────────────────────────────────────────────────────────────
BigQuery              monthlySpend    $523      $500        1x      warning
  Actions: scale-down

Rules

Database Kill Switch

Multi-step database kill sequences: snapshot → verify → isolate → nuke. Each step is an explicit command — no interactive prompts.

# Initiate a kill sequence
ks kill init \
  --credential-id "cred_abc123" \
  --trigger "credential compromise detected"

# Check status (omit id to list all active)
ks kill status dbkill-xyz789

# Advance to next step
ks kill advance dbkill-xyz789 --credential-id "cred_abc123"

# Final step (nuke) requires human approval
ks kill advance dbkill-xyz789 \
  --credential-id "cred_abc123" \
  --human-approval

# Abort if needed
ks kill abort dbkill-xyz789

Alerts

# PagerDuty (recommended — immediate on-call paging)
ks alerts add --type pagerduty --routing-key YOUR_ROUTING_KEY --name "On-Call"

# Slack or Discord webhook
ks alerts add --type slack --webhook-url https://hooks.slack.com/...
ks alerts add --type discord --webhook-url https://discord.com/api/webhooks/...

# GitHub AI Remediation — triggers Claude Code to open a fix PR on extreme violations
ks alerts add --type github \
  --token ghp_YOUR_PAT \
  --repo-owner YOUR_ORG \
  --repo-name YOUR_REPO \
  --workflow kill-switch-remediate.yml \
  --branch main

# Email or generic webhook
ks alerts add --type email --email you@example.com
ks alerts add --type webhook --webhook-url https://your-service.example.com/webhook

# Remove and test
ks alerts remove "PagerDuty"
ks alerts test

Agent Guard (ks guard)

Kill Switch for coding agents — stop a runaway Claude Code / Cursor / Aider session from racking up an LLM bill. ks guard is the same engine as the standalone @kill-switch/agent-guard binary (agent-guard / ksg) — they share one ledger, budget, and escape hatch.

{ "statusLine": { "type": "command", "command": "agent-guard statusline" } }

🟢 Claude Code plan limits  ·  observed just now
  [██░░░░░░░░░░░░░░░░░░]  5-hour limit 12% used, resets 9:19 AM
  [███░░░░░░░░░░░░░░░░░]  weekly limit 17% used, resets Tue 7:59 PM, ~83% left over 5.0d (~17%/day vs ~14%/day budget)
  [░░░░░░░░░░░░░░░░░░░░]  weekly · Sonnet   1%

# Cap a Claude Code session (dollars — API-key usage)
ks guard install
ks guard config --session-hard 30 --daily-hard 150
ks guard status

# Pro/Max subscription? See your REAL plan limits (no proxy, alert-only)
ks guard usage                       # 5-hour + weekly + per-model (Sonnet/Opus), with resets
ks guard status                      # same, auto-refreshed; tier auto-detected from ~/.claude.json

# Hard 402 wall for any other agent (Cursor, Aider, raw scripts)
ks guard proxy --flavor openai --port 8787
# then point the agent at it:
export OPENAI_BASE_URL=http://localhost:8787

# Escape hatch (human only)
ks guard pause --minutes 30
ks guard resume

Organizations

Multi-org support for team and enterprise tiers. Scope any command to an org with the active selection (ks orgs switch) or the X-Org-Id header via the API.

Activity Log

Audit trail of every mutation — account connects, rule changes, kill sequences, team changes. Available on team/enterprise tiers.

Providers

Inspect supported cloud providers and validate credentials before connecting.

# Validate a Cloudflare token before connecting
ks providers validate cloudflare \
  --token your-cf-api-token \
  --account-id your-account-id

Status Dashboard

$ ks status

Kill Switch Status

  Plan:        pro
  Accounts:    2 active / 10 max
  Rules:       3 enabled
  Kill seqs:   none
  Alerts:      1 channel(s) — pagerduty
  Spend (30d): $55.00 · $12.00 saved · 2 action(s) taken

Connected Accounts:

Provider      Name                       Status        Last Check
──────────────────────────────────────────────────────────────────
cloudflare    Production CF              active        ok
aws           AWS Dev                    active        ok

Alert Channels:

Type          Name                 Enabled   Config
──────────────────────────────────────────────────────────────────
pagerduty     On-Call              true      ****abcd

Analytics

$ ks analytics

Analytics Overview

  Total spend:         $123.45
  Avg daily cost:      $4.11
  Projected monthly:   $127.00
  Savings estimate:    $38.20
  Kill switch actions: 3

Last 7 Days:

Date          Cost (USD)   Services   Violations
──────────────────────────────────────────────────
2026-03-30    3.5          5          0
2026-03-31    5.2          6          1

Account Breakdown:

Provider        Total Cost   Avg Daily
──────────────────────────────────────
cloudflare      80           2.67
aws             43.45        1.44

Configuration

Global Options

AI Agent Usage

The CLI is designed to be used by AI coding agents (Claude Code, Cursor, Windsurf, etc.) to set up cloud cost protection on behalf of users — no manual steps required.

Full Agent Workflow

An AI agent can set up Kill Switch monitoring in a few steps:

# Step 1: Authenticate (user provides their API key, or set env var)
export KILL_SWITCH_API_KEY=ks_live_your_key

# Step 2: Discover how to get credentials for the user's provider
ks onboard --help-provider cloudflare --json
# Agent reads the instructions and helps user create the right token

# Step 3: Connect the provider with one command
ks onboard \
  --provider cloudflare \
  --account-id USER_CF_ACCOUNT_ID \
  --token USER_CF_API_TOKEN \
  --name "Production" \
  --shields cost-runaway,ddos,error-storm \
  --alert-pagerduty ROUTING_KEY \
  --json

# Step 4: Add additional alert channels as needed
ks alerts add --type pagerduty --routing-key ROUTING_KEY --json
ks alerts add --type slack --webhook-url https://hooks.slack.com/... --json

# Step 5: Verify full status
ks status --json

Claude Code / CLAUDE.md Integration

Add this to your project's CLAUDE.md to let Claude Code manage Kill Switch for you:

# In your project's CLAUDE.md:
## Kill Switch (Cloud Cost Protection)
- CLI: `ks` (alias for `kill-switch`)
- Auth: KILL_SWITCH_API_KEY env var or `ks auth login --api-key KEY`
- Setup: `ks onboard --provider cloudflare --account-id ID --token TOKEN`
- Check: `ks check --json`
- Credential help: `ks onboard --help-provider cloudflare`
- Cap my own agent spend: `ks guard install && ks guard config --daily-hard 150`

Non-Interactive Commands for Agents

# All commands work with --json for machine-readable output
ks accounts list --json
ks shield cost-runaway --json
ks check --json
ks rules list --json
ks analytics --json
ks guard status --json

# Parse JSON output
ks check --json | jq '.results[].violations | length'

Environment Variables

Exit Codes

See Also

• API Reference (OpenAPI 3.1)
• Integration Guide (Edge Agent, Spend Guard, Alerting)
• @kill-switch/cli & @kill-switch/agent-guard on npm
• GitHub Repository