fullcourtdefense-cli 1.7.25 → 1.7.26

package/dist/commands/mcpGateway.js

@@ -768,10 +768,23 @@ function buildGatewayCommandArgs(gatewayConfig, downstreamCommand, downstreamArg
         '--fail-closed', String(gatewayConfig.failClosed),
     ];
     if (!options.omitSavedCredentials) {
-        commandArgs.push('--shield-id', gatewayConfig.shieldId);
-        if (gatewayConfig.shieldKey && options.includeShieldKey !== false) {
+        // INVARIANT: a shield ID and its shield key must travel together. Writing
+        // the shield ID into the config WITHOUT its key lets the runtime pair that
+        // ID with a DIFFERENT shield's key resolved from ~/.fullcourtdefense.yml.
+        // The backend then returns 401 (SHIELD_KEY_REQUIRED) and, under
+        // --fail-closed, EVERY tool call is blocked — even a read-only lookup.
+        // This was the Claude Desktop "stale shield" bug: the config pinned an old
+        // shield ID while the machine had been re-enrolled to a different shield.
+        const persistKey = !!gatewayConfig.shieldKey && options.includeShieldKey !== false;
+        if (persistKey) {
+            // Self-contained config: ID + matching key baked in as a pair.
+            commandArgs.push('--shield-id', gatewayConfig.shieldId);
             commandArgs.push('--shield-key', gatewayConfig.shieldKey);
         }
+        // When the key is intentionally kept out of the config
+        // (includeShieldKey === false), we also OMIT the shield ID so the runtime
+        // resolves BOTH as a matched pair from ~/.fullcourtdefense.yml — the same
+        // proven path the Cursor hooks use. Never write the ID alone.
         if (gatewayConfig.apiUrl)
             commandArgs.push('--api-url', gatewayConfig.apiUrl);
     }
@@ -1055,7 +1068,7 @@ const CLIENT_KEY_TO_AGENT = {
     windsurf: 'windsurf',
     vscode: 'vscode',
 };
-function newWrapStats() { return { wrapped: [], skippedManaged: [], skippedRemote: [] }; }
+function newWrapStats() { return { wrapped: [], healed: [], skippedManaged: [], skippedRemote: [] }; }
 /** True when an MCP server entry already runs through the AgentGuard gateway. */
 function isGatewayWrappedEntry(entry) {
     if (!entry || typeof entry !== 'object')
@@ -1063,6 +1076,20 @@ function isGatewayWrappedEntry(entry) {
     const args = Array.isArray(entry.args) ? entry.args.map(String) : [];
     return args.includes('mcp-gateway');
 }
+/**
+ * A wrapped entry is STALE/broken when it pins a `--shield-id` but carries no
+ * matching `--shield-key`. At runtime the gateway then pairs that shield ID with
+ * whatever key ~/.fullcourtdefense.yml holds — if the machine was re-enrolled to
+ * a different shield, the pair mismatches, the backend returns 401, and
+ * --fail-closed blocks EVERY tool call. Entries written by the fixed installer
+ * carry either BOTH (self-contained) or NEITHER (resolved as a matched pair from
+ * the yml), so `id without key` uniquely identifies the buggy old wrapping that
+ * must be re-wrapped in place.
+ */
+function wrappedEntryNeedsHeal(entry) {
+    const args = Array.isArray(entry?.args) ? entry.args.map(String) : [];
+    return args.includes('--shield-id') && !args.includes('--shield-key');
+}
 /** Recover the original downstream command+args from a wrapped entry's args. */
 function extractWrappedDownstream(entry) {
     const args = Array.isArray(entry?.args) ? entry.args.map(String) : [];
@@ -1135,6 +1162,21 @@ function wrapJsonConfigFile(file, gatewayConfig, agentClient, dryRun) {
             if (!entry || typeof entry !== 'object')
                 continue;
             if (name === MANAGED_SERVER_NAME || isGatewayWrappedEntry(entry)) {
+                // Already wrapped — but re-heal in place if it carries the stale
+                // shield-id-without-key that caused the fail-closed 401 block. Recover
+                // the original downstream server from the existing wrapper args and
+                // rewrap with the fixed matched-pair credential handling.
+                if (isGatewayWrappedEntry(entry) && wrappedEntryNeedsHeal(entry)) {
+                    const downstream = extractWrappedDownstream(entry);
+                    if (downstream) {
+                        const perServer = { ...gatewayConfig, agentClient, agentName: perServerAgentName(gatewayConfig.developerName, agentClient, name) };
+                        entry.command = nodeExe;
+                        entry.args = buildGatewayCommandArgs(perServer, downstream.command, downstream.args, INSTALL_GATEWAY_ARGS);
+                        stats.healed.push(name);
+                        changed = true;
+                        continue;
+                    }
+                }
                 stats.skippedManaged.push(name);
                 continue;
             }
@@ -1370,6 +1412,7 @@ async function protectAllCommand(args, config) {
     }
     console.log(`\x1b[2mAuto-searching every known MCP client on this machine — ${files.length} config file(s) found.\x1b[0m\n`);
     let totalWrapped = 0;
+    let totalHealed = 0;
     let totalManaged = 0;
     let totalRemote = 0;
     let totalEmpty = 0;
@@ -1386,12 +1429,15 @@ async function protectAllCommand(args, config) {
             console.log('  \x1b[33m• could not parse — left unchanged\x1b[0m\n');
             continue;
         }
-        const found = stats.wrapped.length + stats.skippedManaged.length + stats.skippedRemote.length;
+        const found = stats.wrapped.length + stats.healed.length + stats.skippedManaged.length + stats.skippedRemote.length;
         totalWrapped += stats.wrapped.length;
+        totalHealed += stats.healed.length;
         totalManaged += stats.skippedManaged.length;
         totalRemote += stats.skippedRemote.length;
         if (stats.wrapped.length)
             console.log(`  \x1b[32m✓ ${dryRun ? 'would update' : 'updated'} → now protected:\x1b[0m ${stats.wrapped.join(', ')}`);
+        if (stats.healed.length)
+            console.log(`  \x1b[32m✓ ${dryRun ? 'would repair' : 'repaired'} stale shield credentials:\x1b[0m ${stats.healed.join(', ')}`);
         if (stats.skippedManaged.length)
             console.log(`  \x1b[2m• already protected (unchanged):\x1b[0m ${stats.skippedManaged.join(', ')}`);
         if (stats.skippedRemote.length)
@@ -1409,9 +1455,9 @@ async function protectAllCommand(args, config) {
         console.log(`\x1b[2mNot configured (no config file found): ${notConfigured.map(c => CLIENT_LABELS[c]).join(', ')}\x1b[0m\n`);
     }
     console.log('\x1b[1mSummary\x1b[0m');
-    console.log(`  ${dryRun ? 'would update' : 'updated'}: ${totalWrapped}   already protected: ${totalManaged}   no servers: ${totalEmpty}   skipped remote: ${totalRemote}`);
+    console.log(`  ${dryRun ? 'would update' : 'updated'}: ${totalWrapped}   ${dryRun ? 'would repair' : 'repaired'}: ${totalHealed}   already protected: ${totalManaged}   no servers: ${totalEmpty}   skipped remote: ${totalRemote}`);
     console.log(`  Each protected server enforces your org Action Policies (allow / block / wait-for-human-approval) on its tool calls.`);
-    if (!dryRun && totalWrapped > 0) {
+    if (!dryRun && (totalWrapped > 0 || totalHealed > 0)) {
         console.log('  Backups saved next to each edited file (*.fcd-backup-*).');
         (0, restartNotice_1.printRestartNotice)(allowedClientKeys ? [...allowedClientKeys].join(', ') : undefined);
     }

package/dist/index.js

@@ -104,238 +104,238 @@ function parseArgs(argv) {
     return { command, flags };
 }
 function printHelp() {
-    console.log(`
-  \x1b[1m\x1b[36mFullCourtDefense CLI\x1b[0m v${VERSION}
-  Security scanning for AI agents from your terminal.
-
-  \x1b[1mUsage:\x1b[0m
-    fullcourtdefense <command> [options]
-
-  \x1b[1mCommands:\x1b[0m
-    help        Show this onboarding guide and command reference.
-    doctor      First step. Checks outbound HTTPS access to FullCourtDefense.
-    login       Enrolls this machine with a fleet enrollment token and saves
-                per-machine Shield credentials to ~/.fullcourtdefense.yml.
-    configure   Legacy/manual setup: saves org API key, Organization ID,
-                Shield ID, and Shield key to ~/.fullcourtdefense.yml.
-    setup       Same as configure — manual fallback when not using fleet login.
-    install-all One-click: protect existing MCP servers in every AI client and
-                install available runtime hooks for built-in actions. No folder path
-                or --mcp-command needed. Use --hooks false to skip runtime hooks.
-    install     Alias for install-all.
-    scan        Runs the scan. Use --local for inside-organization scans.
-    discover    Finds MCP servers, local secrets, agent rules/skills, and machine
-                blast radius on this laptop. Use --surface all --upload for AI Fleet.
-                Use --schedule logon to upload inventory/posture at machine login.
-    agent-ci    CI/CD gate for agents and tools only. Fails builds on risky MCP,
-                agent instruction, gateway, policy, or secret drift. Not a bot scan.
-    install-cursor-hook
-                Installs a Cursor hook so EVERY agent action on this machine is
-                checked against your org's Action Policies — in any repo/folder.
-                Prompts are scanned by your Shield; shell/MCP/file/read actions
-                are allowed, blocked, or paused for human approval per policy.
-    uninstall-cursor-hook
-                Removes the FullCourtDefense Cursor hook entries.
-    install-claude-hook
-                Installs Claude-format hooks in ~/.claude/settings.json — ONE file
-                enforces Action Policies + Local Safety rules in Claude Code,
-                VS Code Copilot agent mode, and GitHub Copilot CLI.
-    uninstall-claude-hook
-                Removes the FullCourtDefense Claude-format hook entries.
-    protect-all Auto-detect EVERY MCP server already configured in EVERY client
-                (Cursor, Claude Code/Desktop, Codex, Gemini, Windsurf, VS Code)
-                and wrap each through the Shield proxy — no --mcp-command needed.
-                Enforces your org Action Policies on every tool. --dry-run to preview.
-                Per-tool: --clients cursor (or claude-code, claude-desktop, codex,
-                gemini-cli, windsurf, vscode; comma-separated). Default: all tools.
-    unprotect-all
-                Reverse protect-all: restore every server to its original command.
-                Also supports --clients to target one tool, and --dry-run.
-    auto-protect
-                Self-healing: schedule protect-all to re-run automatically so any
-                server that loses the proxy is re-wrapped. --interval-minutes 60
-                (default) or --on-logon true. --uninstall true / --status true.
-    install-mcp-gateway
-                Install MCP gateway into selected clients (--clients all for every tool).
-    install-cursor-mcp-gateway
-                Cursor only — adds gateway to mcp.json.
-    install-claude-code-mcp-gateway
-                Claude Code only — uses claude mcp add or .mcp.json.
-    install-claude-desktop-mcp-gateway
-                Claude Desktop only.
-    install-codex-mcp-gateway
-                Codex only — writes ~/.codex/config.toml.
-    install-gemini-mcp-gateway
-                Gemini CLI only — writes settings.json mcpServers.
-    install-windsurf-mcp-gateway
-                Windsurf only.
-    install-vscode-mcp-gateway
-                VS Code only — .vscode/mcp.json or user settings.
-    mcp-gateway
-                Runs a local MCP gateway that checks AgentGuard runtime/action
-                policies before forwarding tool calls to a real MCP server.
-    hook        Internal: invoked by Cursor per agent event (reads stdin JSON,
-                returns an allow/deny verdict). Not run by hand.
-    credits     Shows hosted scan credits for CI/CD API-key scans.
-    init        Creates a starter .fullcourtdefense.yml config file.
-
-  \x1b[1mNew User Process:\x1b[0m
-    1. In the web app, an org admin creates a fleet enrollment token:
-       AI Fleet → Settings → Fleet enrollment token.
-
-    2. Check outbound connectivity from the customer machine:
-       fullcourtdefense doctor
-       This confirms the machine can reach https://api.fullcourtdefense.ai over HTTPS.
-
-    3. Enroll this developer machine (one time):
-       fullcourtdefense login --token <fleet-enrollment-token>
-       Or set FCD_ENROLL_TOKEN and run: fullcourtdefense login
-       Saves per-machine Shield credentials to ~/.fullcourtdefense.yml —
-       install, discover --upload, scan, gateway, and hooks use it automatically.
-
-    4. One-click protect every AI client on this machine with Action Policies:
-       fullcourtdefense install-all
-       Verify installs:
-       fullcourtdefense protect-all --dry-run true
-       Or install one client: fullcourtdefense install-cursor-mcp-gateway ...
-
-    5. Run a guided local scan:
-       fullcourtdefense scan --local
-       The CLI asks whether to scan endpoint, mcp, or rag.
-       To open the localhost web scan UI first:
-       fullcourtdefense scan --local --open-ui
-
-    6. Review results:
-       Use --format summary for CI, --format table for terminal view,
-       --format report for evidence, --format full-report for every row,
-       or --format json for raw output.
-       With a Shield key configured, reports are saved to the web Reports page
-       and the browser opens to the saved report. Use --no-open to suppress.
-
-  \x1b[1mLocal Destinations:\x1b[0m
-    endpoint    Internal HTTP URL, for example http://agent.local/chat.
-                The CLI sends attack prompts to this endpoint and scans responses.
-
-    mcp         Either stdio command + args, or an already-running HTTP/SSE MCP URL.
-                Stdio example: node ./mcp-server.js
-                HTTP/HTTPS examples: http://mcp.internal/mcp or https://internal.company.com/mcp
-                Legacy SSE example: https://internal.company.com/sse
-                Secured HTTP MCP supports bearer, basic, and API-key auth.
-
-    rag         File/directory path or live RAG HTTP endpoint.
-                Use --rag-path for local documents, or --rag-url for a RAG service.
-
-  \x1b[1mRecommended Commands:\x1b[0m
-    fullcourtdefense doctor
-    fullcourtdefense configure
-    fullcourtdefense agent-ci --fail-on high --require-gateway --format summary
-    fullcourtdefense agent-ci --fail-on high --format sarif --upload
-    fullcourtdefense scan --local
-    fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
-    fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type bearer --mcp-token TOKEN --mcp-tool all --mode full --format report
-    fullcourtdefense scan --local --type rag --rag-path ./docs --format report
-    fullcourtdefense scan --local --type rag --rag-url http://rag.internal/chat --method POST --request-format custom --input-field message --output-field answer --mode full --format report
-    fullcourtdefense scan --local --type endpoint --endpoint http://agent.local/chat --method POST --mode full --format report
-
-  \x1b[1mScan Options:\x1b[0m
-    --local                 Run scan from this machine, inside your network
-    --open-ui               Open localhost browser scan UI with all options
-    --type <type>           Local scan type: endpoint, mcp, rag
-    --api-key <key>         API key (or set FULLCOURTDEFENSE_API_KEY env var)
-    --api-url <url>         API base URL (default: https://api.fullcourtdefense.ai)
-    --endpoint <url>        Agent API endpoint to scan
-    --mcp-url <url>         Already-running HTTP MCP server URL
-    --mcp-transport <t>     MCP transport: stdio, http, or sse
-    --mcp-command <cmd>     MCP server command, for example node or npx.cmd
-    --mcp-args <args>       MCP server args/path, for example ./server.js
-    --mcp-tool <tool>       MCP tool to test, or all
-    --server-name <name>    MCP gateway server name for client installers
-    --clients <list>        Gateway clients: all, auto, cursor, claude-code,
-                            claude-desktop, codex, gemini-cli, windsurf, vscode
-    --developer-name <name> Runtime identity for user-scoped policies (auto-detected if omitted)
-    --agent-name <name>     Runtime agent name (auto-generated from identity + client if omitted)
-    --scope <scope>         Claude Code MCP scope: local, project, or user
-    --claude-code-scope <s> Claude Code scope for install-mcp-gateway
-    --cursor-project <bool> Cursor project config for install-mcp-gateway
-    --config-path <path>    Claude Desktop config override path
-    --mcp-auth-type <type>  HTTP MCP auth: none, bearer, basic, api-key
-    --mcp-token <token>     HTTP MCP bearer token
-    --mcp-username <user>   HTTP MCP basic username
-    --mcp-password <pass>   HTTP MCP basic password
-    --mcp-api-key-header <h> HTTP MCP API-key header name
-    --mcp-api-key <key>     HTTP MCP API key value
-    --rag-path <path>       RAG file or directory to scan
-    --rag-url <url>         Live RAG HTTP endpoint to scan
-    --shield-id <id>        Shield ID for local outbound Shield verdicts
-    --shield-key <key>      Optional Shield key for locked Shields
-    --fail-on <severity>    agent-ci fail threshold: critical, high, medium, low
-    --require-gateway       agent-ci requires risky MCP servers to use FCD gateway
-    --require-approval-for  agent-ci risky controls list, e.g. payment,delete,shell,secrets
-    --require-upload        agent-ci fails if evidence cannot upload to AgentGuard UI
-    --changed-only          agent-ci limits findings to changed files
-    --changed-files <path>  file or comma/newline list of changed files for agent-ci
-    --method <GET|POST>     Local endpoint method
-    --request-format <fmt>  Local endpoint request format: custom or openai
-    --auth-type <type>      none, bearer, basic, api-key
-    --description <text>    Agent description
-    --system-prompt <text>  System prompt (text or path to file)
-    --mode <sync|async>     Hosted mode, or local mode: quick, full, targeted, deep
-    --categories <list>     Comma-separated attack categories
-    --attack-count <n>      Number of attacks to run
-    --surface <list>        Discover surfaces: mcp, secrets, agent-files, posture, all
-    --fail-threshold <n>    Exit code 1 if score below n (default: 0)
-    --format <fmt>          Output: table, json, summary, report, full-report (default: table)
-    --open                  Open browser scan UI and saved local scan report
-    --open-ui               Open only the browser scan UI before local execution
-    --no-open               Do not open the browser during/after local scans
-    --webhook-format <fmt>  Hosted webhook format, or legacy local request format
-    --config <path>         Path to .fullcourtdefense.yml config file
-
-  \x1b[1mExamples:\x1b[0m
-    $ fullcourtdefense scan --endpoint https://my-bot.com/chat --description "Support bot"
-    $ fullcourtdefense help
-    $ fullcourtdefense scan --local
-    $ fullcourtdefense scan --local --open-ui
-    $ fullcourtdefense scan --local --type endpoint --mode full --endpoint http://internal-agent/chat
-    $ fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full
-    $ fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp
-    $ fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full
-    $ fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url https://internal.company.com/sse --mcp-tool all --mode full
-    $ fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
-    $ fullcourtdefense discover
-    $ fullcourtdefense discover --surface mcp
-    $ fullcourtdefense discover --surface all --upload
-    $ fullcourtdefense discover --surface secrets
-    $ fullcourtdefense discover --surface agent-files
-    $ fullcourtdefense discover --deep --upload --silent --user-email you@company.com
-    $ fullcourtdefense discover --type mcp --json
-    $ fullcourtdefense install-cursor-hook
-    $ fullcourtdefense install-cursor-hook --shadow true        # monitor only
-    $ fullcourtdefense install-cursor-hook --events prompt,shell,mcp,file
-    $ fullcourtdefense install-cursor-hook --project true       # this repo only
-    $ fullcourtdefense uninstall-cursor-hook
-    $ fullcourtdefense install-claude-hook                       # Claude Code + VS Code + Copilot CLI
-    $ fullcourtdefense install-claude-hook --events tools,prompt # also scan prompts
-    $ fullcourtdefense uninstall-claude-hook
-    $ fullcourtdefense install-mcp-gateway --clients auto --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense install-mcp-gateway --clients all --mcp-command npm --mcp-args "run mcp" --upload
-    $ fullcourtdefense install-cursor-mcp-gateway --project true --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense install-claude-code-mcp-gateway --scope local --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense install-claude-code-mcp-gateway --scope project --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense install-claude-desktop-mcp-gateway --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense mcp-gateway --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense login --token <fleet-enrollment-token>
-    $ fullcourtdefense install-all
-    $ fullcourtdefense install-all --auto-protect true --upload
-    $ fullcourtdefense discover --surface all --upload --schedule logon
-    $ fullcourtdefense install-mcp-gateway --clients cursor,codex --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense install-codex-mcp-gateway --mcp-command npm --mcp-args "run mcp"
-    $ fullcourtdefense scan --system-prompt ./prompts/system.md --fail-threshold 80
-    $ fullcourtdefense scan --config .fullcourtdefense.yml --format json
-    $ fullcourtdefense credits
-    $ fullcourtdefense init
-
-  \x1b[2mDocs: https://fullcourtdefense.ai/docs/cli\x1b[0m
+    console.log(`
+  \x1b[1m\x1b[36mFullCourtDefense CLI\x1b[0m v${VERSION}
+  Security scanning for AI agents from your terminal.
+
+  \x1b[1mUsage:\x1b[0m
+    fullcourtdefense <command> [options]
+
+  \x1b[1mCommands:\x1b[0m
+    help        Show this onboarding guide and command reference.
+    doctor      First step. Checks outbound HTTPS access to FullCourtDefense.
+    login       Enrolls this machine with a fleet enrollment token and saves
+                per-machine Shield credentials to ~/.fullcourtdefense.yml.
+    configure   Legacy/manual setup: saves org API key, Organization ID,
+                Shield ID, and Shield key to ~/.fullcourtdefense.yml.
+    setup       Same as configure — manual fallback when not using fleet login.
+    install-all One-click: protect existing MCP servers in every AI client and
+                install available runtime hooks for built-in actions. No folder path
+                or --mcp-command needed. Use --hooks false to skip runtime hooks.
+    install     Alias for install-all.
+    scan        Runs the scan. Use --local for inside-organization scans.
+    discover    Finds MCP servers, local secrets, agent rules/skills, and machine
+                blast radius on this laptop. Use --surface all --upload for AI Fleet.
+                Use --schedule logon to upload inventory/posture at machine login.
+    agent-ci    CI/CD gate for agents and tools only. Fails builds on risky MCP,
+                agent instruction, gateway, policy, or secret drift. Not a bot scan.
+    install-cursor-hook
+                Installs a Cursor hook so EVERY agent action on this machine is
+                checked against your org's Action Policies — in any repo/folder.
+                Prompts are scanned by your Shield; shell/MCP/file/read actions
+                are allowed, blocked, or paused for human approval per policy.
+    uninstall-cursor-hook
+                Removes the FullCourtDefense Cursor hook entries.
+    install-claude-hook
+                Installs Claude-format hooks in ~/.claude/settings.json — ONE file
+                enforces Action Policies + Local Safety rules in Claude Code,
+                VS Code Copilot agent mode, and GitHub Copilot CLI.
+    uninstall-claude-hook
+                Removes the FullCourtDefense Claude-format hook entries.
+    protect-all Auto-detect EVERY MCP server already configured in EVERY client
+                (Cursor, Claude Code/Desktop, Codex, Gemini, Windsurf, VS Code)
+                and wrap each through the Shield proxy — no --mcp-command needed.
+                Enforces your org Action Policies on every tool. --dry-run to preview.
+                Per-tool: --clients cursor (or claude-code, claude-desktop, codex,
+                gemini-cli, windsurf, vscode; comma-separated). Default: all tools.
+    unprotect-all
+                Reverse protect-all: restore every server to its original command.
+                Also supports --clients to target one tool, and --dry-run.
+    auto-protect
+                Self-healing: schedule protect-all to re-run automatically so any
+                server that loses the proxy is re-wrapped. --interval-minutes 60
+                (default) or --on-logon true. --uninstall true / --status true.
+    install-mcp-gateway
+                Install MCP gateway into selected clients (--clients all for every tool).
+    install-cursor-mcp-gateway
+                Cursor only — adds gateway to mcp.json.
+    install-claude-code-mcp-gateway
+                Claude Code only — uses claude mcp add or .mcp.json.
+    install-claude-desktop-mcp-gateway
+                Claude Desktop only.
+    install-codex-mcp-gateway
+                Codex only — writes ~/.codex/config.toml.
+    install-gemini-mcp-gateway
+                Gemini CLI only — writes settings.json mcpServers.
+    install-windsurf-mcp-gateway
+                Windsurf only.
+    install-vscode-mcp-gateway
+                VS Code only — .vscode/mcp.json or user settings.
+    mcp-gateway
+                Runs a local MCP gateway that checks AgentGuard runtime/action
+                policies before forwarding tool calls to a real MCP server.
+    hook        Internal: invoked by Cursor per agent event (reads stdin JSON,
+                returns an allow/deny verdict). Not run by hand.
+    credits     Shows hosted scan credits for CI/CD API-key scans.
+    init        Creates a starter .fullcourtdefense.yml config file.
+
+  \x1b[1mNew User Process:\x1b[0m
+    1. In the web app, an org admin creates a fleet enrollment token:
+       AI Fleet → Settings → Fleet enrollment token.
+
+    2. Check outbound connectivity from the customer machine:
+       fullcourtdefense doctor
+       This confirms the machine can reach https://api.fullcourtdefense.ai over HTTPS.
+
+    3. Enroll this developer machine (one time):
+       fullcourtdefense login --token <fleet-enrollment-token>
+       Or set FCD_ENROLL_TOKEN and run: fullcourtdefense login
+       Saves per-machine Shield credentials to ~/.fullcourtdefense.yml —
+       install, discover --upload, scan, gateway, and hooks use it automatically.
+
+    4. One-click protect every AI client on this machine with Action Policies:
+       fullcourtdefense install-all
+       Verify installs:
+       fullcourtdefense protect-all --dry-run true
+       Or install one client: fullcourtdefense install-cursor-mcp-gateway ...
+
+    5. Run a guided local scan:
+       fullcourtdefense scan --local
+       The CLI asks whether to scan endpoint, mcp, or rag.
+       To open the localhost web scan UI first:
+       fullcourtdefense scan --local --open-ui
+
+    6. Review results:
+       Use --format summary for CI, --format table for terminal view,
+       --format report for evidence, --format full-report for every row,
+       or --format json for raw output.
+       With a Shield key configured, reports are saved to the web Reports page
+       and the browser opens to the saved report. Use --no-open to suppress.
+
+  \x1b[1mLocal Destinations:\x1b[0m
+    endpoint    Internal HTTP URL, for example http://agent.local/chat.
+                The CLI sends attack prompts to this endpoint and scans responses.
+
+    mcp         Either stdio command + args, or an already-running HTTP/SSE MCP URL.
+                Stdio example: node ./mcp-server.js
+                HTTP/HTTPS examples: http://mcp.internal/mcp or https://internal.company.com/mcp
+                Legacy SSE example: https://internal.company.com/sse
+                Secured HTTP MCP supports bearer, basic, and API-key auth.
+
+    rag         File/directory path or live RAG HTTP endpoint.
+                Use --rag-path for local documents, or --rag-url for a RAG service.
+
+  \x1b[1mRecommended Commands:\x1b[0m
+    fullcourtdefense doctor
+    fullcourtdefense configure
+    fullcourtdefense agent-ci --fail-on high --require-gateway --format summary
+    fullcourtdefense agent-ci --fail-on high --format sarif --upload
+    fullcourtdefense scan --local
+    fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
+    fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-auth-type bearer --mcp-token TOKEN --mcp-tool all --mode full --format report
+    fullcourtdefense scan --local --type rag --rag-path ./docs --format report
+    fullcourtdefense scan --local --type rag --rag-url http://rag.internal/chat --method POST --request-format custom --input-field message --output-field answer --mode full --format report
+    fullcourtdefense scan --local --type endpoint --endpoint http://agent.local/chat --method POST --mode full --format report
+
+  \x1b[1mScan Options:\x1b[0m
+    --local                 Run scan from this machine, inside your network
+    --open-ui               Open localhost browser scan UI with all options
+    --type <type>           Local scan type: endpoint, mcp, rag
+    --api-key <key>         API key (or set FULLCOURTDEFENSE_API_KEY env var)
+    --api-url <url>         API base URL (default: https://api.fullcourtdefense.ai)
+    --endpoint <url>        Agent API endpoint to scan
+    --mcp-url <url>         Already-running HTTP MCP server URL
+    --mcp-transport <t>     MCP transport: stdio, http, or sse
+    --mcp-command <cmd>     MCP server command, for example node or npx.cmd
+    --mcp-args <args>       MCP server args/path, for example ./server.js
+    --mcp-tool <tool>       MCP tool to test, or all
+    --server-name <name>    MCP gateway server name for client installers
+    --clients <list>        Gateway clients: all, auto, cursor, claude-code,
+                            claude-desktop, codex, gemini-cli, windsurf, vscode
+    --developer-name <name> Runtime identity for user-scoped policies (auto-detected if omitted)
+    --agent-name <name>     Runtime agent name (auto-generated from identity + client if omitted)
+    --scope <scope>         Claude Code MCP scope: local, project, or user
+    --claude-code-scope <s> Claude Code scope for install-mcp-gateway
+    --cursor-project <bool> Cursor project config for install-mcp-gateway
+    --config-path <path>    Claude Desktop config override path
+    --mcp-auth-type <type>  HTTP MCP auth: none, bearer, basic, api-key
+    --mcp-token <token>     HTTP MCP bearer token
+    --mcp-username <user>   HTTP MCP basic username
+    --mcp-password <pass>   HTTP MCP basic password
+    --mcp-api-key-header <h> HTTP MCP API-key header name
+    --mcp-api-key <key>     HTTP MCP API key value
+    --rag-path <path>       RAG file or directory to scan
+    --rag-url <url>         Live RAG HTTP endpoint to scan
+    --shield-id <id>        Shield ID for local outbound Shield verdicts
+    --shield-key <key>      Optional Shield key for locked Shields
+    --fail-on <severity>    agent-ci fail threshold: critical, high, medium, low
+    --require-gateway       agent-ci requires risky MCP servers to use FCD gateway
+    --require-approval-for  agent-ci risky controls list, e.g. payment,delete,shell,secrets
+    --require-upload        agent-ci fails if evidence cannot upload to AgentGuard UI
+    --changed-only          agent-ci limits findings to changed files
+    --changed-files <path>  file or comma/newline list of changed files for agent-ci
+    --method <GET|POST>     Local endpoint method
+    --request-format <fmt>  Local endpoint request format: custom or openai
+    --auth-type <type>      none, bearer, basic, api-key
+    --description <text>    Agent description
+    --system-prompt <text>  System prompt (text or path to file)
+    --mode <sync|async>     Hosted mode, or local mode: quick, full, targeted, deep
+    --categories <list>     Comma-separated attack categories
+    --attack-count <n>      Number of attacks to run
+    --surface <list>        Discover surfaces: mcp, secrets, agent-files, posture, all
+    --fail-threshold <n>    Exit code 1 if score below n (default: 0)
+    --format <fmt>          Output: table, json, summary, report, full-report (default: table)
+    --open                  Open browser scan UI and saved local scan report
+    --open-ui               Open only the browser scan UI before local execution
+    --no-open               Do not open the browser during/after local scans
+    --webhook-format <fmt>  Hosted webhook format, or legacy local request format
+    --config <path>         Path to .fullcourtdefense.yml config file
+
+  \x1b[1mExamples:\x1b[0m
+    $ fullcourtdefense scan --endpoint https://my-bot.com/chat --description "Support bot"
+    $ fullcourtdefense help
+    $ fullcourtdefense scan --local
+    $ fullcourtdefense scan --local --open-ui
+    $ fullcourtdefense scan --local --type endpoint --mode full --endpoint http://internal-agent/chat
+    $ fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full
+    $ fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp
+    $ fullcourtdefense scan --local --type mcp --mcp-url https://internal.company.com/mcp --mcp-tool all --mode full
+    $ fullcourtdefense scan --local --type mcp --mcp-transport sse --mcp-url https://internal.company.com/sse --mcp-tool all --mode full
+    $ fullcourtdefense scan --local --type mcp --mcp-command node --mcp-args ./server.js --mcp-tool all --mode full --format report
+    $ fullcourtdefense discover
+    $ fullcourtdefense discover --surface mcp
+    $ fullcourtdefense discover --surface all --upload
+    $ fullcourtdefense discover --surface secrets
+    $ fullcourtdefense discover --surface agent-files
+    $ fullcourtdefense discover --deep --upload --silent --user-email you@company.com
+    $ fullcourtdefense discover --type mcp --json
+    $ fullcourtdefense install-cursor-hook
+    $ fullcourtdefense install-cursor-hook --shadow true        # monitor only
+    $ fullcourtdefense install-cursor-hook --events prompt,shell,mcp,file
+    $ fullcourtdefense install-cursor-hook --project true       # this repo only
+    $ fullcourtdefense uninstall-cursor-hook
+    $ fullcourtdefense install-claude-hook                       # Claude Code + VS Code + Copilot CLI
+    $ fullcourtdefense install-claude-hook --events tools,prompt # also scan prompts
+    $ fullcourtdefense uninstall-claude-hook
+    $ fullcourtdefense install-mcp-gateway --clients auto --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense install-mcp-gateway --clients all --mcp-command npm --mcp-args "run mcp" --upload
+    $ fullcourtdefense install-cursor-mcp-gateway --project true --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense install-claude-code-mcp-gateway --scope local --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense install-claude-code-mcp-gateway --scope project --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense install-claude-desktop-mcp-gateway --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense mcp-gateway --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense login --token <fleet-enrollment-token>
+    $ fullcourtdefense install-all
+    $ fullcourtdefense install-all --auto-protect true --upload
+    $ fullcourtdefense discover --surface all --upload --schedule logon
+    $ fullcourtdefense install-mcp-gateway --clients cursor,codex --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense install-codex-mcp-gateway --mcp-command npm --mcp-args "run mcp"
+    $ fullcourtdefense scan --system-prompt ./prompts/system.md --fail-threshold 80
+    $ fullcourtdefense scan --config .fullcourtdefense.yml --format json
+    $ fullcourtdefense credits
+    $ fullcourtdefense init
+
+  \x1b[2mDocs: https://fullcourtdefense.ai/docs/cli\x1b[0m
 `);
 }
 async function main() {

package/dist/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.7.25"
+  "version": "1.7.26"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullcourtdefense-cli",
-  "version": "1.7.25",
+  "version": "1.7.26",
   "description": "Full Court Defense CLI — security scanning for AI agents from your terminal",
   "main": "dist/index.js",
   "bin": {