unbound-cli 1.1.8 → 1.3.0

package/LOCAL_DEV.md

@@ -52,7 +52,7 @@ node src/index.js config reset-gateway-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:
+The `setup` and `onboard` commands (MDM vs user scope auto-detected from sudo) 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`).
@@ -79,22 +79,22 @@ node src/index.js setup cursor claude-code-gateway --backend-url http://localhos
 # 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
+# MDM (run setup with sudo — auto-detected; the frontend URL is passed as --frontend-url)
+sudo node src/index.js setup --api-key <ADMIN_KEY> --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 
 # 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
+sudo node src/index.js onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> \
+    --backend-url http://localhost:8000 --frontend-url http://localhost:3000
 ```
 
 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 dropped by the CLI; only `--backend-url` and `--gateway-url` are forwarded.
+- `onboard` also takes 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.
+- Under sudo (MDM), the CLI passes the frontend URL to the setup scripts as `--frontend-url`; without sudo (user scope) it passes it as `--domain`. All three URLs (backend, frontend, gateway) are forwarded and persisted to each user's `config.json`.
 
 ## Verify config
 
@@ -119,8 +119,8 @@ node src/index.js login --base-url http://localhost:8000 --api-key <your-key>
 
 ```bash
 # Auth
-node src/index.js whoami
 node src/index.js status
+node src/index.js doctor
 
 # Policies — overview
 node src/index.js policy                         # overview + docs links
@@ -186,8 +186,8 @@ node src/index.js setup --all --api-key <key>
 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>
+# MDM onboarding (admin device enrollment, requires root — MDM scope auto-detected from sudo)
+sudo node src/index.js onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
 ```
 
 ## Unlink when done

package/README.md

@@ -17,8 +17,8 @@ unbound login
 # Or login with an API key (for CI/CD or headless environments)
 unbound login --api-key <your-api-key>
 
-# Check who you are
-unbound whoami
+# Check your status, role, and connected tools
+unbound status
 
 # List policies
 unbound policy list
@@ -40,7 +40,7 @@ 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>
+sudo unbound onboard --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.
@@ -55,8 +55,8 @@ The user API key and discovery API key are separate — discovery uses its own k
 | `unbound login --api-key <key>` | Sign in with an API key (non-interactive) |
 | `unbound login --domain <domain>` | Sign in via a custom domain |
 | `unbound logout` | Remove stored credentials |
-| `unbound whoami` | Show current user, org, and role |
-| `unbound status` | Show CLI status and API connectivity |
+| `unbound status` | Show CLI status, role, and connected tools |
+| `unbound doctor` | Diagnose per-tool health (config, hook, env) and API key |
 
 ### Tool Setup
 
@@ -106,9 +106,9 @@ Configure all users on a device via MDM. Requires root.
 
 | Command | Description |
 |---------|-------------|
-| `sudo unbound setup mdm --admin-api-key KEY --all` | Set up all tools |
-| `sudo unbound setup mdm --admin-api-key KEY cursor codex-subscription` | Set up specific tools |
-| `sudo unbound setup mdm --admin-api-key KEY --clear cursor` | Remove config for specific tools |
+| `sudo unbound setup --api-key KEY --all` | Set up all tools |
+| `sudo unbound setup --api-key KEY cursor codex-subscription` | Set up specific tools |
+| `sudo unbound setup --clear cursor` | Remove config for specific tools |
 
 Available tools: `cursor`, `copilot`, `claude-code-subscription`, `claude-code-gateway`, `gemini-cli`, `codex-subscription`, `codex-gateway`
 

package/package.json

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

package/src/commands/chat.js

@@ -121,7 +121,7 @@ function normalizeAssistantTurn(turn) {
 // backend-supplied strings out of the shell line so copy-pastes stay safe.
 function friendlyChatError(err) {
   if (err?.statusCode === 401) return 'Not authenticated. Run `unbound login` and try again.';
-  if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound whoami` to check yours.';
+  if (err?.statusCode === 403) return 'Chat requires Admin or Manager role. Run `unbound status` to check yours.';
   if (err?.statusCode === 429) return 'Rate limited. Please wait a moment and try again.';
   return sanitizeForTerminal(err?.message || 'Request failed.');
 }
@@ -479,7 +479,7 @@ INTERACTIVE SESSION
     /exit              quit (Ctrl+C also works)
 
 NOTES
-  * Requires Admin or Manager role in your organization. Run 'unbound whoami' to check.
+  * Requires Admin or Manager role in your organization. Run 'unbound status' to check.
   * Conversation history is held in memory only; nothing is ever written to disk.
   * Each -m invocation sends no history; keep each prompt self-contained.
   * -o writes a new file with mode 0600 and refuses to overwrite existing files.

package/src/commands/doctor.js

@@ -0,0 +1,198 @@
+const { spawnSync } = require('child_process');
+const config = require('../config');
+const api = require('../api');
+const output = require('../output');
+const { getDeviceSerial } = require('../device-serial');
+const { detectTools } = require('../toolHealth');
+const { hasRootPrivileges } = require('./setup');
+
+// Validate the stored API key against the backend. Returns one of:
+// valid | invalid | not-logged-in | unverified (network/other error).
+async function checkApiKey() {
+  if (!config.isLoggedIn()) return { state: 'not-logged-in', detail: 'no API key stored — run `unbound login`' };
+  try {
+    const deviceSerial = await getDeviceSerial();
+    const privileges = await api.get('/api/v1/users/privileges/', { query: { device_serial: deviceSerial } });
+    config.backfillUserInfo(privileges);
+    return { state: 'valid', detail: 'verified against the backend' };
+  } catch (err) {
+    // The HTTP status is the reliable signal; the message wording can change.
+    if (err && (err.statusCode === 401 || /invalid or expired|401|unauthor/i.test(err.message || ''))) {
+      return { state: 'invalid', detail: 'the stored key was rejected (401) — run `unbound login`' };
+    }
+    return { state: 'unverified', detail: `could not verify (${err.message})` };
+  }
+}
+
+// Exit code for `--fix`: signal/spawn error → 1; otherwise the `setup` status. A
+// successful non-root run that left MDM tools tampered still fails so a CI gate
+// doesn't read the machine as clean. As root those tools were just repaired, so a
+// status-0 run is clean — don't penalize.
+function fixExitCode(status, root, mdmRemaining) {
+  if (status == null) return 1;
+  return status || (!root && mdmRemaining ? 1 : 0);
+}
+
+function register(program) {
+  program
+    .command('doctor')
+    .description('Diagnose the local Unbound install: per-tool config, hook script and env wiring, plus API-key validity. Prints how to fix anything broken.')
+    .addHelpText('after', `
+For each AI coding tool, doctor verifies:
+  Config       - the tool's config file contains the Unbound integration
+  Hook script  - the installed hook/key-helper file exists
+  Env wiring   - the API key (and gateway URL, for gateway mode) is exported
+
+Per-tool status:
+  Healthy       - everything in place
+  Tampered      - partially installed (reinstall to fix)
+  Not installed - no Unbound integration found
+  Managed by MDM- configured org-wide by your administrator
+
+Exit code is non-zero when any tool is tampered or the API key is invalid, so
+doctor can gate scripts/CI.
+
+Examples:
+  $ unbound doctor
+  $ unbound doctor --fix      Reinstall every tampered tool
+  $ unbound doctor --json
+`)
+    .option('--fix', 'Reinstall every tool reported as tampered')
+    .option('--json', 'Output raw JSON')
+    .action(async (opts) => {
+      try {
+        const apiKey = config.getApiKey();
+        const gatewayUrl = config.getGatewayUrl();
+
+        const spin = output.spinner('Running diagnostics...');
+        const key = await checkApiKey();
+        const tools = detectTools({ gatewayUrl, apiKey });
+        spin.stop();
+
+        const tampered = tools.filter((t) => t.status === 'tampered');
+        const unhealthy = tampered.length > 0 || key.state === 'invalid';
+
+        if (opts.json) {
+          output.json({
+            api_key: key,
+            tools: tools.map((t) => ({
+              tool: t.key,
+              label: t.label,
+              mode: t.mode,
+              status: t.status,
+              conflict: !!t.conflict,
+              checks: t.checks.map((c) => ({ name: c.name, ok: c.ok, kind: c.kind, detail: c.detail, warn: !!c.warn })),
+            })),
+            healthy: !unhealthy,
+          });
+          if (unhealthy) process.exitCode = 1;
+          return;
+        }
+
+        const C = output.colors;
+        const labelOf = (t) => t.label + (t.mode ? ` (${t.mode})` : '');
+        const W = Math.max(7, ...tools.map((t) => labelOf(t).length)); // 7 = "API key"
+
+        console.log('');
+        const keyText = {
+          valid: C.green('✓ Valid'),
+          invalid: C.red('✗ Invalid or expired'),
+          'not-logged-in': C.dim('– Not logged in'),
+          unverified: `${C.yellow('? Could not verify')} ${C.dim(`(${key.detail})`)}`,
+        }[key.state];
+        console.log(`  ${C.bold('API key'.padEnd(W))}   ${keyText}`);
+        console.log('');
+
+        for (const t of tools) {
+          let s;
+          if (t.status === 'healthy') s = C.green('✓ Healthy');
+          else if (t.status === 'managed-by-mdm') s = C.green('✓ Healthy') + C.dim(' · managed by MDM');
+          else if (t.status === 'tampered') {
+            // Status + reason on one line. Mode sits next to the tool name.
+            const reasons = [];
+            if (t.conflict) reasons.push('two modes installed');
+            for (const c of t.checks) if (!c.ok) reasons.push(c.summary || c.name);
+            s = C.red(`✗ Tampered — ${reasons.join(', ')}`);
+          } else s = C.dim('○ Not set up');
+          console.log(`  ${labelOf(t).padEnd(W)}   ${s}`);
+        }
+        console.log('');
+
+        // Fix routing. User-level tools are fixable by anyone (`unbound doctor
+        // --fix`); MDM-managed ones need `sudo`. One sudo run repairs everything
+        // (sudo `setup` installs MDM-wide, and on macOS sudo keeps HOME so it sees
+        // the user's tools too). When both kinds are broken we show both commands
+        // so a user WITHOUT sudo can still repair their own user-level tools.
+        const userTampered = tampered.filter((t) => t.scope !== 'mdm');
+        const mdmTampered = tampered.filter((t) => t.scope === 'mdm');
+        const userFix = userTampered.map((t) => t.key);
+        const mdmFix = mdmTampered.map((t) => t.key);
+        const userNames = userTampered.map((t) => t.label).join(', ');
+        const mdmNames = mdmTampered.map((t) => t.label).join(', ');
+        const allFix = tampered.map((t) => t.key);
+        const anyInstalled = tools.some((t) => t.status !== 'not-installed');
+
+        if (opts.fix) {
+          if (!tampered.length) {
+            if (!anyInstalled) console.log(`${C.yellow('No tools are set up yet')} — nothing to fix. Run ${C.bold('unbound setup')} first.`);
+            else output.success('Nothing to fix — all set up tools are healthy.');
+            console.log('');
+            return;
+          }
+          const root = hasRootPrivileges();
+          // sudo → reinstall everything (MDM-wide); without sudo → the user-level
+          // tools only, and point at sudo for whatever's org-managed.
+          if (!root && !userFix.length) {
+            console.log(`${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization.`);
+            console.log(`  Run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+            console.log('');
+            process.exitCode = 1;
+            return;
+          }
+          const fixNow = root ? allFix : userFix;
+          output.info(`Reinstalling: ${fixNow.join(', ')}${root ? ' (org-wide, all users)' : ''}`);
+          console.log('');
+          const r = spawnSync(process.argv[0], [process.argv[1], 'setup', ...fixNow], { stdio: 'inherit' });
+          if (!root && mdmFix.length) console.error(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+          process.exitCode = fixExitCode(r.status, root, mdmFix.length > 0);
+          return;
+        }
+
+        // No `--fix`: report and show the command(s) that fix it.
+        if (!anyInstalled && key.state !== 'invalid') {
+          console.log(`${C.yellow('No AI tools are set up yet.')} Run ${C.bold('unbound setup')} to get started.`);
+          console.log('');
+          return;
+        }
+        if (!unhealthy) {
+          output.success('All set up tools are healthy.');
+          console.log('');
+          return;
+        }
+        if (tampered.length) {
+          console.log(C.red(`✗ ${tampered.length} tool${tampered.length === 1 ? ' needs' : 's need'} attention.`));
+          if (!mdmFix.length) {
+            console.log(`  Run ${C.bold('unbound doctor --fix')} to repair ${userNames}.`);
+          } else if (!userFix.length) {
+            console.log(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization.`);
+            console.log(`  Run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
+          } else {
+            // Both: a user without sudo can still fix their own tools; sudo fixes everything.
+            console.log(`  Run ${C.bold('unbound doctor --fix')} to repair ${userNames}.`);
+            console.log(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'} too.`);
+          }
+        }
+        if (key.state === 'invalid') {
+          if (!tampered.length) console.log(C.red('✗ Your API key is invalid or expired.'));
+          console.log(`  Run ${C.bold('unbound login')} to re-authenticate.`);
+        }
+        console.log('');
+        process.exitCode = 1;
+      } catch (err) {
+        if (!err.displayed) output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { register, fixExitCode };