unbound-cli 0.3.1 → 0.5.0

package/LOCAL_DEV.md

@@ -68,11 +68,44 @@ node src/index.js login --base-url http://localhost:8000 --api-key <your-key>
 node src/index.js whoami
 node src/index.js status
 
-# Policies
+# Policies — overview
+node src/index.js policy                         # overview + docs links
+node src/index.js policy form-data               # reference data (must produce output — bugfix)
 node src/index.js policy list
 node src/index.js policy list --type SECURITY --json
 node src/index.js policy get 1
-node src/index.js policy form-data
+node src/index.js policy effective 1
+
+# Policy type subcommands
+node src/index.js policy cost --help
+node src/index.js policy model --help
+node src/index.js policy security --help
+node src/index.js policy tool --help
+
+# Cost policies
+node src/index.js policy cost list
+node src/index.js policy cost create --name "Test Cost" --monthly-budget 500 --group engg
+node src/index.js policy cost update 5 --monthly-budget 750
+
+# Model policies
+node src/index.js policy model create --name "No Opus" --all-models --excluded claude-3-opus
+node src/index.js policy model create --name "Sonnet Only" --allowed claude-3-5-sonnet
+
+# Security policies
+node src/index.js policy security create --name "Block PII" --sub-type guardrails \
+    --guardrail PII:BLOCK --guardrail Secrets:REDACT
+node src/index.js policy security create --name "Route 429s" --sub-type error-code-routing \
+    --error-route 429:gpt-4:claude-3-5-sonnet
+
+# Tool policies (separate backend: /api/v1/command-policies/)
+node src/index.js policy tool list
+node src/index.js policy tool families
+node src/index.js policy tool mcp-servers
+node src/index.js policy tool create-terminal --name "Block rm -rf" \
+    --command-family filesystem --field command='rm -rf*' --action BLOCK \
+    --custom-message "Destructive command blocked."
+node src/index.js policy tool create-mcp --name "Audit Linear writes" \
+    --mcp-server Linear --mcp-action-type write --action AUDIT
 
 # Users
 node src/index.js users list
@@ -90,6 +123,17 @@ node src/index.js tools approved
 # Setup
 node src/index.js setup cursor
 node src/index.js setup claude-code
+
+# Setup the default bundle (Cursor + Claude Code hooks + Codex hooks)
+node src/index.js setup --all
+node src/index.js setup --all --api-key <key>
+
+# Onboarding (one command: login + setup --all + discover)
+node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+sudo node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+
+# MDM onboarding (admin device enrollment, requires root)
+sudo node src/index.js onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
 ```
 
 ## Unlink when done

package/README.md

@@ -30,6 +30,20 @@ unbound setup
 unbound setup cursor
 ```
 
+## Onboarding (one command)
+
+For new users, the fastest path from install to a fully-configured device is the `onboard` command. It logs you in, installs the default tool bundle (Cursor, Claude Code hooks, Codex hooks), and runs device discovery — all in one step.
+
+```bash
+# End user
+npm install -g unbound-cli
+unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+
+# Admin enrolling a device via MDM (requires root)
+sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
+```
+
+The user API key and discovery API key are separate — discovery uses its own key that the CLI does not store. Run with `sudo` to let the discovery step scan all users on the device; without it, only the current user is scanned.
 
 ## Commands
 
@@ -51,6 +65,7 @@ Interactive batch setup:
 | Command | Description |
 |---------|-------------|
 | `unbound setup` | Select and install multiple tools interactively |
+| `unbound setup --all` | Install the default bundle: Cursor + Claude Code hooks + Codex hooks |
 
 Automated setup (downloads scripts, sets env vars, configures tool):
 
@@ -112,17 +127,92 @@ Scan a device for installed AI coding tools and report findings to Unbound. Uses
 
 ### Policies (Admin only)
 
+Unbound has **four** policy types. Each has its own subcommand with guided flag-based create/update. Tool policies live on a separate backend endpoint but are reachable under the same `policy` command tree.
+
+Docs: https://docs.getunbound.ai/policies
+
+| Type | Subcommand | Purpose | Docs |
+|---|---|---|---|
+| **Cost** | `unbound policy cost` | Monthly budget limits per user group | https://docs.getunbound.ai/policies/cost-policies |
+| **Model** | `unbound policy model` | Control which AI models are available | https://docs.getunbound.ai/policies/model-policies |
+| **Security** | `unbound policy security` | Guardrails (PII, secrets), routing rules | https://docs.getunbound.ai/policies/security-policies |
+| **Tool** | `unbound policy tool` | Shell command and MCP tool controls | https://docs.getunbound.ai/policies/tool-policies |
+
+Generic commands (Cost/Model/Security only):
+
 | Command | Description |
 |---------|-------------|
-| `unbound policy list` | List all policies |
-| `unbound policy get <id>` | Get policy details |
-| `unbound policy create --name <n> --type <t>` | Create a policy |
-| `unbound policy update <id>` | Update a policy |
+| `unbound policy` | Overview of types and subcommands |
+| `unbound policy list [--type COST\|MODEL\|SECURITY]` | List policies |
+| `unbound policy get <id>` | Get a policy's details |
 | `unbound policy delete <id>` | Delete a policy |
-| `unbound policy form-data` | Get reference data for policy creation |
-| `unbound policy effective <id>` | View effective policies for a user/group |
+| `unbound policy form-data` | Reference data: user groups, models, guardrails, tool types, command policies |
+| `unbound policy effective <id> [--user\|--group]` | View effective policies for a user or group |
+
+Cost policy examples:
+
+```bash
+# Create a $1,000/month cap for the engg user group
+unbound policy cost create --name "Eng Budget" --monthly-budget 1000 --group engg
+
+# Change the budget
+unbound policy cost update 5 --monthly-budget 1500
+
+# List just cost policies
+unbound policy cost list
+```
+
+Model policy examples:
+
+```bash
+# Allow only specific models
+unbound policy model create --name "Sonnet Only" --allowed claude-3-5-sonnet
+
+# Allow everything except specific models
+unbound policy model create --name "No Opus" --all-models --excluded claude-3-opus
+
+# List all model policies
+unbound policy model list
+```
+
+Security policy examples:
+
+```bash
+# Block PII, redact secrets, for the engg group
+unbound policy security create --name "Block PII" --sub-type guardrails \
+    --guardrail PII:BLOCK --guardrail Secrets:REDACT --group engg
+
+# Default-route gpt-4 traffic to claude-3-5-sonnet
+unbound policy security create --name "Prefer Sonnet" --sub-type default-routing \
+    --route gpt-4:claude-3-5-sonnet
+
+# Fall back on 429s
+unbound policy security create --name "429 Fallback" --sub-type error-code-routing \
+    --error-route 429:gpt-4:claude-3-5-sonnet
+```
+
+Tool policy examples:
+
+```bash
+# 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 \
+    --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 \
+    --mcp-action-type write --action AUDIT
+
+# List, get, delete
+unbound policy tool list
+unbound policy tool get <id>
+unbound policy tool delete <id>
+```
 
-Policy types: `SECURITY`, `MODEL`, `COST`
+Before creating any policy, run `unbound policy form-data` to see available user group names, model names, guardrail names, and existing command policies. The CLI accepts names (e.g. `engg`, `claude-3-opus`, `PII`) and resolves them to backend IDs automatically. You can also pass numeric IDs directly.
 
 ### Users
 

package/package.json

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

package/src/commands/discover.js

@@ -13,6 +13,15 @@ function isRoot() {
   return typeof process.getuid === 'function' && process.getuid() === 0;
 }
 
+/**
+ * Escapes a string for safe embedding in a shell command (single-quote wrap).
+ * Mirrors the helper in setup.js. Required because runDiscoveryScript uses
+ * spawn(cmd, { shell: true }) which routes the full command through bash.
+ */
+function shellEscape(str) {
+  return "'" + String(str).replace(/'/g, "'\\''") + "'";
+}
+
 /**
  * Downloads a bash script from the discovery repo and executes it with arguments.
  * Uses stdio: 'inherit' so the script's output is shown live.
@@ -36,6 +45,26 @@ function runDiscoveryScript(scriptName, args) {
   });
 }
 
+/**
+ * Runs the main discovery scan (install.sh) with the given discovery key and domain.
+ * Emits a warning if not running as root (scan will be limited to the current user).
+ * Throws on failure. Used by both the `discover` command and the `onboard` command.
+ */
+async function runDiscoveryScan({ apiKey, domain = DEFAULT_DOMAIN }) {
+  if (!apiKey) {
+    throw new Error('Discovery API key is required.');
+  }
+
+  if (!isRoot()) {
+    output.warn('Running without root. Only scanning current user\'s tools.');
+    output.info('Run with sudo to scan all users on this device.');
+    console.log('');
+  }
+
+  const args = `--api-key ${shellEscape(apiKey)} --domain ${shellEscape(domain)}`;
+  await runDiscoveryScript('install.sh', args);
+}
+
 function register(program) {
   const discover = program
     .command('discover')
@@ -72,14 +101,7 @@ Examples:
           return;
         }
 
-        if (!isRoot()) {
-          output.warn('Running without root. Only scanning current user\'s tools.');
-          output.info('Run with sudo to scan all users on this device.');
-          console.log('');
-        }
-
-        const args = `--api-key "${opts.apiKey}" --domain "${opts.domain}"`;
-        await runDiscoveryScript('install.sh', args);
+        await runDiscoveryScan({ apiKey: opts.apiKey, domain: opts.domain });
 
         console.log('');
         output.success('Discovery complete');
@@ -125,7 +147,7 @@ Examples:
           return;
         }
 
-        const args = `--api-key "${opts.apiKey}" --domain "${opts.domain}"`;
+        const args = `--api-key ${shellEscape(opts.apiKey)} --domain ${shellEscape(opts.domain)}`;
         await runDiscoveryScript('setup-scheduled-scan.sh', args);
       } catch (err) {
         output.error(err.message);
@@ -207,4 +229,4 @@ Examples:
     });
 }
 
-module.exports = { register };
+module.exports = { register, runDiscoveryScan };

package/src/commands/onboard.js

@@ -0,0 +1,134 @@
+const { Option } = require('commander');
+const config = require('../config');
+const output = require('../output');
+const { ensureLoggedIn } = require('../auth');
+const { runSetupAllBundle, runMdmSetupAllBundle, checkRoot, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
+const { runDiscoveryScan } = require('./discover');
+
+const DEFAULT_DOMAIN = 'https://backend.getunbound.ai';
+
+/**
+ * Builds the recovery-command suffix for partial-failure hints.
+ * Includes `--domain <value>` only when the user supplied a non-default domain,
+ * so users running against a custom backend get a copy-pastable command.
+ */
+function domainHintSuffix(domain) {
+  if (!domain || domain === DEFAULT_DOMAIN) return '';
+  return ` --domain ${domain}`;
+}
+
+function register(program) {
+  program
+    .command('onboard')
+    .description(
+      'One-step user onboarding: install the default AI tools bundle and run device discovery. ' +
+      'Runs `setup --all` followed by `discover` in a single command.'
+    )
+    .requiredOption('--api-key <key>', 'User API key (for tool setup and login)')
+    .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
+    .option('--domain <url>', 'Backend URL for discovery', DEFAULT_DOMAIN)
+    .addHelpText('after', `
+Runs the full onboarding flow for an end user:
+  1. Logs in with --api-key and stores credentials.
+  2. Installs the default tool bundle: ${ALL_TOOLS.join(', ')}.
+  3. Runs device discovery with --discovery-key.
+
+The user API key and discovery API key are separate keys obtained from
+different parts of the Unbound dashboard. Discovery uses its own key
+that is not stored in the CLI config.
+
+Run with sudo to let the discovery step scan all users on the device.
+Without sudo, discovery only scans the current user.
+
+For admin device enrollment via MDM, use \`unbound onboard-mdm\` instead.
+
+Examples:
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ sudo unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+`)
+    .action(async (opts) => {
+      let setupSucceeded = false;
+      try {
+        await ensureLoggedIn({ apiKey: opts.apiKey });
+        const apiKey = config.getApiKey();
+
+        console.log('');
+        output.info('Step 1/2: Installing tool bundle');
+        const ok = await runSetupAllBundle(apiKey);
+        if (!ok) return;
+        setupSucceeded = true;
+
+        console.log('');
+        output.info('Step 2/2: Running device discovery');
+        console.log('');
+        await runDiscoveryScan({ apiKey: opts.discoveryKey, domain: opts.domain });
+
+        console.log('');
+        output.success('Onboarding complete');
+      } catch (err) {
+        if (!err.displayed) output.error(err.message);
+        if (setupSucceeded) {
+          const suffix = domainHintSuffix(opts.domain);
+          console.error('  Tool setup completed successfully — only discovery failed.');
+          console.error(`  Re-run discovery only with: unbound discover --api-key <DISCOVERY_KEY>${suffix}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+
+  // --- MDM onboard (separate top-level command, mirrors `unbound onboard`) ---
+
+  program
+    .command('onboard-mdm')
+    .description(
+      'One-step MDM onboarding: install the default MDM tool bundle and run device discovery. ' +
+      'Requires root. Used by organization admins to enroll devices via MDM.'
+    )
+    .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
+    .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
+    .option('--domain <url>', 'Backend URL for discovery', DEFAULT_DOMAIN)
+    .addOption(new Option('--url <url>', 'Override backend URL for setup scripts').hideHelp())
+    .addHelpText('after', `
+Runs the full MDM onboarding flow for device enrollment:
+  1. Installs the MDM tool bundle: ${MDM_ALL_TOOLS.join(', ')}.
+  2. Runs device discovery against all users on the device.
+
+Both steps require root. The admin API key and discovery API key are
+separate keys obtained from different parts of the Unbound admin dashboard.
+
+For end-user onboarding (non-MDM), use \`unbound onboard\` instead.
+
+Examples:
+  $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
+`)
+    .action(async (opts) => {
+      let setupSucceeded = false;
+      try {
+        checkRoot('onboard-mdm');
+
+        console.log('');
+        output.info('Step 1/2: Installing MDM tool bundle');
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { url: opts.url });
+        if (!ok) return;
+        setupSucceeded = true;
+
+        console.log('');
+        output.info('Step 2/2: Running device discovery');
+        console.log('');
+        await runDiscoveryScan({ apiKey: opts.discoveryKey, domain: opts.domain });
+
+        console.log('');
+        output.success('MDM onboarding complete');
+      } catch (err) {
+        if (!err.displayed) output.error(err.message);
+        if (setupSucceeded) {
+          const suffix = domainHintSuffix(opts.domain);
+          console.error('  MDM tool setup completed successfully — only discovery failed.');
+          console.error(`  Re-run discovery only with: sudo unbound discover --api-key <DISCOVERY_KEY>${suffix}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { register };