unbound-cli 1.1.7 → 1.2.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
 
@@ -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

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

package/src/commands/onboard.js

@@ -2,7 +2,7 @@ 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 { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
 
 /**
@@ -20,52 +20,55 @@ function register(program) {
   const onboard = 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.'
+      'One-step onboarding: install the AI tools bundle and run device discovery. ' +
+      'Scope is auto-detected from your privileges — run with sudo to enroll every ' +
+      'user on the device (MDM/org scope), or without sudo to set up just the current user.'
     )
-    .option('--api-key <key>', 'User API key (or set UNBOUND_API_KEY env var, or reuse a stored `unbound login` key)')
-    .option('--discovery-key <key>', 'Discovery API key for device scan (or set UNBOUND_DISCOVERY_KEY env var)')
+    .option('--api-key <key>', 'API key (user key, or admin key when run with sudo). Falls back to UNBOUND_API_KEY or a stored `unbound login` key)')
+    .addOption(new Option('--admin-api-key <key>', 'Alias for --api-key (back-compat)').hideHelp())
+    .option('--discovery-key <key>', 'Discovery API key for device scan (or set UNBOUND_DISCOVERY_KEY)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
-    .option('--set-cron', 'Set up a daily background job to keep governance up to date')
-    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
+    .option('--set-cron', 'Set up a daily background job to keep governance up to date (under sudo, schedules a discovery scan only — not a full tool re-install)')
+    .option('--backfill', 'Seed historical Claude Code / Codex / Copilot sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
     .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())
     .addOption(new Option('--gateway-url <url>', 'Override gateway 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 (or reuses a stored
-     \`unbound login\` key when --api-key is omitted).
-  2. Installs the default tool bundle: ${ALL_TOOLS.join(', ')}.
+Runs the full onboarding flow, auto-detecting scope from your privileges:
+  With sudo, installs the MDM tool bundle (${MDM_ALL_TOOLS.join(', ')}) and
+  scans all users on the device. Without sudo, installs the user bundle
+  (${ALL_TOOLS.join(', ')}) and scans the current user.
+
+  1. Logs in / resolves the API key (or reuses a stored \`unbound login\` key
+     when --api-key is omitted).
+  2. Installs the tool bundle for the detected scope.
   3. Runs device discovery with --discovery-key. With --set-cron, sets up a
      recurring daily scheduled scan (cross-platform) instead of a one-time scan.
 
-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.
+The 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.
 
 Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ sudo unbound onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron
-  $ sudo unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
 `)
     .action(async (opts) => {
-      const apiKeyOpt = opts.apiKey || process.env.UNBOUND_API_KEY;
+      const apiKeyOpt = opts.apiKey || opts.adminApiKey || process.env.UNBOUND_API_KEY;
       const discoveryKeyOpt = opts.discoveryKey || process.env.UNBOUND_DISCOVERY_KEY;
-      // A stored `unbound login` key is enough — only demand --api-key when not
-      // already logged in. ensureLoggedIn() reuses the stored credential below.
-      if (!apiKeyOpt && !config.isLoggedIn()) {
-        output.error('--api-key is required (or set UNBOUND_API_KEY env var, or run `unbound login` first)');
+      const isMdm = hasRootPrivileges();
+
+      if (!discoveryKeyOpt) {
+        output.error('--discovery-key is required (or set UNBOUND_DISCOVERY_KEY env var)');
         process.exitCode = 1;
         return;
       }
-      if (!discoveryKeyOpt) {
-        output.error('--discovery-key is required (or set UNBOUND_DISCOVERY_KEY env var)');
+      // User scope needs a key or an existing login; MDM scope resolves the
+      // admin key below (it may come from a stored `unbound login` credential).
+      if (!isMdm && !apiKeyOpt && !config.isLoggedIn()) {
+        output.error('--api-key is required (or set UNBOUND_API_KEY env var, or run `unbound login` first)');
         process.exitCode = 1;
         return;
       }
@@ -73,84 +76,120 @@ Examples:
       let setupSucceeded = false;
       let discoverySucceeded = false;
       let discoveryDomain;
+      let skippedTools;
       try {
         // Persist URLs first, then login, then setup — order matters so the
         // login validates against the new backend and setup wires tools at the
         // new gateway. setUrls is atomic; a malformed URL throws before any
-        // disk write so the three URLs never end up out of sync.
+        // disk write so the three URLs never end up out of sync. Prefer the
+        // values we JUST persisted over the env-var-aware getters — a stale
+        // UNBOUND_*_URL from a prior shell session could otherwise silently
+        // shadow the user's explicit --*-url flag.
         const written = config.setUrls({
           backend: opts.backendUrl,
           frontend: opts.frontendUrl,
           gateway: opts.gatewayUrl,
         });
-        // Prefer the values we JUST persisted over the env-var-aware getters —
-        // a stale UNBOUND_*_URL from a prior shell session could otherwise
-        // silently shadow the user's explicit --*-url flag and route login or
-        // setup at the wrong tenant.
         const backendUrl = written.base_url || config.getBaseUrl();
         const frontendUrl = written.frontend_url || config.getFrontendUrl();
         const gatewayUrl = written.gateway_url || config.getGatewayUrl();
         discoveryDomain = opts.domain || backendUrl;
 
-        await ensureLoggedIn({
-          apiKey: apiKeyOpt,
-          baseUrl: written.base_url,
-          frontendUrl: written.frontend_url,
-        });
-        const apiKey = config.getApiKey();
+        if (isMdm) {
+          // Reuse the key stored by `unbound login` when no key was passed.
+          const adminApiKey = apiKeyOpt || config.getApiKey();
+          if (!adminApiKey) {
+            output.error('--api-key is required (or run `unbound login` first).');
+            process.exitCode = 1;
+            return;
+          }
 
-        console.log('');
-        output.info('Step 1/2: Installing tool bundle');
-        const { ok, skipped } = await runSetupAllBundle(apiKey, {
-          backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
-        });
-        if (!ok) return;
-        setupSucceeded = true;
+          console.log('');
+          output.info('Step 1/2: Installing MDM tool bundle (all users)');
+          const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
+            backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
+          });
+          if (!ok) return;
+          setupSucceeded = true;
 
-        console.log('');
-        output.info('Step 2/2: Running device discovery');
-        console.log('');
-        await runDiscoveryScan({ apiKey: discoveryKeyOpt, domain: discoveryDomain });
-        discoverySucceeded = true;
+          console.log('');
+          output.info('Step 2/2: Running device discovery');
+          console.log('');
+          await runDiscoveryScan({ apiKey: discoveryKeyOpt, domain: discoveryDomain });
+          discoverySucceeded = true;
+          skippedTools = skipped;
+        } else {
+          await ensureLoggedIn({
+            apiKey: apiKeyOpt,
+            baseUrl: written.base_url,
+            frontendUrl: written.frontend_url,
+          });
+          const apiKey = config.getApiKey();
+
+          console.log('');
+          output.info('Step 1/2: Installing tool bundle');
+          const { ok, skipped } = await runSetupAllBundle(apiKey, {
+            backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
+          });
+          if (!ok) return;
+          setupSucceeded = true;
+
+          console.log('');
+          output.info('Step 2/2: Running device discovery');
+          console.log('');
+          await runDiscoveryScan({ apiKey: discoveryKeyOpt, domain: discoveryDomain });
+          discoverySucceeded = true;
+          skippedTools = skipped;
+        }
 
         if (opts.setCron) {
           console.log('');
-          output.info('Setting up daily scheduled run');
           const { setupScheduledRun } = require('../scheduled');
-          await setupScheduledRun({
-            command: 'onboard',
-            apiKey: apiKeyOpt || apiKey,
-            discoveryKey: discoveryKeyOpt,
-            domain: discoveryDomain,
-            skipRunAtLoad: true,
-          });
+          if (isMdm) {
+            // Under sudo, the recurring job refreshes the device/tool inventory
+            // only — it does NOT re-push the full MDM tool bundle daily, and it
+            // stores the lower-privilege discovery key, not the admin key.
+            output.info('Setting up daily scheduled discovery scan');
+            await setupScheduledRun({
+              command: 'discover',
+              apiKey: discoveryKeyOpt,
+              domain: discoveryDomain,
+              skipRunAtLoad: true,
+            });
+          } else {
+            output.info('Setting up daily scheduled run');
+            await setupScheduledRun({
+              command: 'onboard',
+              apiKey: apiKeyOpt || config.getApiKey(),
+              discoveryKey: discoveryKeyOpt,
+              domain: discoveryDomain,
+              skipRunAtLoad: true,
+            });
+          }
         }
 
         console.log('');
-        output.success(skipped && skipped.length
+        output.success(skippedTools && skippedTools.length
           ? 'Onboarding complete — tools managed by MDM were skipped (see above)'
           : 'Onboarding complete');
       } catch (err) {
         if (!err.displayed) output.error(err.message);
+        const suffix = domainHintSuffix(discoveryDomain);
+        const sudo = isMdm ? 'sudo ' : '';
         if (discoverySucceeded && opts.setCron) {
           // Both setup and discovery completed; only the optional --set-cron
-          // step failed. Don't tell the user to re-run discovery — they already
-          // did. Tell them how to retry just the cron setup. discover schedule
-          // would install a discover-only cron, dropping the tool-bundle
-          // reinstall the user originally asked for, so the correct retry is
-          // re-running onboard with both keys.
-          const suffix = domainHintSuffix(discoveryDomain);
+          // step failed. Retry just the cron: under sudo the scheduled job is a
+          // discovery-only scan, so point at `discover --set-cron`; in user
+          // scope it re-runs the full onboard (the bundle reinstall is intended).
           console.error('  Setup and discovery completed successfully — only scheduled-run setup failed.');
-          console.error(`  Re-run cron setup with: unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron${suffix}`);
-        } else if (setupSucceeded && !discoverySucceeded) {
-          const suffix = domainHintSuffix(discoveryDomain);
-          const retryCmd = `unbound discover --api-key <DISCOVERY_KEY>${suffix}`;
-          console.error('  Tool setup completed successfully — only discovery failed.');
-          if (opts.setCron) {
-            console.error(`  Re-run with: unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --set-cron${suffix}`);
+          if (isMdm) {
+            console.error(`  Re-run just the scheduled scan with: sudo unbound discover --api-key <DISCOVERY_KEY> --set-cron${suffix}`);
           } else {
-            console.error(`  Re-run discovery only with: ${retryCmd}`);
+            console.error(`  Re-run cron setup with: unbound onboard --api-key <KEY> --discovery-key <DISCOVERY_KEY> --set-cron${suffix}`);
           }
+        } else if (setupSucceeded && !discoverySucceeded) {
+          console.error('  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;
       }
@@ -178,92 +217,6 @@ Examples:
         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.'
-    )
-    .option('--admin-api-key <key>', 'Admin API key for MDM enrollment (falls back to your stored `unbound login` key)')
-    .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
-    .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
-    .option('--backfill', 'Seed historical Claude Code / Codex / Copilot sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
-    .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())
-    .addOption(new Option('--gateway-url <url>', 'Override gateway 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(', ')}.
-  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.
---admin-api-key may be omitted to reuse the key stored by a prior
-\`unbound login\` (run sudo with HOME preserved so the stored key is found).
-
-For end-user onboarding (non-MDM), use \`unbound onboard\` instead.
-
-Examples:
-  $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>
-  $ sudo unbound onboard-mdm --discovery-key <DISCOVERY_KEY>   Reuse the stored \`unbound login\` key
-  $ sudo unbound onboard-mdm --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> --backfill
-`)
-    .action(async (opts) => {
-      let setupSucceeded = false;
-      let discoveryDomain;
-      try {
-        // Persist URLs first, then login, then setup — order matters so this
-        // MDM run wires tools at the new tenant. Prefer just-written values
-        // over env-var-aware getters so a stale UNBOUND_*_URL can't shadow the
-        // user's explicit --*-url flag.
-        const written = config.setUrls({
-          backend: opts.backendUrl,
-          gateway: opts.gatewayUrl,
-        });
-        const backendUrl = written.base_url || config.getBaseUrl();
-        const gatewayUrl = written.gateway_url || config.getGatewayUrl();
-        discoveryDomain = opts.domain || backendUrl;
-
-        checkRoot('onboard-mdm');
-
-        // Reuse the key stored by `unbound login` when --admin-api-key is omitted.
-        const adminApiKey = opts.adminApiKey || config.getApiKey();
-        if (!adminApiKey) {
-          output.error('--admin-api-key is required (or run `unbound login` first).');
-          process.exitCode = 1;
-          return;
-        }
-
-        console.log('');
-        output.info('Step 1/2: Installing MDM tool bundle');
-        const { ok, skipped } = await runMdmSetupAllBundle(adminApiKey, {
-          backendUrl, gatewayUrl, backfill: !!opts.backfill,
-        });
-        if (!ok) return;
-        setupSucceeded = true;
-
-        console.log('');
-        output.info('Step 2/2: Running device discovery');
-        console.log('');
-        await runDiscoveryScan({ apiKey: opts.discoveryKey, domain: discoveryDomain });
-
-        console.log('');
-        output.success(skipped && skipped.length
-          ? 'MDM onboarding complete — tools managed by MDM were skipped (see above)'
-          : 'MDM onboarding complete');
-      } catch (err) {
-        if (!err.displayed) output.error(err.message);
-        if (setupSucceeded) {
-          const suffix = domainHintSuffix(discoveryDomain);
-          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

@@ -45,10 +45,10 @@ const MDM_TOOLS = {
   'codex-gateway':            { label: 'Codex (gateway)',            script: 'codex/gateway/mdm/setup.py' },
 };
 
-// Default MDM tools for `unbound onboard-mdm` (subscription mode for Claude Code/Codex since only one can be active)
+// Default MDM tools for `sudo unbound onboard` (subscription mode for Claude Code/Codex since only one can be active)
 const MDM_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription', 'copilot'];
 
-// Tools for `unbound setup mdm --all` — identical to MDM_ALL_TOOLS today; split kept for future flexibility.
+// Tools for `sudo unbound setup --all` — identical to MDM_ALL_TOOLS today; split kept for future flexibility.
 const MDM_SETUP_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription', 'copilot'];
 
 // Default tools for `unbound onboard` (Cursor, Claude Code hooks, Codex hooks, Copilot hooks; no Gemini CLI).
@@ -73,7 +73,7 @@ const SETUP_TOOL_MAP = {
  * bundle (one mode per tool, no Gemini CLI), but clearing must remove EVERY
  * tool Unbound can configure — both modes plus Gemini CLI — so a prior
  * gateway-mode or Gemini setup isn't silently left behind. Mirrors the
- * `setup mdm --all` split.
+ * MDM `--all` split.
  */
 function resolveSetupAllTools(clear) {
   return clear ? Object.keys(SETUP_TOOL_MAP) : [...SETUP_ALL_TOOLS];
@@ -241,8 +241,9 @@ async function runPythonScriptWindows(scriptPath, args, { capture }) {
 /**
  * Builds the shared argv tail for setup.py invocations. Always passes the
  * tenant URL flags so the script's behavior is not sensitive to drift in its
- * own defaults. `mdm: true` skips --domain (frontend URL) since MDM scripts
- * have no browser-auth flow.
+ * own defaults. The frontend URL goes to non-MDM scripts as --domain (also
+ * their browser-auth host) and to MDM scripts as --frontend-url (persist-only,
+ * no auth flow). Either way it lands in ~/.unbound/config.json as frontend_url.
  */
 function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm, backfill } = {}) {
   // --clear runs no auth in the Python scripts, so the key may be absent. Omit
@@ -250,7 +251,7 @@ function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, m
   let args = apiKey ? `--api-key ${shellEscape(apiKey)}` : '';
   if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
   if (gatewayUrl) args += ` --gateway-url ${shellEscape(gatewayUrl)}`;
-  if (!mdm && frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
+  if (frontendUrl) args += mdm ? ` --frontend-url ${shellEscape(frontendUrl)}` : ` --domain ${shellEscape(frontendUrl)}`;
   if (clear) args += ' --clear';
   if (backfill) args += ' --backfill';
   return args.trim();
@@ -337,18 +338,6 @@ 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(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 ${commandHint} ...`);
-  }
-}
-
 /**
  * Returns true when the process has the privileges needed to touch system-level
  * (MDM) configuration. On Windows, `net session` succeeds only when elevated, so
@@ -454,9 +443,12 @@ function register(program) {
     .argument('[tools...]', 'Tools to set up')
     .description(
       'Configure AI coding tools to use Unbound as their API gateway. ' +
-      'Run with no arguments for interactive setup, or specify tools directly.'
+      'Run with no arguments for interactive setup, or specify tools directly. ' +
+      'Run with sudo to configure every user on the device (MDM/org scope); ' +
+      'without sudo, only the current user.'
     )
     .option('--api-key <key>', 'Authenticate with an API key (skips browser login)')
+    .addOption(new Option('--admin-api-key <key>', 'Alias for --api-key for MDM enrollment (back-compat)').hideHelp())
     .option('--clear', 'Remove Unbound configuration for the specified tools (no login or API key required)')
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
@@ -466,6 +458,10 @@ function register(program) {
     .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--gateway-url <url>', 'Override gateway URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
+Scope is chosen automatically from your privileges:
+  Run with sudo to configure every user on the device (MDM/org scope);
+  without sudo, only the current user is configured.
+
 Available tools:
   cursor                    Cursor IDE
   copilot                   GitHub Copilot
@@ -495,6 +491,11 @@ Examples:
   $ unbound setup --all                                    Set up the default bundle
   $ unbound setup --all --api-key <key>                    Login + set up the bundle
 
+  Configure all users on the device (MDM/org scope — run with sudo):
+  $ sudo unbound setup --all                               Configure all users (MDM)
+  $ sudo unbound setup cursor codex-subscription           Configure specific tools for all users
+  $ sudo unbound setup --clear --all                       Remove config for all users
+
   Seed historical sessions (Claude Code / Codex subscription mode + Copilot):
   $ unbound setup claude-code --subscription --backfill   Install hooks AND backfill local history
   $ unbound setup codex --subscription --backfill         Install hooks AND backfill local history
@@ -544,6 +545,95 @@ must update the MDM configuration.
         const frontendUrl = written.frontend_url || config.getFrontendUrl();
         const gatewayUrl = written.gateway_url || config.getGatewayUrl();
 
+        // Scope is auto-detected from privileges: with sudo/root we configure
+        // every user on the device (MDM scope); without it, just the current
+        // user. URLs were already persisted above and apply to both scopes.
+        const isMdm = hasRootPrivileges();
+        if (isMdm) {
+          const mdmToolNames = [...Object.keys(MDM_TOOLS), 'claude-code', 'codex'].join(', ');
+          const adminApiKey = opts.adminApiKey || opts.apiKey || config.getApiKey();
+          if (!opts.clear && !adminApiKey) {
+            output.error('--api-key is required to set up tools (or run `unbound login` first).');
+            process.exitCode = 1;
+            return;
+          }
+          if (opts.all && tools.length > 0) {
+            output.error('Cannot combine --all with specific tool names. Use one or the other.');
+            process.exitCode = 1;
+            return;
+          }
+          let toolNames;
+          if (opts.all) {
+            // --clear --all wipes every tool (both modes); setup --all uses the
+            // subscription-default bundle (can't enroll both modes at once).
+            toolNames = opts.clear ? Object.keys(MDM_TOOLS) : MDM_SETUP_ALL_TOOLS;
+          } else if (tools.length > 0) {
+            toolNames = tools;
+          } else {
+            output.error('Specify tools to set up, or use --all.');
+            console.error('  Available: ' + mdmToolNames);
+            process.exitCode = 1;
+            return;
+          }
+          // Bare claude-code/codex have no interactive mode prompt under MDM:
+          // --clear removes both modes; setup honors --gateway/--subscription
+          // (matching user scope) and defaults to subscription.
+          if (!opts.clear && opts.subscription && opts.gateway) {
+            output.error('Cannot use both --subscription and --gateway. Choose one.');
+            process.exitCode = 1;
+            return;
+          }
+          toolNames = [...new Set(toolNames.flatMap(name => {
+            const mode = MODE_TOOLS[name];
+            if (!mode) return [name];
+            if (opts.clear) return [mode.subscription, mode.gateway];
+            return opts.gateway ? [mode.gateway] : [mode.subscription];
+          }))];
+          const invalid = toolNames.filter(t => !MDM_TOOLS[t]);
+          if (invalid.length > 0) {
+            output.error(`Unknown tool(s): ${invalid.join(', ')}`);
+            console.error('  Available: ' + mdmToolNames);
+            process.exitCode = 1;
+            return;
+          }
+          if (!opts.clear) {
+            if (toolNames.includes('claude-code-subscription') && toolNames.includes('claude-code-gateway')) {
+              output.error('Cannot use both claude-code-subscription and claude-code-gateway. Choose one.');
+              process.exitCode = 1;
+              return;
+            }
+            if (toolNames.includes('codex-subscription') && toolNames.includes('codex-gateway')) {
+              output.error('Cannot use both codex-subscription and codex-gateway. Choose one.');
+              process.exitCode = 1;
+              return;
+            }
+          }
+          const resolvedTools = toolNames.map(name => ({ name, ...MDM_TOOLS[name] }));
+          console.log('');
+          if (opts.backfill) {
+            for (const tool of resolvedTools) {
+              if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+            }
+          }
+          const { ok } = await runBatch(
+            resolvedTools,
+            (tool) => {
+              const toolArgs = buildScriptArgs(adminApiKey, {
+                backendUrl,
+                frontendUrl,
+                gatewayUrl,
+                clear: opts.clear,
+                mdm: true,
+                backfill: opts.backfill && scriptSupportsBackfill(tool.script),
+              });
+              return runScriptPiped(tool.script, toolArgs);
+            },
+            { clear: opts.clear, summary: opts.clear ? 'All tools cleared' : 'All tools configured' }
+          );
+          if (!ok) return;
+          return;
+        }
+
         // Clearing config needs no credentials — the setup scripts remove
         // files without calling the API — so don't force a login for --clear.
         if (!opts.clear) {
@@ -746,166 +836,6 @@ must update the MDM configuration.
       }
     });
 
-  // --- MDM setup ---
-
-  // Bare claude-code/codex are accepted too: with --clear they remove both
-  // modes; for setup they default to subscription (MDM has no mode prompt).
-  const mdmToolNames = [...Object.keys(MDM_TOOLS), 'claude-code', 'codex'].join(', ');
-
-  setup
-    .command('mdm')
-    .description(
-      'MDM setup: configure all users on this device. Requires root. ' +
-      'Used by organization admins to enroll devices via MDM.'
-    )
-    .argument('[tools...]', 'Tools to set up: ' + mdmToolNames)
-    .option('--admin-api-key <key>', 'Admin API key for MDM enrollment (falls back to your stored `unbound login` key; not required with --clear)')
-    .option('--clear', 'Remove Unbound configuration for the specified tools (no API key required)')
-    .option('--all', 'Set up all available tools')
-    .option('--backfill', 'Seed historical Claude Code / Codex / Copilot sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
-    .addHelpText('after', `
-Available tools:
-  cursor                    Cursor IDE
-  copilot                   GitHub Copilot
-  claude-code-subscription  Claude Code with your own subscription (hooks only)
-  claude-code-gateway       Claude Code with Unbound as AI provider
-  claude-code               Both Claude Code modes (clears both; sets up subscription)
-  gemini-cli                Gemini CLI
-  codex-subscription        Codex with your own subscription (hooks only)
-  codex-gateway             Codex with Unbound as AI provider
-  codex                     Both Codex modes (clears both; sets up subscription)
-
-Note: claude-code-subscription and claude-code-gateway are mutually exclusive when
-      setting up; same for codex. Bare claude-code/codex set up subscription mode.
-      When using --all, subscription mode is used by default for Claude Code and Codex.
-
-Setup examples (need an admin key — pass --admin-api-key, or omit it to reuse the
-key stored by a prior \`unbound login\`):
-  $ sudo unbound setup mdm --admin-api-key KEY cursor
-  $ sudo unbound setup mdm --admin-api-key KEY cursor claude-code-subscription codex-subscription
-  $ sudo unbound setup mdm --admin-api-key KEY --all
-  $ sudo unbound setup mdm --all                           Reuse the stored \`unbound login\` key
-  $ sudo unbound setup mdm --admin-api-key KEY claude-code-subscription --backfill
-                                                           Install hooks AND backfill local history
-  $ sudo unbound setup mdm --admin-api-key KEY copilot --backfill
-                                                           Install Copilot hooks AND backfill local history
-
-Clear examples (no API key required):
-  $ sudo unbound setup mdm --clear cursor
-  $ sudo unbound setup mdm --clear claude-code              Clears BOTH Claude Code modes
-  $ sudo unbound setup mdm --clear codex                    Clears BOTH Codex modes
-  $ sudo unbound setup mdm --clear --all                    Clears every tool
-`)
-    .action(async (tools, opts, command) => {
-      try {
-        checkRoot();
-        // --all and --clear are defined on both this command and the parent `setup` command;
-        // --backend-url, --frontend-url, --gateway-url are defined only on the parent `setup` command.
-        // Use optsWithGlobals() so they all work regardless of position relative to `mdm`.
-        const globalOpts = command.optsWithGlobals();
-        // Clearing removes config without calling the API, so a key is only
-        // required when actually enrolling tools. Fall back to the API key
-        // stored by `unbound login` so admins who are already logged in don't
-        // have to pass --admin-api-key again.
-        const adminApiKey = opts.adminApiKey || config.getApiKey();
-        if (!globalOpts.clear && !adminApiKey) {
-          output.error('--admin-api-key is required to set up tools (or run `unbound login` first).');
-          process.exitCode = 1;
-          return;
-        }
-        // Persist URLs first so this MDM run wires tools at the new tenant
-        // and any subsequent non-MDM command on the same machine inherits.
-        // Prefer just-persisted values over env-var-aware getters so a stale
-        // UNBOUND_*_URL can't shadow the explicit --*-url flag.
-        const written = config.setUrls({
-          backend: globalOpts.backendUrl,
-          gateway: globalOpts.gatewayUrl,
-        });
-        const backendUrl = written.base_url || config.getBaseUrl();
-        const gatewayUrl = written.gateway_url || config.getGatewayUrl();
-
-        if (globalOpts.all && tools.length > 0) {
-          output.error('Cannot combine --all with specific tool names. Use one or the other.');
-          process.exitCode = 1;
-          return;
-        }
-
-        let toolNames;
-        if (globalOpts.all) {
-          // --clear --all wipes every tool, including both Claude Code/Codex modes.
-          // Setup --all uses the subscription-default bundle (can't enroll both modes).
-          toolNames = globalOpts.clear ? Object.keys(MDM_TOOLS) : MDM_SETUP_ALL_TOOLS;
-        } else if (tools.length > 0) {
-          toolNames = tools;
-        } else {
-          output.error('Specify tools to set up, or use --all.');
-          console.error('  Available: ' + mdmToolNames);
-          process.exitCode = 1;
-          return;
-        }
-
-        // Expand bare claude-code/codex (MDM has no interactive mode prompt):
-        // --clear removes both modes; setup defaults to subscription, matching --all.
-        toolNames = [...new Set(toolNames.flatMap(name => {
-          const mode = MODE_TOOLS[name];
-          if (!mode) return [name];
-          return globalOpts.clear ? [mode.subscription, mode.gateway] : [mode.subscription];
-        }))];
-
-        const invalid = toolNames.filter(t => !MDM_TOOLS[t]);
-        if (invalid.length > 0) {
-          output.error(`Unknown tool(s): ${invalid.join(', ')}`);
-          console.error('  Available: ' + mdmToolNames);
-          process.exitCode = 1;
-          return;
-        }
-
-        // Mode mutual-exclusivity only applies when setting up — clearing both
-        // modes at once is valid (and is what bare claude-code/codex --clear does).
-        if (!globalOpts.clear) {
-          if (toolNames.includes('claude-code-subscription') && toolNames.includes('claude-code-gateway')) {
-            output.error('Cannot use both claude-code-subscription and claude-code-gateway. Choose one.');
-            process.exitCode = 1;
-            return;
-          }
-
-          if (toolNames.includes('codex-subscription') && toolNames.includes('codex-gateway')) {
-            output.error('Cannot use both codex-subscription and codex-gateway. Choose one.');
-            process.exitCode = 1;
-            return;
-          }
-        }
-
-        const resolvedTools = toolNames.map(name => ({ name, ...MDM_TOOLS[name] }));
-        console.log('');
-
-        if (globalOpts.backfill) {
-          for (const tool of resolvedTools) {
-            if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
-          }
-        }
-
-        const { ok } = await runBatch(
-          resolvedTools,
-          (tool) => {
-            const toolArgs = buildScriptArgs(adminApiKey, {
-              backendUrl,
-              gatewayUrl,
-              clear: globalOpts.clear,
-              mdm: true,
-              backfill: globalOpts.backfill && scriptSupportsBackfill(tool.script),
-            });
-            return runScriptPiped(tool.script, toolArgs);
-          },
-          { clear: globalOpts.clear, summary: globalOpts.clear ? 'All tools cleared' : 'All tools configured' }
-        );
-        if (!ok) return;
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
   // --- Full uninstall ---
 
   program
@@ -1030,7 +960,7 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { backendUrl, gatewayUrl, backfill = false } = {}) {
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
   const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
   if (backfill) {
     for (const tool of resolvedTools) {
@@ -1039,7 +969,7 @@ async function runMdmSetupAllBundle(adminApiKey, { backendUrl, gatewayUrl, backf
   }
   return runBatch(resolvedTools, (tool) => {
     const args = buildScriptArgs(adminApiKey, {
-      backendUrl, gatewayUrl, mdm: true,
+      backendUrl, frontendUrl, gatewayUrl, mdm: true,
       backfill: backfill && scriptSupportsBackfill(tool.script),
     });
     return runScriptPiped(tool.script, args);
@@ -1050,7 +980,7 @@ module.exports = {
   register,
   runSetupAllBundle,
   runMdmSetupAllBundle,
-  checkRoot,
+  hasRootPrivileges,
   ALL_TOOLS,
   MDM_ALL_TOOLS,
   buildScriptArgs,

package/src/index.js

@@ -44,9 +44,9 @@ AUTHENTICATION
   Or set URLs separately (any time):
   $ unbound config urls <gateway-url> <frontend-url> <backend-url>
 
-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>
+ONBOARDING (one-step install + discover; scope auto-detected from sudo)
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>         Current user
+  $ sudo unbound onboard --api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY>   All users (MDM)
 
 TOOL SETUP
   $ unbound setup                          Select and install multiple tools interactively
@@ -85,11 +85,11 @@ TOOL SETUP
   $ sudo unbound nuke                      Wipe everything on the device (MDM + user)
   $ unbound nuke                           Wipe just your tools + credentials (no sudo)
 
-MDM SETUP (admin, requires root)
-  $ sudo unbound setup mdm --admin-api-key KEY --all
-  $ sudo unbound setup mdm --admin-api-key KEY cursor copilot codex-subscription
-  $ sudo unbound setup mdm --admin-api-key KEY claude-code-subscription codex-subscription gemini-cli
-  $ sudo unbound setup mdm --clear cursor codex-subscription   (no API key needed to clear)
+MDM SETUP (all users on the device — run setup with sudo)
+  $ sudo unbound setup --all --api-key KEY
+  $ sudo unbound setup cursor copilot codex-subscription --api-key KEY
+  $ sudo unbound setup claude-code-subscription codex-subscription gemini-cli --api-key KEY
+  $ sudo unbound setup --clear cursor codex-subscription       (no API key needed to clear)
 
 MDM AI TOOLS DISCOVERY
   --domain defaults to the configured backend URL (set via "unbound config set-backend-url")

package/test/command-merge.test.js

@@ -0,0 +1,44 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const setup = require('../src/commands/setup');
+
+// WEB-4757: `onboard`/`setup` are single commands; MDM vs user scope is
+// auto-detected from sudo/root, so the separate `onboard-mdm` and `setup mdm`
+// commands no longer exist. These guard against a regression that re-splits or
+// drops them.
+
+function buildProgram() {
+  const program = new Command();
+  require('../src/commands/onboard').register(program);
+  setup.register(program);
+  return program;
+}
+
+test('WEB-4757: onboard/setup are single top-level commands, no -mdm variants', () => {
+  const top = buildProgram().commands.map((c) => c.name());
+  assert.ok(top.includes('onboard'), 'onboard is registered');
+  assert.ok(top.includes('setup'), 'setup is registered');
+  assert.ok(!top.includes('onboard-mdm'), 'onboard-mdm is gone');
+});
+
+test('WEB-4757: setup has no `mdm` subcommand; onboard keeps `unschedule`', () => {
+  const program = buildProgram();
+  const setupCmd = program.commands.find((c) => c.name() === 'setup');
+  const onboardCmd = program.commands.find((c) => c.name() === 'onboard');
+  assert.ok(!setupCmd.commands.some((c) => c.name() === 'mdm'), 'setup mdm subcommand is gone');
+  assert.ok(onboardCmd.commands.some((c) => c.name() === 'unschedule'), 'onboard unschedule is kept');
+});
+
+test('WEB-4757: onboard/setup accept --admin-api-key as a back-compat alias', () => {
+  const program = buildProgram();
+  const onboardCmd = program.commands.find((c) => c.name() === 'onboard');
+  const setupCmd = program.commands.find((c) => c.name() === 'setup');
+  assert.ok(onboardCmd.options.some((o) => o.long === '--admin-api-key'), 'onboard --admin-api-key');
+  assert.ok(setupCmd.options.some((o) => o.long === '--admin-api-key'), 'setup --admin-api-key');
+});
+
+test('WEB-4757: scope helper is exported; the throwing checkRoot is gone', () => {
+  assert.equal(typeof setup.hasRootPrivileges, 'function');
+  assert.equal(setup.checkRoot, undefined);
+});

package/test/onboard-scope.test.js

@@ -0,0 +1,114 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+
+// WEB-4757: scope is auto-detected from sudo/root. These tests verify the
+// permission primitive (hasRootPrivileges) and that `onboard` actually routes
+// to the MDM bundle when root and the user bundle when not — without touching
+// the network or running any setup script (all downstream deps are stubbed).
+
+// ---- 1. The sudo permission check itself ----
+test('hasRootPrivileges: true when effective uid is 0 (sudo/root)', () => {
+  delete require.cache[require.resolve('../src/commands/setup')];
+  const setup = require('../src/commands/setup');
+  const orig = process.getuid;
+  try {
+    process.getuid = () => 0;
+    assert.equal(setup.hasRootPrivileges(), true);
+  } finally {
+    process.getuid = orig;
+  }
+});
+
+test('hasRootPrivileges: false when effective uid is not 0 (no sudo)', () => {
+  delete require.cache[require.resolve('../src/commands/setup')];
+  const setup = require('../src/commands/setup');
+  const orig = process.getuid;
+  try {
+    process.getuid = () => 1000;
+    assert.equal(setup.hasRootPrivileges(), false);
+  } finally {
+    process.getuid = orig;
+  }
+});
+
+// ---- 2. onboard routes by detected scope ----
+// Reloads the module graph with stubbed deps so we can observe which bundle
+// helper the single `onboard` command invokes.
+async function runOnboard(isRoot, { setCron = false } = {}) {
+  for (const m of [
+    '../src/commands/onboard',
+    '../src/commands/setup',
+    '../src/commands/discover',
+    '../src/auth',
+    '../src/config',
+    '../src/output',
+    '../src/scheduled',
+  ]) {
+    delete require.cache[require.resolve(m)];
+  }
+
+  const calls = { mdm: 0, user: 0, discovery: 0, loggedIn: 0, cron: null };
+  const setup = require('../src/commands/setup');
+  const discover = require('../src/commands/discover');
+  const auth = require('../src/auth');
+  const config = require('../src/config');
+  const output = require('../src/output');
+  const scheduled = require('../src/scheduled');
+
+  setup.hasRootPrivileges = () => isRoot;
+  setup.runMdmSetupAllBundle = async () => { calls.mdm++; return { ok: true, skipped: [] }; };
+  setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
+  discover.runDiscoveryScan = async () => { calls.discovery++; };
+  auth.ensureLoggedIn = async () => { calls.loggedIn++; };
+  scheduled.setupScheduledRun = async (o) => { calls.cron = o; };
+  config.setUrls = () => ({});
+  config.getApiKey = () => 'resolved-key';
+  config.getBaseUrl = () => 'https://b.acme';
+  config.getFrontendUrl = () => 'https://f.acme';
+  config.getGatewayUrl = () => 'https://g.acme';
+  config.isLoggedIn = () => true;
+  for (const k of ['info', 'success', 'error', 'warn']) output[k] = () => {};
+
+  const { register } = require('../src/commands/onboard');
+  const program = new Command();
+  program.exitOverride();
+  register(program);
+  const argv = ['node', 'unbound', 'onboard', '--api-key', 'k', '--discovery-key', 'd'];
+  if (setCron) argv.push('--set-cron');
+  await program.parseAsync(argv);
+  return calls;
+}
+
+test('onboard with sudo/root → installs the MDM bundle (all users), no login', async () => {
+  const calls = await runOnboard(true);
+  assert.equal(calls.mdm, 1, 'MDM bundle installed');
+  assert.equal(calls.user, 0, 'user bundle NOT installed');
+  assert.equal(calls.loggedIn, 0, 'MDM scope does not run ensureLoggedIn');
+  assert.equal(calls.discovery, 1, 'discovery still runs');
+});
+
+test('onboard without sudo → logs in and installs the user bundle', async () => {
+  const calls = await runOnboard(false);
+  assert.equal(calls.user, 1, 'user bundle installed');
+  assert.equal(calls.mdm, 0, 'MDM bundle NOT installed');
+  assert.equal(calls.loggedIn, 1, 'user scope runs ensureLoggedIn');
+  assert.equal(calls.discovery, 1, 'discovery still runs');
+});
+
+// --set-cron under sudo schedules discovery only (not a daily full MDM
+// re-install) and stores the discovery key, never the admin key.
+test('onboard --set-cron with sudo → schedules discovery-only with the discovery key', async () => {
+  const calls = await runOnboard(true, { setCron: true });
+  assert.ok(calls.cron, 'a scheduled run was set up');
+  assert.equal(calls.cron.command, 'discover', 'schedules discover, not full onboard');
+  assert.equal(calls.cron.apiKey, 'd', 'uses the discovery key, not the admin key');
+  assert.equal(calls.cron.discoveryKey, undefined, 'no separate admin/discovery key passed');
+});
+
+test('onboard --set-cron without sudo → schedules the full onboard run', async () => {
+  const calls = await runOnboard(false, { setCron: true });
+  assert.ok(calls.cron, 'a scheduled run was set up');
+  assert.equal(calls.cron.command, 'onboard', 'user scope keeps the full onboard cron');
+  assert.equal(calls.cron.discoveryKey, 'd', 'discovery key forwarded for the onboard cron');
+});

package/test/setup-args.test.js

@@ -70,14 +70,16 @@ test('scriptSupportsBackfill: cursor and gateway-mode scripts are unsupported',
   assert.ok(!scriptSupportsBackfill('gemini-cli/gateway/setup.py'));
 });
 
-// MDM scripts have no browser-auth flow, so --domain (frontend URL) is
-// suppressed even when a frontendUrl is supplied.
-test('buildScriptArgs: mdm:true suppresses --domain even with frontendUrl', () => {
+// MDM scripts have no browser-auth flow, so the frontend URL goes via
+// --frontend-url (persist-only), never --domain. It must still be passed so
+// frontend_url lands in each user's ~/.unbound/config.json.
+test('buildScriptArgs: mdm:true passes frontend as --frontend-url, not --domain', () => {
   const args = buildScriptArgs('sk-x', {
     mdm: true,
     frontendUrl: 'https://gateway.acme.com',
   });
   assert.ok(!args.includes('--domain'), args);
+  assert.ok(args.includes("--frontend-url 'https://gateway.acme.com'"), args);
 });
 
 test('buildScriptArgs: non-mdm includes --domain when frontendUrl passed', () => {