unbound-cli 1.3.2 → 1.5.0

package/README.md

@@ -195,17 +195,25 @@ unbound policy security create --name "429 Fallback" --sub-type error-code-routi
 
 Tool policy examples:
 
+> **BREAKING CHANGE in 1.5.0:** `create-terminal` and `create-mcp` now require either `--prompt` (AI-assisted creation) or an explicit `--no-ai` opt-out. Invocations with raw classification flags but no `--no-ai` exit with code 2 and a remediation message. Under Claude Code (`CLAUDECODE=1`), even `--no-ai` is rejected unless you also set `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` — this is intended for interactive humans, not agents.
+
 ```bash
+# AI-assisted (preferred): describe the policy in natural language.
+unbound policy tool create-terminal --prompt "block rm -rf"
+
+# AI-assisted MCP policy: describe the service and intent in natural language.
+unbound policy tool create-mcp --prompt "audit all Linear writes"
+
 # See what command families and MCP servers are available
 unbound policy tool families
 unbound policy tool mcp-servers
 
-# Block destructive shell commands
-unbound policy tool create-terminal --name "Block rm -rf" --command-family filesystem \
+# Flag-based fallback: block destructive shell commands explicitly
+unbound policy tool create-terminal --no-ai --name "Block rm -rf" --command-family filesystem \
     --field command='rm -rf*' --action BLOCK --custom-message "Destructive command blocked."
 
-# Audit Linear write operations via MCP
-unbound policy tool create-mcp --name "Audit Linear writes" --mcp-server Linear \
+# Flag-based MCP fallback: audit Linear write operations
+unbound policy tool create-mcp --no-ai --name "Audit Linear writes" --mcp-server Linear \
     --mcp-action-type write --action AUDIT
 
 # List, get, delete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/commands/policy.js

@@ -2,6 +2,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { formatDate, confirm, parseCommaSeparated } = require('../utils');
+const { assertSteering, helpBannerFor } = require('../lib/no-ai-guard');
 
 // ============================================================================
 // Constants and docs URLs
@@ -1429,27 +1430,38 @@ Subcommands:
   tool
     .command('create-terminal')
     .description('Create a TERMINAL_COMMAND policy: monitor or block shell commands run by AI coding tools.')
-    .requiredOption('--name <name>', 'Policy name (required)')
-    .requiredOption('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
+    .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --command-family/--field/--config. Compatible with --name/--description/--action overrides.')
+    .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
+    .option('--name <name>', 'Policy name (required unless --prompt is used)')
+    .option('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
     .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used.', (val, prev = []) => [...prev, val])
-    .requiredOption('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
+    .option('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
     .option('--description <text>', 'Human-readable description')
     .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
     .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
     .option('--disabled', 'Create the policy in disabled state')
     .option('--config <json>', 'Advanced: raw config JSON (skips --field builder)')
+    .option('--yes', 'Skip the confirmation prompt for --prompt flows (preview is still printed)')
     .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('before', helpBannerFor('create-terminal'))
     .addHelpText('after', `
 Examples:
-  $ unbound policy tool create-terminal --name "Block rm -rf" \\
+  # AI-assisted (preferred): describe the policy in natural language.
+  $ unbound policy tool create-terminal --prompt "block rm -rf"
+
+  # AI-assisted, with manual overrides for name and action:
+  $ unbound policy tool create-terminal --prompt "block rm -rf" \\
+      --name "Block recursive deletes" --action WARN
+
+  $ unbound policy tool create-terminal --no-ai --name "Block rm -rf" \\
       --command-family filesystem --field command='rm -rf*' --action BLOCK \\
       --custom-message "Destructive commands are blocked."
 
-  $ unbound policy tool create-terminal --name "Audit git push" \\
+  $ unbound policy tool create-terminal --no-ai --name "Audit git push" \\
       --command-family git --field command='git push*' --action AUDIT
 
   # Multiple --field are ANDed — this fires only on a push to main on origin:
-  $ unbound policy tool create-terminal --name "Block push to main on origin" \\
+  $ unbound policy tool create-terminal --no-ai --name "Block push to main on origin" \\
       --command-family git_action \\
       --field operation=push --field branch=main --field remote='*origin*' \\
       --action BLOCK --custom-message "Pushing to main on origin is blocked."
@@ -1460,6 +1472,84 @@ Learn more: ${DOCS_TOOL}
     .action(async (opts) => {
       try {
         requireLogin();
+        assertSteering(opts, { subcommandName: 'create-terminal' });
+
+        if (opts.prompt !== undefined) {
+          if (typeof opts.prompt !== 'string' || opts.prompt.trim() === '') {
+            output.error('--prompt cannot be empty.');
+            process.exitCode = 2;
+            return;
+          }
+          // --name, --description, --action are now allowed as AI overrides (merged in mergeAiAndFlags).
+          // --command-family, --field, --config remain mutex with --prompt because they're AI
+          // classification territory; if the AI gets them wrong, the right answer is re-prompting,
+          // not flag overrides (which would need catalog validation we don't want to add here).
+          const mutex = ['commandFamily', 'field', 'config'];
+          for (const k of mutex) {
+            if (opts[k]) {
+              throw new Error('Pass --prompt for AI-assist or the field flags for explicit creation, not both.');
+            }
+          }
+          if (opts.group) {
+            let formData;
+            try {
+              formData = await loadFormData();
+            } catch (err) {
+              const { routeBackendError } = require('../lib/policy-ai-assist');
+              const routed = routeBackendError(err);
+              output.error(routed.message);
+              process.exitCode = routed.exitCode;
+              return;
+            }
+            opts.scopeUserGroupIds = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+          }
+          const { runTerminalPromptCreate } = require('../lib/policy-ai-assist');
+          let result;
+          try {
+            result = await runTerminalPromptCreate(opts);
+          } catch (err) {
+            if (err.exitCode === 0) {
+              output.warn(err.message);
+              return;
+            }
+            output.error(err.message);
+            process.exitCode = err.exitCode || 1;
+            return;
+          }
+          if (!result.confirmed) {
+            output.warn('Aborted.');
+            return;
+          }
+          const body = result.body;
+          let data;
+          try {
+            data = await api.post('/api/v1/command-policies/', { body });
+          } catch (err) {
+            const { routeBackendError } = require('../lib/policy-ai-assist');
+            const routed = routeBackendError(err);
+            output.error(routed.message);
+            process.exitCode = routed.exitCode;
+            return;
+          }
+          if (opts.json) {
+            output.json(data);
+            return;
+          }
+          output.success(`Terminal policy${body.name ? ` "${body.name}"` : ''} created.`);
+          displayToolPolicy(unwrapToolPolicy(data));
+          return;
+        }
+
+        if (!opts.name) {
+          throw new Error('--name is required (or use --prompt for AI assist).');
+        }
+        if (!opts.commandFamily) {
+          throw new Error('--command-family is required (or use --prompt for AI assist).');
+        }
+        if (!opts.action) {
+          throw new Error('--action is required (or use --prompt for AI assist).');
+        }
+
         const action = normalizeAction(opts.action, TOOL_ACTIONS, '--action');
         if ((action === 'BLOCK' || action === 'WARN') && !opts.customMessage) {
           throw new Error('--custom-message is required when --action is BLOCK or WARN.');
@@ -1508,32 +1598,45 @@ Learn more: ${DOCS_TOOL}
         displayToolPolicy(unwrapToolPolicy(data));
       } catch (err) {
         output.error(err.message);
-        process.exitCode = 1;
+        process.exitCode = err.exitCode || 1;
       }
     });
 
   tool
     .command('create-mcp')
     .description('Create an MCP_TOOL policy: monitor or block MCP server tool calls.')
-    .requiredOption('--name <name>', 'Policy name (required)')
-    .requiredOption('--mcp-server <server>', 'MCP server name as shown by `policy tool mcp-servers` (e.g. linear, github). Resolved to its canonical group automatically.')
+    .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --mcp-server/--mcp-tool/--mcp-action-type/--config. Compatible with --name/--description/--action overrides.')
+    .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
+    .option('--name <name>', 'Policy name (required unless --prompt is used). Override AI suggestion when used with --prompt.')
+    .option('--mcp-server <server>', 'MCP server name as shown by `policy tool mcp-servers` (e.g. linear, github). Resolved to its canonical group automatically.')
     .option('--mcp-tool <tool>', 'Specific tool name on the MCP server (e.g. create_issue). Mutually exclusive with --mcp-action-type.')
     .option('--mcp-action-type <type>', `Match by tool action type: ${MCP_ACTION_TYPES.join(' | ')}. Mutually exclusive with --mcp-tool.`)
-    .requiredOption('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
-    .option('--description <text>', 'Human-readable description')
-    .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
+    .option('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}. Override AI suggestion when used with --prompt.`)
+    .option('--description <text>', 'Human-readable description. Override AI suggestion when used with --prompt.')
+    .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN. Override AI suggestion when used with --prompt.')
     .option('--group <names|ids>', 'Comma-separated user group names or IDs to scope this policy to')
     .option('--disabled', 'Create the policy in disabled state')
+    .option('--config <json>', 'Advanced: raw config JSON')
+    .option('--yes', 'Skip the confirmation prompt for --prompt flows (preview is still printed)')
     .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('before', helpBannerFor('create-mcp'))
     .addHelpText('after', `
 Examples:
-  Match a specific tool on a server:
-  $ unbound policy tool create-mcp --name "Block Linear writes" \\
+  # AI-assisted (preferred): describe the policy in natural language.
+  $ unbound policy tool create-mcp --prompt "audit all Linear writes"
+
+  # AI-assisted, with manual overrides for name and action:
+  $ unbound policy tool create-mcp --prompt "audit all Linear writes" \\
+      --name "Audit Linear writes" --action WARN \\
+      --custom-message "Linear writes are monitored."
+
+  # Match a specific tool on a server (flag-based fallback):
+  $ unbound policy tool create-mcp --no-ai --name "Block Linear writes" \\
       --mcp-server linear --mcp-tool create_issue --action BLOCK \\
       --custom-message "Issue creation is blocked. Contact admin."
 
-  Match all destructive tools on a server:
-  $ unbound policy tool create-mcp --name "Audit all destructive Slack" \\
+  # Match all destructive tools on a server:
+  $ unbound policy tool create-mcp --no-ai --name "Audit all destructive Slack" \\
       --mcp-server slack --mcp-action-type destructive --action AUDIT
 
 The server name is resolved to its canonical group automatically, so pass the
@@ -1545,6 +1648,80 @@ Learn more: ${DOCS_TOOL}
     .action(async (opts) => {
       try {
         requireLogin();
+        assertSteering(opts, { subcommandName: 'create-mcp' });
+
+        if (opts.prompt !== undefined) {
+          if (typeof opts.prompt !== 'string' || opts.prompt.trim() === '') {
+            output.error('--prompt cannot be empty.');
+            process.exitCode = 2;
+            return;
+          }
+          const mutex = ['mcpServer', 'mcpTool', 'mcpActionType', 'config'];
+          for (const k of mutex) {
+            if (opts[k]) {
+              throw new Error('Pass --prompt for AI-assist or the field flags for explicit creation, not both.');
+            }
+          }
+          if (opts.group) {
+            let formData;
+            try {
+              formData = await loadFormData();
+            } catch (err) {
+              const { routeBackendError } = require('../lib/policy-ai-assist');
+              const routed = routeBackendError(err);
+              output.error(routed.message);
+              process.exitCode = routed.exitCode;
+              return;
+            }
+            opts.scopeUserGroupIds = resolveByName(formData.user_groups || [], opts.group, { kind: 'user group' });
+          }
+          const { runMcpPromptCreate } = require('../lib/policy-ai-assist');
+          let result;
+          try {
+            result = await runMcpPromptCreate(opts);
+          } catch (err) {
+            if (err.exitCode === 0) {
+              output.warn(err.message);
+              return;
+            }
+            output.error(err.message);
+            process.exitCode = err.exitCode || 1;
+            return;
+          }
+          if (!result.confirmed) {
+            output.warn('Aborted.');
+            return;
+          }
+          const body = result.body;
+          let data;
+          try {
+            data = await api.post('/api/v1/command-policies/', { body });
+          } catch (err) {
+            const { routeBackendError } = require('../lib/policy-ai-assist');
+            const routed = routeBackendError(err);
+            output.error(routed.message);
+            process.exitCode = routed.exitCode;
+            return;
+          }
+          if (opts.json) {
+            output.json(data);
+            return;
+          }
+          output.success(`MCP policy${body.name ? ` "${body.name}"` : ''} created.`);
+          displayToolPolicy(unwrapToolPolicy(data));
+          return;
+        }
+
+        if (!opts.name) {
+          throw new Error('--name is required (or use --prompt for AI assist).');
+        }
+        if (!opts.mcpServer) {
+          throw new Error('--mcp-server is required (or use --prompt for AI assist).');
+        }
+        if (!opts.action) {
+          throw new Error('--action is required (or use --prompt for AI assist).');
+        }
+
         const action = normalizeAction(opts.action, TOOL_ACTIONS, '--action');
         if ((action === 'BLOCK' || action === 'WARN') && !opts.customMessage) {
           throw new Error('--custom-message is required when --action is BLOCK or WARN.');
@@ -1575,6 +1752,9 @@ Learn more: ${DOCS_TOOL}
           enabled: !opts.disabled,
           config: {},
         };
+        if (opts.config) {
+          body.config = parseJsonOrThrow(opts.config);
+        }
         if (hasTool) body.mcp_tool = opts.mcpTool;
         if (hasActionType) body.mcp_tool_action_type = opts.mcpActionType;
         if (opts.customMessage) body.custom_message = opts.customMessage;
@@ -1593,7 +1773,7 @@ Learn more: ${DOCS_TOOL}
         displayToolPolicy(unwrapToolPolicy(data));
       } catch (err) {
         output.error(err.message);
-        process.exitCode = 1;
+        process.exitCode = err.exitCode || 1;
       }
     });
 

package/src/commands/setup.js

@@ -946,13 +946,14 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
   // actually supports it (Claude Code hooks, Codex hooks, Copilot hooks).
   // Cursor would print "not supported"; passing the flag to gateway-mode
   // scripts would error out — `scriptSupportsBackfill` checks for both.
-  return runBatch(resolvedTools, (tool) => {
+  const result = await runBatch(resolvedTools, (tool) => {
     const args = buildScriptArgs(apiKey, {
       backendUrl, frontendUrl, gatewayUrl,
       backfill: backfill && scriptSupportsBackfill(tool.script),
     });
     return runScriptPiped(tool.script, args);
   });
+  return result;
 }
 
 /**
@@ -967,13 +968,14 @@ async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gate
       if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
     }
   }
-  return runBatch(resolvedTools, (tool) => {
+  const result = await runBatch(resolvedTools, (tool) => {
     const args = buildScriptArgs(adminApiKey, {
       backendUrl, frontendUrl, gatewayUrl, mdm: true,
       backfill: backfill && scriptSupportsBackfill(tool.script),
     });
     return runScriptPiped(tool.script, args);
   });
+  return result;
 }
 
 module.exports = {

package/src/lib/no-ai-guard.js

@@ -0,0 +1,77 @@
+// Steering guard for `policy tool create-terminal` / `create-mcp`.
+//
+// Three layers, evaluated in order. Routing happens BEFORE src/lib/policy-ai-assist.js
+// is reached — this module never touches the network and has no external deps.
+//
+//   Layer 1 (assertSteering): require either --prompt or an explicit --no-ai opt-out.
+//                             Reject --prompt + --no-ai (mutex).
+//   Layer 2 (assertSteering): under CLAUDECODE=1, reject --no-ai unless the env-gated
+//                             escape hatch UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1 is set.
+//   Layer 3 (helpBannerFor):  banner-first --help so the AI-assisted form is the
+//                             one a reader sees first.
+//
+// Errors carry `err.exitCode = 2` so the .action() catch block in src/commands/policy.js
+// can propagate via `process.exitCode = err.exitCode || 1`.
+
+function makeGuardError(message) {
+  const err = new Error(message);
+  err.exitCode = 2;
+  return err;
+}
+
+// Layer 1 + Layer 2. Throws a guard error (exitCode 2) on rejection.
+// `opts` is the parsed commander options object; `--no-ai` arrives as `opts.ai === false`.
+// "prompt provided" means `--prompt` appeared on the command line at all (even
+// empty-string) — the empty-prompt case is validated by the existing
+// `opts.prompt.trim() === ''` check in the prompt branch so that callers see the
+// dedicated "--prompt cannot be empty." error rather than the steering message.
+function assertSteering(opts, { subcommandName, env = process.env } = {}) {
+  const hasPrompt = opts.prompt !== undefined;
+  const noAi = opts.ai === false;
+
+  // Mutex (layer 1): --prompt + --no-ai is incoherent — pick one.
+  if (hasPrompt && noAi) {
+    throw makeGuardError(
+      'Pass --prompt for AI-assisted creation or --no-ai for raw flags, not both.'
+    );
+  }
+
+  // Layer 1: neither --prompt nor --no-ai → steer to the AI-assisted form.
+  if (!hasPrompt && !noAi) {
+    throw makeGuardError(
+      `${subcommandName} requires AI-assisted creation. Retry with --prompt "<natural language description>". To use raw classification flags instead, opt out explicitly with --no-ai.`
+    );
+  }
+
+  // Layer 2: under Claude Code, even --no-ai is rejected unless the human-only
+  // escape hatch is set. This is steering, not security — the env var is in
+  // plain sight in the error message. See PLAN risk R2.
+  if (noAi && env.CLAUDECODE === '1' && env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE !== '1') {
+    throw makeGuardError(
+      `--no-ai is disabled under CLAUDECODE=1. This is intended for interactive humans, not for agents. Retry with --prompt "<natural language description>", or set UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1 if you are an interactive human.`
+    );
+  }
+}
+
+// Layer 3: banner rendered above commander's auto-generated `Usage:` line by
+// `.addHelpText('before', helpBannerFor(...))`. Keep it short so the help screen
+// is still scannable.
+function helpBannerFor(subcommandName) {
+  const examples = {
+    'create-terminal': 'unbound policy tool create-terminal --prompt "block rm -rf"',
+    'create-mcp': 'unbound policy tool create-mcp --prompt "audit all Linear writes"',
+  };
+  if (!Object.prototype.hasOwnProperty.call(examples, subcommandName)) {
+    throw new Error(`helpBannerFor: unknown subcommand "${subcommandName}"`);
+  }
+  const promptExample = examples[subcommandName];
+  return [
+    'AI-ASSISTED (preferred):',
+    `  $ ${promptExample}`,
+    '',
+    'To use raw classification flags instead, opt out explicitly with --no-ai.',
+    '',
+  ].join('\n');
+}
+
+module.exports = { assertSteering, helpBannerFor };