@kill-switch/cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,178 @@
+# @kill-switch/cli
+
+Stop runaway cloud bills from the terminal. Monitor Cloudflare, GCP, and AWS spending with automatic kill switches that shut down services before they drain your account.
+
+Born from a [$91K Cloudflare bill](https://kill-switch.net).
+
+## Install
+
+```sh
+npm install -g @kill-switch/cli
+```
+
+This gives you two commands: `kill-switch` and `ks` (short alias).
+
+## Quick Start
+
+```sh
+# 1. Get an API key from https://app.kill-switch.net (Settings > API Keys)
+ks auth login --api-key ks_live_your_key_here
+
+# 2. Connect your cloud provider and apply protection
+ks onboard --provider cloudflare \
+  --account-id YOUR_ACCOUNT_ID \
+  --token YOUR_API_TOKEN \
+  --name "Production" \
+  --shields cost-runaway,ddos
+
+# 3. Check your accounts
+ks check
+```
+
+## One-Command Setup
+
+The `onboard` command connects a provider, applies shield presets, and configures alerts in one step:
+
+```sh
+# Cloudflare
+ks onboard --provider cloudflare \
+  --account-id YOUR_CF_ACCOUNT_ID \
+  --token YOUR_CF_API_TOKEN \
+  --name "Production" \
+  --shields cost-runaway,ddos \
+  --alert-email you@example.com
+
+# AWS
+ks onboard --provider aws \
+  --access-key AKIA... \
+  --secret-key wJalr... \
+  --region us-east-1 \
+  --shields aws-cost-runaway,gpu-runaway
+
+# GCP
+ks onboard --provider gcp \
+  --project-id my-project-123 \
+  --service-account "$(cat key.json)" \
+  --shields cost-runaway
+
+# Interactive mode (prompts for everything)
+ks onboard
+```
+
+Don't know where to find your credentials? Run:
+
+```sh
+ks onboard --help-provider cloudflare
+ks onboard --help-provider aws
+ks onboard --help-provider gcp
+```
+
+## Shields (Quick Protect)
+
+Apply preset protection rules with one command:
+
+```sh
+ks shield cost-runaway        # Kill services exceeding daily cost limit
+ks shield ddos                # Kill services getting excessive requests
+ks shield gpu-runaway         # Stop unexpected GPU instances
+ks shield lambda-loop         # Throttle recursive Lambda invocations
+ks shield aws-cost-runaway    # Emergency stop on AWS daily spend spike
+ks shield brute-force         # Rotate creds on mass auth failures
+ks shield exfiltration        # Isolate on unusual egress
+ks shield error-storm         # Scale down on sustained high error rate
+
+# List all shields
+ks shield --list
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ks onboard` | One-command setup: connect + shields + alerts |
+| `ks auth login` | Authenticate with API key |
+| `ks auth status` | Show auth status |
+| `ks accounts list` | List connected cloud accounts |
+| `ks accounts add` | Connect a cloud provider |
+| `ks accounts check <id>` | Run manual check on an account |
+| `ks check` | Check all accounts |
+| `ks shield <preset>` | Apply a protection preset |
+| `ks rules list` | List active rules |
+| `ks alerts list` | List alert channels |
+| `ks analytics` | Cost analytics overview |
+| `ks config list` | Show configuration |
+
+## AI Agent Usage
+
+The CLI is designed for AI coding agents (Claude Code, Cursor, Windsurf) to set up cloud monitoring on behalf of users without interactive prompts.
+
+```sh
+# Set API key via env var
+export KILL_SWITCH_API_KEY=ks_live_your_key
+
+# Non-interactive setup with JSON output
+ks onboard \
+  --provider cloudflare \
+  --account-id CF_ACCOUNT_ID \
+  --token CF_API_TOKEN \
+  --name "Production" \
+  --shields cost-runaway,ddos \
+  --json
+
+# All commands support --json for machine-readable output
+ks accounts list --json
+ks check --json
+ks analytics --json
+```
+
+### CLAUDE.md Integration
+
+Add this to your project's `CLAUDE.md` so your AI agent knows how to manage Kill Switch:
+
+```markdown
+## 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`
+- Docs: `ks onboard --help-provider cloudflare`
+```
+
+## Authentication
+
+The CLI uses personal API keys (prefixed with `ks_live_`). Create one from [app.kill-switch.net](https://app.kill-switch.net) under Settings > API Keys.
+
+**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` (set by `ks auth login`)
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output raw JSON (for automation/scripting/AI agents) |
+| `--api-key <key>` | Override API key for this command |
+| `--api-url <url>` | Override API URL |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Client error (bad arguments, API error) |
+| `2` | Authentication error (invalid/missing API key) |
+
+## Links
+
+- [Website](https://kill-switch.net)
+- [Dashboard](https://app.kill-switch.net)
+- [API Docs](https://kill-switch.net/docs)
+- [CLI Docs](https://kill-switch.net/docs/cli.html)
+- [GitHub](https://github.com/AiExpanse/kill-switch)
+
+## License
+
+MIT

package/dist/commands/auth.js

@@ -1,17 +1,90 @@
 import { saveConfig, deleteConfig, resolveApiKey, resolveApiUrl } from "../config.js";
 import { apiRequest } from "../api-client.js";
 import { outputJson, formatObject, outputError } from "../output.js";
+import { createInterface } from "readline";
+import { execFile } from "child_process";
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    execFile(cmd, [url], () => { });
+}
 export function registerAuthCommands(program) {
     const auth = program.command("auth").description("Manage authentication");
+    auth
+        .command("setup")
+        .description("Create an API key (opens browser to sign in, then paste the key)")
+        .action(async () => {
+        const json = program.opts().json;
+        const existing = resolveApiKey();
+        if (existing) {
+            try {
+                const result = await apiRequest("/accounts/me");
+                if (!json) {
+                    console.log(`Already authenticated as ${result.name || result._id}.`);
+                    const proceed = await ask("Create a new API key anyway? (y/N): ");
+                    if (proceed.toLowerCase() !== "y")
+                        return;
+                }
+            }
+            catch {
+                // Key invalid, proceed
+            }
+        }
+        if (!json) {
+            console.log("\n\u26a1 Kill Switch CLI Setup\n");
+            console.log("Opening app.kill-switch.net in your browser...");
+            console.log("1. Sign in (or create an account)");
+            console.log("2. Go to Settings > API Keys");
+            console.log("3. Click 'Create API Key'");
+            console.log("4. Copy the key and paste it below\n");
+        }
+        openBrowser("https://app.kill-switch.net/settings");
+        const key = await ask("Paste your API key (ks_live_...): ");
+        if (!key.startsWith("ks_")) {
+            outputError("API key must start with 'ks_'. Try again.", json);
+            process.exit(1);
+        }
+        try {
+            const result = await apiRequest("/accounts/me", { apiKey: key });
+            saveConfig({ apiKey: key, apiUrl: resolveApiUrl() });
+            if (json) {
+                outputJson({ authenticated: true, account: result.name || result._id });
+            }
+            else {
+                console.log(`\n\u2713 Authenticated as ${result.name || result._id}`);
+                console.log("API key saved to ~/.kill-switch/config.json\n");
+                console.log("Next: ks onboard --provider cloudflare --help-provider cloudflare");
+            }
+        }
+        catch (err) {
+            outputError(`Authentication failed: ${err.message}`, json);
+            process.exit(2);
+        }
+    });
     auth
         .command("login")
-        .description("Authenticate with an API key")
-        .requiredOption("--api-key <key>", "Personal API key (starts with ks_)")
+        .description("Authenticate with an existing API key")
+        .option("--api-key <key>", "Personal API key (starts with ks_)")
         .action(async (opts) => {
         const json = program.opts().json;
-        const key = opts.apiKey;
+        let key = opts.apiKey;
+        if (!key) {
+            if (json) {
+                outputError("--api-key is required in JSON mode", json);
+                process.exit(1);
+            }
+            key = await ask("API key (ks_live_...): ");
+        }
         if (!key.startsWith("ks_")) {
-            outputError("API key must start with 'ks_'. Create one at app.kill-switch.net.", json);
+            outputError("API key must start with 'ks_'. Create one at app.kill-switch.net or run: ks auth setup", json);
             process.exit(1);
         }
         // Validate the key by calling the API

package/dist/commands/onboard.js

@@ -77,6 +77,21 @@ const PROVIDER_HELP = {
     Run: aws configure get region
     Common values: us-east-1, us-west-2, eu-west-1`,
     },
+    runpod: {
+        name: "RunPod",
+        fields: "--runpod-api-key",
+        howToGet: `How to get this value:
+
+  API Key:
+    1. Go to https://www.runpod.io/console/user/settings
+    2. Scroll to "API Keys" section
+    3. Click "Create API Key" (or copy an existing one)
+    4. The key starts with a long alphanumeric string
+
+  Required permissions:
+    - Read access to pods, serverless endpoints, and network volumes
+    - Write access if you want auto-kill actions (stop/terminate pods, scale endpoints)`,
+    },
 };
 const AVAILABLE_SHIELDS = [
     "cost-runaway", "ddos", "brute-force", "error-storm",
@@ -105,6 +120,7 @@ export function registerOnboardCommands(program) {
         .option("--access-key <key>", "Access Key ID (AWS)")
         .option("--secret-key <key>", "Secret Access Key (AWS)")
         .option("--region <region>", "Region (AWS, default: us-east-1)")
+        .option("--runpod-api-key <key>", "API Key (RunPod)")
         .option("--shields <presets>", "Comma-separated shield presets to apply (default: cost-runaway)")
         .option("--alert-email <email>", "Email address for alerts")
         .option("--alert-discord <url>", "Discord webhook URL for alerts")
@@ -146,7 +162,7 @@ Available shields: ${AVAILABLE_SHIELDS.join(", ")}
         if (opts.helpProvider) {
             const help = PROVIDER_HELP[opts.helpProvider];
             if (!help) {
-                outputError(`Unknown provider: ${opts.helpProvider}. Use: cloudflare, gcp, aws`, json);
+                outputError(`Unknown provider: ${opts.helpProvider}. Use: cloudflare, gcp, aws, runpod`, json);
                 process.exit(1);
             }
             if (json) {
@@ -165,7 +181,7 @@ Available shields: ${AVAILABLE_SHIELDS.join(", ")}
             // Interactive mode if no provider specified
             if (!provider) {
                 if (json) {
-                    outputError("--provider is required in JSON mode. Use: cloudflare, gcp, aws", json);
+                    outputError("--provider is required in JSON mode. Use: cloudflare, gcp, aws, runpod", json);
                     process.exit(1);
                 }
                 console.log("\n\u26a1 Kill Switch Onboarding\n");
@@ -174,12 +190,13 @@ Available shields: ${AVAILABLE_SHIELDS.join(", ")}
                 console.log("  1. cloudflare  — Workers, R2, D1, Queues, Stream");
                 console.log("  2. gcp         — Cloud Run, Compute, GKE, BigQuery");
                 console.log("  3. aws         — EC2, Lambda, RDS, ECS, S3");
+                console.log("  4. runpod      — GPU Pods, Serverless Endpoints, Network Volumes");
                 console.log();
-                const choice = await ask("Choose a provider (1/2/3 or name): ");
-                provider = { "1": "cloudflare", "2": "gcp", "3": "aws" }[choice] || choice;
+                const choice = await ask("Choose a provider (1/2/3/4 or name): ");
+                provider = { "1": "cloudflare", "2": "gcp", "3": "aws", "4": "runpod" }[choice] || choice;
             }
             if (!PROVIDER_HELP[provider]) {
-                outputError(`Unknown provider: ${provider}. Use: cloudflare, gcp, aws`, json);
+                outputError(`Unknown provider: ${provider}. Use: cloudflare, gcp, aws, runpod`, json);
                 process.exit(1);
             }
             if (!name && !json) {
@@ -248,6 +265,18 @@ Available shields: ${AVAILABLE_SHIELDS.join(", ")}
                 credential.awsSecretAccessKey = secretKey;
                 credential.awsRegion = region || "us-east-1";
             }
+            else if (provider === "runpod") {
+                let apiKey = opts.runpodApiKey;
+                if (!apiKey && !json) {
+                    console.log("\n  Tip: Create an API Key at https://www.runpod.io/console/user/settings");
+                    apiKey = await ask("  RunPod API Key: ");
+                }
+                if (!apiKey) {
+                    outputError(`RunPod requires ${PROVIDER_HELP.runpod.fields}`, json);
+                    process.exit(1);
+                }
+                credential.runpodApiKey = apiKey;
+            }
             // 1. Connect cloud account
             if (!json)
                 console.log(`\nConnecting ${PROVIDER_HELP[provider].name}...`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kill-switch/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Kill Switch CLI — monitor cloud spending, kill runaway services from the terminal",
   "type": "module",
   "bin": {
@@ -23,6 +23,13 @@
   "engines": {
     "node": ">=18"
   },
-  "files": ["dist"],
+  "files": ["dist", "README.md"],
+  "keywords": ["cloud", "kill-switch", "cost-monitoring", "cloudflare", "aws", "gcp", "runpod", "gpu", "finops", "billing", "cli", "devops"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AiExpanse/kill-switch",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://kill-switch.net",
   "license": "MIT"
 }