@timo972/cc-router 0.7.0

package/dist/cli/cmd-start.js

@@ -0,0 +1,318 @@
+import { select, confirm, password as passwordPrompt } from "@inquirer/prompts";
+import chalk from "chalk";
+import { PROXY_PORT, LITELLM_PORT, ACCOUNTS_PATH } from "../config/paths.js";
+import { accountsFileExists, readConfig, writeConfig, generateProxySecret, } from "../config/manager.js";
+import { writeClaudeSettings } from "../utils/claude-config.js";
+import { checkForUpdate, performUpdate, PKG_NAME } from "../utils/self-update.js";
+import { launchDaemon } from "../daemon/launcher.js";
+import { installService } from "../daemon/service.js";
+import { getLocalIPs } from "../utils/network.js";
+export function registerStart(program) {
+    program
+        .command("start")
+        .description("Start the proxy server")
+        .option("--foreground", "Run in the foreground (stay in this terminal)")
+        .option("--port <port>", "Port to listen on", String(PROXY_PORT))
+        .option("--litellm [url]", "Forward to LiteLLM instead of Anthropic directly")
+        .option("--accounts <path>", "Path to accounts.json", ACCOUNTS_PATH)
+        .option("--reconfigure", "Re-ask run preferences (forget saved preferences)")
+        .action(async (opts) => {
+        // ── Step 0: Check for updates ──────────────────────────────────────────
+        await maybeUpdate();
+        // ── Step 1: Ensure accounts exist ──────────────────────────────────────
+        if (!accountsFileExists(opts.accounts !== ACCOUNTS_PATH ? opts.accounts : undefined)) {
+            console.log(chalk.yellow("\n  No accounts configured yet.\n"));
+            const runSetup = await confirm({
+                message: "Run the setup wizard now?",
+                default: true,
+            });
+            if (runSetup) {
+                const { runSetupWizard } = await import("./cmd-setup.js");
+                await runSetupWizard({ addMode: false });
+                // After setup, re-check
+                if (!accountsFileExists()) {
+                    console.log(chalk.red("\n✗ Setup did not produce accounts. Cannot start.\n"));
+                    process.exit(1);
+                }
+            }
+            else {
+                console.log(chalk.gray("  Run 'cc-router setup' when you're ready.\n"));
+                return;
+            }
+        }
+        // ── Step 2: Resolve run preferences ────────────────────────────────────
+        const cfg = readConfig();
+        // --foreground flag overrides everything
+        if (opts.foreground) {
+            await startForeground(opts);
+            return;
+        }
+        // --reconfigure: forget saved preferences
+        if (opts.reconfigure) {
+            delete cfg.runPreferences;
+            writeConfig(cfg);
+        }
+        let prefs = cfg.runPreferences;
+        if (!prefs) {
+            // First time — ask the user
+            prefs = await askRunPreferences();
+            cfg.runPreferences = prefs;
+            writeConfig(cfg);
+        }
+        // ── Step 3: Handle server mode setup ───────────────────────────────────
+        if (prefs.serverMode && !cfg.proxySecret) {
+            await maybeSetupPassword(cfg);
+        }
+        // ── Step 4: Configure Claude Code if not already done ──────────────────
+        await ensureClaudeCodeConfigured(prefs, cfg);
+        // ── Step 5: Start according to preferences ─────────────────────────────
+        const port = parseInt(opts.port, 10) || prefs.port;
+        const litellmUrl = opts.litellm
+            ? (typeof opts.litellm === "string" ? opts.litellm : `http://localhost:${LITELLM_PORT}`)
+            : undefined;
+        if (opts.litellm && typeof opts.litellm !== "string") {
+            await ensureLiteLLMRunning();
+        }
+        if (prefs.mode === "foreground") {
+            await startForeground(opts);
+            return;
+        }
+        if (prefs.mode === "service") {
+            await installService(prefs.serverMode);
+        }
+        else {
+            // background mode
+            await launchDaemon({
+                port,
+                litellmUrl,
+                accountsPath: opts.accounts !== ACCOUNTS_PATH ? opts.accounts : undefined,
+                serverMode: prefs.serverMode,
+            });
+        }
+        // ── Step 6: Print server mode instructions ─────────────────────────────
+        if (prefs.serverMode) {
+            printServerModeInstructions(port, cfg.proxySecret);
+        }
+    });
+}
+// ─── Interactive preferences ─────────────────────────────────────────────────
+async function askRunPreferences() {
+    console.log(chalk.bold(`\n${"━".repeat(40)}\n  First-time setup\n${"━".repeat(40)}\n`));
+    const mode = await select({
+        message: "How do you want to run CC-Router?",
+        choices: [
+            { name: "In the background  (recommended — runs silently, auto-restarts)", value: "background" },
+            { name: "In the foreground  (stays in this terminal, Ctrl+C to stop)", value: "foreground" },
+        ],
+    });
+    let autoStart = false;
+    if (mode === "background") {
+        autoStart = await confirm({
+            message: "Start automatically when your computer boots?",
+            default: true,
+        });
+    }
+    const serverMode = await confirm({
+        message: "Will this machine serve other devices on the network? (server mode)",
+        default: false,
+    });
+    // For local (non-server) mode, ask about auto-configuring Claude Code
+    let configureClaudeCode = true;
+    if (!serverMode) {
+        configureClaudeCode = await confirm({
+            message: "Configure Claude Code to use the proxy automatically? (recommended)",
+            default: true,
+        });
+    }
+    const prefs = {
+        mode: autoStart ? "service" : mode,
+        serverMode,
+        port: PROXY_PORT,
+        configureClaudeCode,
+    };
+    console.log(chalk.green(`\n  ✓ Preferences saved. Next time 'cc-router start' will use these automatically.`));
+    console.log(chalk.gray(`    Change anytime with: cc-router start --reconfigure\n`));
+    return prefs;
+}
+async function maybeSetupPassword(cfg) {
+    console.log(chalk.yellow("\n  Server mode binds the proxy to the network. A password is REQUIRED —" +
+        "\n  without it, anyone who can reach the port could use your accounts.\n"));
+    const pwChoice = await select({
+        message: "Set a proxy password?",
+        choices: [
+            { name: "Generate automatically  (recommended)", value: "generate" },
+            { name: "Enter my own password", value: "manual" },
+        ],
+    });
+    if (pwChoice === "manual") {
+        const raw = await passwordPrompt({
+            message: "Enter proxy password:",
+            validate: (v) => v.trim().length >= 8 || "Minimum 8 characters",
+        });
+        cfg.proxySecret = raw.trim();
+        writeConfig(cfg);
+        console.log(chalk.green("  ✓ Password saved.\n"));
+        return;
+    }
+    const secret = generateProxySecret();
+    cfg.proxySecret = secret;
+    writeConfig(cfg);
+    console.log(chalk.yellow("\n  *** Save this password — you cannot recover it later ***"));
+    console.log("      " + chalk.bold(secret));
+    console.log(chalk.gray("  Clients will need this to connect.\n"));
+}
+async function ensureClaudeCodeConfigured(prefs, cfg) {
+    // Skip if user opted out (server mode always skips — clients configure themselves)
+    if (prefs.configureClaudeCode === false || prefs.serverMode)
+        return;
+    try {
+        const { readClaudeProxySettings } = await import("../utils/claude-config.js");
+        const current = readClaudeProxySettings();
+        if (current.baseUrl)
+            return; // already configured
+        writeClaudeSettings(prefs.port, `http://localhost:${prefs.port}`);
+        console.log(chalk.green("  ✓ Claude Code configured to use the proxy"));
+    }
+    catch (err) {
+        console.warn(chalk.yellow(`  ⚠ Could not configure Claude Code: ${err.message}`));
+        console.warn(chalk.gray(`    Configure manually: cc-router configure`));
+    }
+}
+// ─── Update check ────────────────────────────────────────────────────────────
+async function maybeUpdate() {
+    let check;
+    try {
+        check = await checkForUpdate(true); // force fresh check, skip disk cache
+        if (!check.updateAvailable)
+            return;
+    }
+    catch {
+        return; // network check is non-critical
+    }
+    // From here, errors should be visible
+    if (check.diff === "major") {
+        console.log(chalk.yellow(`\n  New major version available: v${check.current} → v${check.latest}`));
+        console.log(chalk.gray(`  Update manually: npm i -g ${PKG_NAME}@${check.latest}\n`));
+        return;
+    }
+    console.log(chalk.cyan(`\n  Update available: v${check.current} → v${check.latest} (${check.diff})`));
+    const doUpdate = await confirm({
+        message: "Update now?",
+        default: true,
+    });
+    if (!doUpdate)
+        return;
+    try {
+        const ok = await performUpdate(check.latest);
+        if (ok) {
+            console.log(chalk.green("  ✓ Updated. Restarting with new version...\n"));
+            const { spawn } = await import("child_process");
+            const child = spawn(process.execPath, process.argv.slice(1), {
+                stdio: "inherit",
+                env: process.env,
+            });
+            child.on("exit", (code) => process.exit(code ?? 0));
+            child.on("error", (err) => {
+                console.error(chalk.red(`  Failed to restart after update: ${err.message}`));
+                process.exit(1);
+            });
+            await new Promise(() => { });
+        }
+    }
+    catch (err) {
+        console.error(chalk.yellow(`  ⚠ Update failed: ${err.message}`));
+        console.log(chalk.gray("  Continuing with current version.\n"));
+    }
+}
+// ─── Server mode instructions ────────────────────────────────────────────────
+function printServerModeInstructions(port, secret) {
+    const ips = getLocalIPs();
+    const ip = ips[0] ?? "<your-ip>";
+    console.log(chalk.bold.cyan(`\n  ┌${"─".repeat(56)}┐`));
+    console.log(chalk.bold.cyan(`  │  Server mode active — clients can connect with:      │`));
+    console.log(chalk.bold.cyan(`  ├${"─".repeat(56)}┤`));
+    console.log(chalk.cyan(`  │                                                        │`));
+    console.log(chalk.cyan(`  │  ${chalk.white(`cc-router client connect http://${ip}:${port}`)}${" ".repeat(Math.max(0, 38 - ip.length - String(port).length))}│`));
+    if (secret) {
+        console.log(chalk.cyan(`  │    ${chalk.gray(`--secret ${secret}`)}${" ".repeat(Math.max(0, 43 - secret.length))}│`));
+    }
+    console.log(chalk.cyan(`  │                                                        │`));
+    console.log(chalk.cyan(`  │  Or manually in ~/.claude/settings.json:               │`));
+    console.log(chalk.cyan(`  │  ${chalk.gray(`{`)}                                                     │`));
+    console.log(chalk.cyan(`  │    ${chalk.gray(`"env": {`)}                                             │`));
+    console.log(chalk.cyan(`  │      ${chalk.gray(`"ANTHROPIC_BASE_URL": "http://${ip}:${port}"`)}${" ".repeat(Math.max(0, 30 - ip.length - String(port).length))}│`));
+    if (secret) {
+        console.log(chalk.cyan(`  │      ${chalk.gray(`"ANTHROPIC_AUTH_TOKEN": "${secret}"`)}${" ".repeat(Math.max(0, 30 - secret.length))}│`));
+    }
+    else {
+        console.log(chalk.cyan(`  │      ${chalk.gray(`"ANTHROPIC_AUTH_TOKEN": "proxy-managed"`)}            │`));
+    }
+    console.log(chalk.cyan(`  │    ${chalk.gray(`}`)}                                                    │`));
+    console.log(chalk.cyan(`  │  ${chalk.gray(`}`)}                                                      │`));
+    console.log(chalk.bold.cyan(`  └${"─".repeat(56)}┘\n`));
+    // Plaintext-HTTP warning: the proxy speaks HTTP only. Over a non-loopback
+    // link the proxy secret and every prompt/response travel in the clear.
+    console.log(chalk.yellow.bold("  ⚠ This link is plain HTTP — not encrypted."));
+    console.log(chalk.yellow(`    The password above and all prompts/responses are sent in cleartext and\n` +
+        `    can be read by anyone on the network path. For anything beyond a trusted\n` +
+        `    LAN, put CC-Router behind a TLS-terminating reverse proxy (Caddy, nginx,\n` +
+        `    Cloudflare Tunnel) and hand clients the https:// URL.\n` +
+        `    See: docs/security.md → "Transport security (TLS)".\n`));
+}
+// ─── Foreground start (direct server import) ────────────────────────────────
+async function startForeground(opts) {
+    const litellmUrl = opts.litellm
+        ? (typeof opts.litellm === "string" ? opts.litellm : `http://localhost:${LITELLM_PORT}`)
+        : undefined;
+    if (opts.litellm && typeof opts.litellm !== "string") {
+        await ensureLiteLLMRunning();
+    }
+    // Apply server mode env if configured
+    const cfg = readConfig();
+    if (cfg.runPreferences?.serverMode && !process.env["HOST"]) {
+        process.env["HOST"] = "0.0.0.0";
+    }
+    const { startServer } = await import("../proxy/server.js");
+    await startServer({
+        port: parseInt(opts.port, 10),
+        litellmUrl,
+        accountsPath: opts.accounts !== ACCOUNTS_PATH ? opts.accounts : undefined,
+    });
+}
+// ─── LiteLLM Docker helper ──────────────────────────────────────────────────
+async function ensureLiteLLMRunning() {
+    const { execFile } = await import("child_process");
+    const { promisify } = await import("util");
+    const execFileAsync = promisify(execFile);
+    const litellmUrl = `http://localhost:${LITELLM_PORT}`;
+    try {
+        const res = await fetch(`${litellmUrl}/health`, { signal: AbortSignal.timeout(1_000) });
+        if (res.ok) {
+            console.log(chalk.green(`✓ LiteLLM already running at ${litellmUrl}`));
+            return;
+        }
+    }
+    catch { /* not running */ }
+    console.log(chalk.cyan("Starting LiteLLM via Docker..."));
+    try {
+        await execFileAsync("docker", ["info"]);
+    }
+    catch {
+        console.error(chalk.red("✗ Docker is not running. Start Docker Desktop first."));
+        console.error(chalk.gray("  Or pass a custom LiteLLM URL: cc-router start --litellm http://your-host:4000"));
+        process.exit(1);
+    }
+    try {
+        const { spawn } = await import("child_process");
+        await new Promise((resolve, reject) => {
+            const child = spawn("docker", ["compose", "up", "-d", "litellm"], { stdio: "inherit" });
+            child.on("error", reject);
+            child.on("close", code => code === 0 ? resolve() : reject(new Error(`exit ${code}`)));
+        });
+        console.log(chalk.green(`✓ LiteLLM starting at ${litellmUrl}/ui`));
+    }
+    catch (err) {
+        console.error(chalk.red("✗ Failed to start LiteLLM:"), err.message);
+        process.exit(1);
+    }
+}

package/dist/cli/cmd-status.js

@@ -0,0 +1,177 @@
+import chalk from "chalk";
+import { PROXY_PORT } from "../config/paths.js";
+import { readConfig } from "../config/manager.js";
+export function resolveStatusTarget(port) {
+    const cfg = readConfig();
+    if (cfg.client) {
+        const base = cfg.client.remoteUrl.replace(/\/+$/, "");
+        const headers = {};
+        if (cfg.client.remoteSecret)
+            headers["authorization"] = `Bearer ${cfg.client.remoteSecret}`;
+        return {
+            baseUrl: base,
+            healthUrl: `${base}/cc-router/health`,
+            headers,
+            authToken: cfg.client.remoteSecret,
+        };
+    }
+    const base = `http://localhost:${port}`;
+    const headers = {};
+    if (cfg.proxySecret)
+        headers["authorization"] = `Bearer ${cfg.proxySecret}`;
+    return {
+        baseUrl: base,
+        healthUrl: `${base}/cc-router/health`,
+        headers,
+        authToken: cfg.proxySecret,
+    };
+}
+export function registerStatus(program) {
+    program
+        .command("status")
+        .description("Live dashboard: account health, request counts, recent routing log")
+        .option("--port <port>", "Proxy port to connect to", String(PROXY_PORT))
+        .option("--json", "Output current stats as JSON and exit (non-interactive)")
+        .action(async (opts) => {
+        const port = parseInt(opts.port, 10);
+        if (opts.json) {
+            await jsonOutput(port);
+            return;
+        }
+        await dashboardLoop(port);
+    });
+}
+async function jsonOutput(port) {
+    const { healthUrl, headers } = resolveStatusTarget(port);
+    try {
+        const res = await fetch(healthUrl, {
+            headers,
+            signal: AbortSignal.timeout(2_000),
+        });
+        if (!res.ok) {
+            console.error(chalk.red(`Proxy returned HTTP ${res.status}`));
+            process.exit(1);
+        }
+        console.log(JSON.stringify(await res.json(), null, 2));
+    }
+    catch {
+        console.error(chalk.red(`Cannot connect to proxy at ${healthUrl}`));
+        const cfg = readConfig();
+        if (cfg.client) {
+            console.error(chalk.gray("Is the remote CC-Router running?"));
+        }
+        else {
+            console.error(chalk.gray("Is it running? Start with: cc-router start"));
+        }
+        process.exit(1);
+    }
+}
+/**
+ * Launches the Ink dashboard and handles "re-launch" intents.
+ *
+ * The dashboard cannot run inquirer prompts while Ink owns stdin, so when
+ * the user presses `n` to add an account, Ink unmounts **completely** first.
+ * Only after `waitUntilExit()` resolves — and stdin is restored from raw mode
+ * — does the OAuth flow run. Once tokens are obtained and POSTed to the
+ * server, the dashboard is re-rendered and polling resumes.
+ *
+ * IMPORTANT: The previous design resolved the outer promise from inside
+ * `onIntent` (before Ink unmounted), then raced with `waitUntilExit`. That
+ * caused inquirer to see a half-released stdin and force-close itself.
+ * The fix: `onIntent` writes to a mutable variable; `waitUntilExit()`
+ * is the ONLY thing that resolves the await; stdin is explicitly restored
+ * before inquirer runs.
+ */
+async function dashboardLoop(port) {
+    // Dynamic imports keep these heavy deps out of the cold-start path
+    const [{ render }, { createElement }, { Dashboard }] = await Promise.all([
+        import("ink"),
+        import("react"),
+        import("../ui/Dashboard.js"),
+    ]);
+    while (true) {
+        const target = resolveStatusTarget(port);
+        // `pendingIntent` is set by the Dashboard component via `onIntent`;
+        // it defaults to "quit" so Ctrl+C (exitOnCtrlC) does the right thing
+        // without the Dashboard ever firing onIntent.
+        let pendingIntent = "quit";
+        const instance = render(createElement(Dashboard, {
+            port,
+            baseUrl: target.baseUrl,
+            authToken: target.authToken,
+            onIntent: (i) => { pendingIntent = i; },
+        }), { exitOnCtrlC: true });
+        // Block until Ink has FULLY unmounted and released stdin.
+        // The Dashboard's keyboard handler calls exit() for both `q` and `n`;
+        // Ctrl+C also triggers exit via exitOnCtrlC.
+        await instance.waitUntilExit();
+        // Yield the event loop so any of Ink's pending stdin cleanup tasks
+        // (listeners detach, raw-mode restore) run before inquirer grabs stdin.
+        // Without this, inquirer can see a half-released stdin and throw
+        // "User force closed the prompt".
+        await new Promise(resolve => setImmediate(resolve));
+        // Ink leaves stdin in raw mode. Restore it before running inquirer or
+        // exiting, otherwise the terminal may remain in a broken state.
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+        }
+        // Ink may have paused stdin — resume it so inquirer can read input.
+        process.stdin.resume();
+        if (pendingIntent === "quit")
+            return;
+        // Intent: addAccount — run the OAuth flow, then POST the resulting
+        // tokens to the server we're connected to (local or remote).
+        console.log();
+        console.log(chalk.cyan("→ Adding a new account..."));
+        console.log();
+        const added = await runAddAccountFlow(target);
+        if (added) {
+            console.log(chalk.green(`\n✓ Account "${added}" added. Returning to dashboard...\n`));
+        }
+        else {
+            console.log(chalk.yellow("\n  No account added. Returning to dashboard...\n"));
+        }
+        // Fall through → loop re-renders the dashboard
+    }
+}
+/**
+ * Runs the existing setupSingleAccount() OAuth flow, then POSTs the resulting
+ * tokens to /cc-router/accounts on the active target. Returns the new id on
+ * success, or null if the user aborted / an error occurred.
+ */
+async function runAddAccountFlow(target) {
+    try {
+        const { setupSingleAccount } = await import("./cmd-setup.js");
+        // The index shown in the flow is just for display, pick something neutral.
+        const account = await setupSingleAccount(1);
+        if (!account)
+            return null;
+        const res = await fetch(`${target.baseUrl}/cc-router/accounts`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...target.headers,
+            },
+            body: JSON.stringify({
+                id: account.id,
+                accessToken: account.tokens.accessToken,
+                refreshToken: account.tokens.refreshToken,
+                expiresAt: account.tokens.expiresAt,
+                scopes: account.tokens.scopes,
+            }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(chalk.red(`\n✗ Server rejected account: HTTP ${res.status}`));
+            if (text)
+                console.error(chalk.gray(`  ${text}`));
+            return null;
+        }
+        return account.id;
+    }
+    catch (err) {
+        console.error(chalk.red(`\n✗ Failed to add account: ${err.message}`));
+        return null;
+    }
+}

package/dist/cli/cmd-stop.js

@@ -0,0 +1,100 @@
+import { confirm } from "@inquirer/prompts";
+import chalk from "chalk";
+import { removeClaudeSettings, readClaudeProxySettings } from "../utils/claude-config.js";
+import { PROXY_PORT } from "../config/paths.js";
+import { stopDaemon } from "../daemon/launcher.js";
+import { isProxyRunning } from "../daemon/pid.js";
+import { isServiceInstalled, uninstallService } from "../daemon/service.js";
+import { readConfig, writeConfig } from "../config/manager.js";
+export function registerStop(program) {
+    program
+        .command("stop")
+        .description("Stop the proxy and optionally clean up service / Claude Code config")
+        .option("--keep-config", "Stop the proxy but keep all configuration")
+        .option("--full", "Stop, remove auto-start, and revert Claude Code config (no prompts)")
+        .action(async (opts) => {
+        await stopProxy(opts);
+    });
+}
+export function registerRevert(program) {
+    program
+        .command("revert")
+        .description("Restore Claude Code to its normal authentication (removes proxy config)")
+        .action(async () => {
+        await stopProxy({ full: true });
+    });
+}
+// ─── Core logic ──────────────────────────────────────────────────────────────
+async function stopProxy(opts) {
+    let anythingDone = false;
+    // 1. Stop the proxy process
+    const wasRunning = await isProxyRunning();
+    if (wasRunning) {
+        const stopped = await stopDaemon(PROXY_PORT);
+        if (stopped) {
+            console.log(chalk.green("✓ Proxy process stopped"));
+            anythingDone = true;
+        }
+        else {
+            console.log(chalk.yellow("⚠ Could not stop proxy automatically."));
+            console.log(chalk.gray("  If it's running in a terminal, press Ctrl+C there."));
+            console.log(chalk.gray(`  Or kill manually: kill $(lsof -ti:${PROXY_PORT})`));
+        }
+    }
+    else {
+        console.log(chalk.gray("  Proxy is not running."));
+    }
+    if (opts.keepConfig) {
+        printDone(anythingDone);
+        return;
+    }
+    // 2. Service cleanup
+    const hasService = isServiceInstalled();
+    if (hasService) {
+        let removeService = opts.full ?? false;
+        if (!opts.full) {
+            removeService = await confirm({
+                message: "CC-Router is configured to start on boot. Remove auto-start?",
+                default: false,
+            });
+        }
+        if (removeService) {
+            await uninstallService();
+            // Also clear the service preference so next `start` re-asks
+            const cfg = readConfig();
+            if (cfg.runPreferences?.mode === "service") {
+                cfg.runPreferences.mode = "background";
+                writeConfig(cfg);
+            }
+            anythingDone = true;
+        }
+    }
+    // 3. Claude Code config cleanup
+    const current = readClaudeProxySettings();
+    if (current.baseUrl) {
+        let removeSettings = opts.full ?? false;
+        if (!opts.full) {
+            removeSettings = await confirm({
+                message: "Remove proxy settings from Claude Code? (Claude will use normal auth)",
+                default: false,
+            });
+        }
+        if (removeSettings) {
+            removeClaudeSettings();
+            console.log(chalk.green("✓ Removed proxy settings from ~/.claude/settings.json"));
+            console.log(chalk.gray("  Claude Code will use its normal authentication on next launch."));
+            anythingDone = true;
+        }
+    }
+    printDone(anythingDone);
+}
+function printDone(anythingDone) {
+    if (!anythingDone) {
+        console.log(chalk.gray("\nNothing to do — proxy was not running and config was not set."));
+    }
+    else {
+        console.log(chalk.green("\n✓ Done."));
+        console.log(chalk.gray("  To re-enable: cc-router start"));
+        console.log(chalk.gray("  To reconfigure: cc-router start --reconfigure\n"));
+    }
+}

package/dist/cli/cmd-telemetry.js

@@ -0,0 +1,58 @@
+import chalk from "chalk";
+import { loadTelemetryState, writeTelemetryState, isTelemetryEnabled } from "../config/telemetry.js";
+export function registerTelemetry(program) {
+    program
+        .command("telemetry [action]")
+        .description("Manage anonymous usage analytics: on, off, status (default: status)")
+        .action(async (action) => {
+        const resolved = action ?? "status";
+        if (resolved === "status") {
+            showStatus();
+            return;
+        }
+        if (resolved === "on") {
+            const state = loadTelemetryState();
+            state.enabled = true;
+            writeTelemetryState(state);
+            console.log(chalk.green("Telemetry enabled."));
+            console.log(chalk.dim(`Install ID: ${state.installId}`));
+            return;
+        }
+        if (resolved === "off") {
+            // Do not beacon on opt-out: an explicit "turn it off" must not send data.
+            const state = loadTelemetryState();
+            state.enabled = false;
+            writeTelemetryState(state);
+            console.log(chalk.yellow("Telemetry disabled. No data will be sent."));
+            console.log(chalk.dim("Re-enable anytime with: cc-router telemetry on"));
+            return;
+        }
+        console.error(chalk.red(`Unknown action "${resolved}". Use: on, off, status`));
+        process.exitCode = 1;
+    });
+}
+function showStatus() {
+    const state = loadTelemetryState();
+    const envDisabled = process.env["DO_NOT_TRACK"] === "1" || process.env["CC_ROUTER_TELEMETRY"] === "0";
+    console.log(chalk.bold("Telemetry"));
+    console.log();
+    if (envDisabled) {
+        console.log(`  Status:     ${chalk.yellow("disabled")} (by environment variable)`);
+    }
+    else if (state.enabled) {
+        console.log(`  Status:     ${chalk.green("enabled")}`);
+    }
+    else {
+        console.log(`  Status:     ${chalk.yellow("disabled")}`);
+    }
+    console.log(`  Active:     ${isTelemetryEnabled() ? chalk.green("yes") : chalk.yellow("no")}`);
+    console.log(`  Install ID: ${chalk.dim(state.installId)}`);
+    console.log(`  Since:      ${chalk.dim(state.firstRunAt)}`);
+    console.log();
+    console.log(chalk.dim("  What we send:  version, OS, locale, lifecycle events (start, heartbeat)"));
+    console.log(chalk.dim("  What we DON'T: IPs, tokens, prompts, request content, account names"));
+    console.log(chalk.dim("  Source code:   src/utils/telemetry.ts"));
+    console.log();
+    console.log(chalk.dim("  Disable:  cc-router telemetry off"));
+    console.log(chalk.dim("  Or set:   DO_NOT_TRACK=1  |  CC_ROUTER_TELEMETRY=0"));
+}