unbound-cli 0.4.0 → 0.5.1

package/LOCAL_DEV.md

@@ -43,6 +43,47 @@ node src/index.js config reset-url
 node src/index.js config reset-frontend-url
 ```
 
+## Point setup scripts to a local backend / frontend
+
+The `setup`, `setup mdm`, `onboard`, and `onboard-mdm` commands invoke Python setup scripts from the `setup` repo. Those scripts:
+
+- Ping `https://backend.getunbound.ai/api/v1/setup/complete/` when a tool is configured (override with `--backend-url`).
+- Use the frontend URL for the browser-auth callback if `--api-key` is not already stored (override with `--frontend-url`, passed through to the scripts as `--domain`).
+
+Both flags are hidden from `--help` (dev-only) and work on every setup-invoking command:
+
+```bash
+# Single tool — override backend only, or both
+node src/index.js setup cursor --backend-url http://localhost:8000
+node src/index.js setup cursor --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+node src/index.js setup claude-code --gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Default bundle
+node src/index.js setup --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Multiple explicit tools
+node src/index.js setup cursor claude-code-gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Interactive mode (select tools, then apply overrides to all selected)
+node src/index.js setup --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# MDM (requires sudo; MDM scripts ignore --frontend-url since they don't use browser auth)
+sudo node src/index.js setup mdm --admin-api-key <ADMIN_KEY> --all --backend-url http://localhost:8000
+
+# Onboarding (combined setup + discover)
+node src/index.js onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> \
+    --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+sudo node src/index.js onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> \
+    --backend-url http://localhost:8000
+```
+
+When omitted, scripts default to `https://backend.getunbound.ai` and the stored frontend URL (or `https://gateway.getunbound.ai`).
+
+Notes:
+- `--backend-url` / `--frontend-url` only affect the setup scripts. They do not change the CLI's own API calls (use `config set-url` / `UNBOUND_API_URL` / `config set-frontend-url` / `UNBOUND_FRONTEND_URL` for that).
+- `onboard` and `onboard-mdm` also take a visible `--domain <url>` flag — that one is for the **discovery** backend (a separate repo), not the setup scripts' frontend. The two flags don't conflict.
+- MDM setup scripts (`setup mdm`, `onboard-mdm`) don't do browser auth, so `--frontend-url` is a no-op there; only `--backend-url` is meaningful.
+
 ## Verify config
 
 ```bash
@@ -68,11 +109,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

package/README.md

@@ -127,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.4.0",
+  "version": "0.5.1",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/commands/onboard.js

@@ -27,6 +27,8 @@ function register(program) {
     .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)
+    .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
+    .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
 Runs the full onboarding flow for an end user:
   1. Logs in with --api-key and stores credentials.
@@ -54,7 +56,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing tool bundle');
-        const ok = await runSetupAllBundle(apiKey);
+        const ok = await runSetupAllBundle(apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;
 
@@ -87,7 +89,8 @@ Examples:
     .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())
+    .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
+    .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
 Runs the full MDM onboarding flow for device enrollment:
   1. Installs the MDM tool bundle: ${MDM_ALL_TOOLS.join(', ')}.
@@ -108,7 +111,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing MDM tool bundle');
-        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { url: opts.url });
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;