unbound-cli 0.3.0 → 0.4.0

package/LOCAL_DEV.md

@@ -90,6 +90,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):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "0.3.0",
+  "version": "0.4.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 };

package/src/commands/setup.js

@@ -27,6 +27,10 @@ const MDM_TOOLS = {
 // Default tools for --all (uses subscription mode for Claude Code and Codex since only one can be active)
 const MDM_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription'];
 
+// Default tools for user-level `unbound setup --all`.
+// Includes Cursor, Claude Code hooks, and Codex hooks (no Gemini CLI).
+const ALL_TOOLS = ['cursor', 'claude-code-subscription', 'codex-subscription'];
+
 // Tool name → script mapping for automated tools
 const SETUP_TOOL_MAP = {
   'cursor':                   { label: 'Cursor',                     script: 'cursor/setup.py' },
@@ -130,11 +134,12 @@ function runScriptPiped(scriptPath, args) {
 /**
  * Checks that the process is running as root (macOS/Linux).
  * Windows admin check is handled by the Python MDM scripts themselves.
+ * Pass a customized hint for the calling command (defaults to "setup mdm").
  */
-function checkRoot() {
+function checkRoot(commandHint = 'setup mdm') {
   if (process.platform === 'win32') return;
   if (typeof process.getuid !== 'function' || process.getuid() !== 0) {
-    throw new Error('MDM setup requires root. Run with: sudo unbound setup mdm ...');
+    throw new Error(`MDM setup requires root. Run with: sudo unbound ${commandHint} ...`);
   }
 }
 
@@ -171,6 +176,7 @@ function register(program) {
     .option('--clear', 'Remove Unbound configuration for the specified tools')
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
+    .option('--all', 'Set up the default bundle: Cursor, Claude Code (hooks), Codex (hooks)')
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -195,6 +201,10 @@ Examples:
   $ unbound setup claude-code --subscription               Claude Code hooks only
   $ unbound setup codex --gateway                          Codex gateway mode
 
+  Install the default bundle (Cursor + Claude Code hooks + Codex hooks):
+  $ unbound setup --all                                    Set up the default bundle
+  $ unbound setup --all --api-key <key>                    Login + set up the bundle
+
   One-step login and setup:
   $ unbound setup cursor --api-key <key>                   Login + set up Cursor
   $ unbound setup cursor claude-code-gateway --api-key <key>
@@ -217,6 +227,16 @@ automatically to authenticate before proceeding.
         const apiKey = config.getApiKey();
         const frontendUrl = config.getFrontendUrl();
 
+        // --all expands to the default bundle. Cannot be combined with explicit tool names.
+        if (opts.all) {
+          if (tools.length > 0) {
+            output.error('Cannot combine --all with explicit tool names.');
+            process.exitCode = 1;
+            return;
+          }
+          tools = [...ALL_TOOLS];
+        }
+
         // No tools specified → interactive multi-select (existing flow)
         if (tools.length === 0) {
           const selected = await output.multiSelect(
@@ -455,7 +475,7 @@ Examples:
         console.log('');
 
         const mdmArgs = (tool) => {
-          let args = `--api_key ${shellEscape(opts.adminApiKey)}`;
+          let args = `--api-key ${shellEscape(opts.adminApiKey)}`;
           if (opts.url) args += ` --url ${shellEscape(opts.url)}`;
           if (opts.clear) args += ' --clear';
           return args;
@@ -477,4 +497,34 @@ Examples:
     });
 }
 
-module.exports = { register };
+/**
+ * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks) with spinners.
+ * Assumes the caller has already ensured the user is logged in.
+ * Returns true on success, false on failure.
+ */
+async function runSetupAllBundle(apiKey) {
+  const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
+  const args = `--api-key ${shellEscape(apiKey)}`;
+  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+}
+
+/**
+ * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks) with spinners.
+ * Caller must ensure the process is running as root.
+ * Returns true on success, false on failure.
+ */
+async function runMdmSetupAllBundle(adminApiKey, { url } = {}) {
+  const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
+  let args = `--api-key ${shellEscape(adminApiKey)}`;
+  if (url) args += ` --url ${shellEscape(url)}`;
+  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+}
+
+module.exports = {
+  register,
+  runSetupAllBundle,
+  runMdmSetupAllBundle,
+  checkRoot,
+  ALL_TOOLS,
+  MDM_ALL_TOOLS,
+};

package/src/index.js

@@ -23,8 +23,13 @@ AUTHENTICATION
   $ unbound whoami                         Show current user and organization
   $ unbound status                         Show CLI status and API connectivity
 
+ONBOARDING (one-step install + discover)
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
+
 TOOL SETUP
   $ unbound setup                          Select and install multiple tools interactively
+  $ unbound setup --all                    Set up the default bundle (Cursor + Claude Code hooks + Codex hooks)
   $ unbound setup cursor                   Set up Cursor
   $ unbound setup claude-code              Set up Claude Code (interactive mode selection)
   $ unbound setup claude-code --gateway    Use Unbound as AI provider
@@ -113,6 +118,7 @@ require('./commands/user-groups').register(program);
 require('./commands/tools').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);
+require('./commands/onboard').register(program);
 
 // config command for managing CLI settings
 const configCmd = program