unbound-cli 1.1.1 → 1.1.3

package/package.json

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

package/src/auth.js

@@ -7,6 +7,7 @@ const { URL } = require('url');
 const config = require('./config');
 const output = require('./output');
 const api = require('./api');
+const { getDeviceSerial } = require('./device-serial');
 
 /**
  * Opens the browser for authentication and waits for the callback.
@@ -117,7 +118,13 @@ async function loginWithApiKey(apiKey, { baseUrl } = {}) {
   const spin = output.spinner('Authenticating...');
   let response;
   try {
-    response = await api.get('/api/v1/users/privileges/', { apiKey, baseUrl });
+    // Report this machine's serial so the backend can map the device to the
+    // authenticated user. Optional + best-effort: omitted when undeterminable.
+    // Awaited (not sync) so the probe never blocks the spinner on a cache miss.
+    const deviceSerial = await getDeviceSerial();
+    response = await api.get('/api/v1/users/privileges/', {
+      apiKey, baseUrl, query: { device_serial: deviceSerial },
+    });
   } catch (err) {
     let msg;
     if (err.statusCode === 401 || err.statusCode === 403) {

package/src/commands/login.js

@@ -3,6 +3,7 @@ const config = require('../config');
 const output = require('../output');
 const api = require('../api');
 const { loginWithBrowser, loginWithApiKey } = require('../auth');
+const { getDeviceSerial } = require('../device-serial');
 
 function register(program) {
   program
@@ -79,7 +80,10 @@ Examples:
           // Validate the just-stored key against the explicit backend if one
           // was just persisted; otherwise fall back to the env-var-aware
           // getter. api.get reads the stored key from config internally.
-          await api.get('/api/v1/users/privileges/', { baseUrl: explicitBaseUrl });
+          const deviceSerial = await getDeviceSerial();
+          await api.get('/api/v1/users/privileges/', {
+            baseUrl: explicitBaseUrl, query: { device_serial: deviceSerial },
+          });
         }
 
         const cfg = config.readConfig();

package/src/commands/onboard.js

@@ -23,7 +23,7 @@ function register(program) {
       'One-step user onboarding: install the default AI tools bundle and run device discovery. ' +
       'Runs `setup --all` followed by `discover` in a single command.'
     )
-    .option('--api-key <key>', 'User API key (or set UNBOUND_API_KEY env var)')
+    .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('--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')
@@ -33,7 +33,8 @@ function register(program) {
     .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.
+  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(', ')}.
   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.
@@ -56,8 +57,10 @@ Examples:
     .action(async (opts) => {
       const apiKeyOpt = opts.apiKey || process.env.UNBOUND_API_KEY;
       const discoveryKeyOpt = opts.discoveryKey || process.env.UNBOUND_DISCOVERY_KEY;
-      if (!apiKeyOpt) {
-        output.error('--api-key is required (or set UNBOUND_API_KEY env var)');
+      // 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)');
         process.exitCode = 1;
         return;
       }
@@ -116,7 +119,7 @@ Examples:
           const { setupScheduledRun } = require('../scheduled');
           await setupScheduledRun({
             command: 'onboard',
-            apiKey: apiKeyOpt,
+            apiKey: apiKeyOpt || apiKey,
             discoveryKey: discoveryKeyOpt,
             domain: discoveryDomain,
             skipRunAtLoad: true,
@@ -182,7 +185,7 @@ Examples:
       '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')
+    .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)')
@@ -196,11 +199,14 @@ Runs the full MDM onboarding flow for device enrollment:
 
 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) => {
@@ -221,9 +227,17 @@ Examples:
 
         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 = await runMdmSetupAllBundle(opts.adminApiKey, {
+        const ok = await runMdmSetupAllBundle(adminApiKey, {
           backendUrl, gatewayUrl, backfill: !!opts.backfill,
         });
         if (!ok) return;

package/src/commands/setup.js

@@ -510,7 +510,7 @@ requires authentication.
         // No tools specified → interactive multi-select (existing flow)
         if (tools.length === 0) {
           const selected = await output.multiSelect(
-            'Select tools to set up with Unbound:',
+            opts.clear ? 'Select tools to remove Unbound configuration for:' : 'Select tools to set up with Unbound:',
             SETUP_TOOLS
           );
 
@@ -530,14 +530,15 @@ requires authentication.
           const ok = await runBatch(selectedTools, (tool) => {
             const toolArgs = buildScriptArgs(apiKey, {
               ...urlOpts,
+              clear: opts.clear,
               backfill: opts.backfill && scriptSupportsBackfill(tool.script),
             });
             return runScriptPiped(tool.script, toolArgs);
-          });
+          }, { clear: opts.clear });
           if (!ok) return;
 
           console.log('');
-          output.success('All tools configured');
+          output.success(opts.clear ? 'All tools cleared' : 'All tools configured');
           return;
         }
 
@@ -705,7 +706,7 @@ requires authentication.
       '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 (not required with --clear)')
+    .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)')
@@ -725,10 +726,12 @@ Note: claude-code-subscription and claude-code-gateway are mutually exclusive wh
       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 (require --admin-api-key):
+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
@@ -748,9 +751,12 @@ Clear examples (no API key required):
         // 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.
-        if (!globalOpts.clear && !opts.adminApiKey) {
-          output.error('--admin-api-key is required to set up tools.');
+        // 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;
         }
@@ -829,7 +835,7 @@ Clear examples (no API key required):
         const ok = await runBatch(
           resolvedTools,
           (tool) => {
-            const toolArgs = buildScriptArgs(opts.adminApiKey, {
+            const toolArgs = buildScriptArgs(adminApiKey, {
               backendUrl,
               gatewayUrl,
               clear: globalOpts.clear,

package/src/commands/status.js

@@ -1,6 +1,7 @@
 const config = require('../config');
 const api = require('../api');
 const output = require('../output');
+const { getDeviceSerial } = require('../device-serial');
 
 function register(program) {
   program
@@ -36,7 +37,10 @@ Examples:
         if (loggedIn) {
           const spin = output.spinner('Checking API connectivity...');
           try {
-            const privileges = await api.get('/api/v1/users/privileges/');
+            const deviceSerial = await getDeviceSerial();
+            const privileges = await api.get('/api/v1/users/privileges/', {
+              query: { device_serial: deviceSerial },
+            });
             config.backfillUserInfo(privileges);
             spin.stop();
             connectivity = 'Connected';

package/src/commands/whoami.js

@@ -1,6 +1,7 @@
 const config = require('../config');
 const api = require('../api');
 const output = require('../output');
+const { getDeviceSerial } = require('../device-serial');
 
 function roleFromPrivileges(privileges) {
   if (privileges.is_admin) return 'Admin';
@@ -34,7 +35,10 @@ Examples:
       const cfg = config.readConfig();
       const spin = output.spinner('Fetching user info...');
       try {
-        const privileges = await api.get('/api/v1/users/privileges/');
+        const deviceSerial = await getDeviceSerial();
+        const privileges = await api.get('/api/v1/users/privileges/', {
+          query: { device_serial: deviceSerial },
+        });
         spin.stop();
         config.backfillUserInfo(privileges);
 

package/src/device-serial.js

@@ -0,0 +1,159 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const { CONFIG_DIR } = require('./config');
+
+const execFileAsync = promisify(execFile);
+
+// Shared with the endpoint hooks: they cache the same value under this key so a
+// machine reports one identity across the CLI and the installed hooks.
+const IDENTITY_CACHE_FILE = path.join(CONFIG_DIR, 'identity.json');
+const PROBE_TIMEOUT_MS = 3000;
+
+// DMI/BIOS serial fields are often unset on VMs and OEM boards and come back as a
+// shared sentinel (with a zero exit code), which would map many machines onto one
+// fake serial. Treat these as "no serial" and fall through. Mirrors the hooks +
+// discovery scanner so all three agree on a machine's identity.
+const PLACEHOLDER_SERIALS = new Set([
+  '', '0', '00000000', '000000000', '0000000000', 'none', 'na', 'n/a',
+  'unknown', 'default', 'default string', 'to be filled by o.e.m.',
+  'to be filled by oem', 'system serial number', 'serial number',
+  'not applicable', 'not specified', 'not available', 'oem', 'o.e.m.',
+  'invalid', '123456789', 'xxxxxxxx',
+]);
+
+// Best-effort serial is intentionally non-fatal, so failures are swallowed rather
+// than surfaced to the user. Set UNBOUND_DEBUG=1 to trace why a serial was omitted.
+function debug(msg) {
+  if (process.env.UNBOUND_DEBUG) {
+    try { process.stderr.write(`[unbound] device-serial: ${msg}\n`); } catch { /* ignore */ }
+  }
+}
+
+function isValidSerial(value) {
+  return typeof value === 'string'
+    && value.trim() !== ''
+    && !PLACEHOLDER_SERIALS.has(value.trim().toLowerCase());
+}
+
+// Run a probe command asynchronously so the event loop (and the caller's spinner)
+// stays alive during the probe. Bounded by a timeout, never throws, resolves to
+// stdout or null (nonzero exit / timeout / missing binary all map to null).
+async function run(cmd, args) {
+  try {
+    const { stdout } = await execFileAsync(cmd, args, {
+      timeout: PROBE_TIMEOUT_MS, windowsHide: true, encoding: 'utf8',
+    });
+    return typeof stdout === 'string' ? stdout : null;
+  } catch (err) {
+    debug(`probe '${cmd}' failed: ${err && err.message}`);
+    return null;
+  }
+}
+
+// Best-effort hardware serial, mirroring the MDM setup scripts and discovery
+// scanner. Filters OEM/VM placeholders so two machines never collide on the same
+// fake serial, falling through to a stable per-install id (machine-id / MachineGuid).
+async function probeSerial() {
+  const platform = os.platform();
+
+  if (platform === 'darwin') {
+    const out = await run('system_profiler', ['SPHardwareDataType']);
+    if (out) {
+      for (const line of out.split('\n')) {
+        if (line.includes('Serial Number')) {
+          const idx = line.indexOf(': ');
+          if (idx !== -1) {
+            const value = line.slice(idx + 2).trim();
+            if (isValidSerial(value)) return value;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  if (platform === 'linux') {
+    const dmi = await run('dmidecode', ['-s', 'system-serial-number']); // needs root; falls through otherwise
+    if (dmi && isValidSerial(dmi)) return dmi.trim();
+    for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+      try {
+        const value = fs.readFileSync(p, 'utf8').trim();
+        if (isValidSerial(value)) return value;
+      } catch {
+        // try the next path
+      }
+    }
+    return null;
+  }
+
+  if (platform === 'win32') {
+    const bios = await run('powershell', ['-NoProfile', '-Command',
+      '(Get-CimInstance -ClassName Win32_BIOS).SerialNumber']);
+    if (bios && isValidSerial(bios)) return bios.trim();
+    const guid = await run('powershell', ['-NoProfile', '-Command',
+      "(Get-ItemProperty 'HKLM:\\SOFTWARE\\Microsoft\\Cryptography').MachineGuid"]);
+    if (guid && isValidSerial(guid)) return guid.trim();
+    return null;
+  }
+
+  debug(`unsupported platform: ${platform}`);
+  return null;
+}
+
+function readCache() {
+  try {
+    const data = JSON.parse(fs.readFileSync(IDENTITY_CACHE_FILE, 'utf8'));
+    if (data && typeof data === 'object') return data;
+  } catch (err) {
+    if (err.code !== 'ENOENT') debug(`cache read failed: ${err.message}`);
+  }
+  return {};
+}
+
+// Merge + atomic write so a torn file can't corrupt the cache the hooks share.
+function writeCache(data) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    const tmp = path.join(CONFIG_DIR, `.identity.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    fs.renameSync(tmp, IDENTITY_CACHE_FILE);
+  } catch (err) {
+    // an unwritable cache is fine — we still return the probed value
+    debug(`cache write failed: ${err.message}`);
+  }
+}
+
+/**
+ * Best-effort hardware serial, shared with the endpoint hooks via
+ * ~/.unbound/identity.json. Reads the cache first (instant); probes asynchronously
+ * and persists only when missing, so the caller's spinner keeps animating. Never
+ * throws — resolves to null when the serial can't be determined, so callers simply
+ * omit it from the request. Set UNBOUND_DEBUG=1 to trace omissions.
+ */
+async function getDeviceSerial() {
+  try {
+    const data = readCache();
+    // Validate the cached value, not just its presence — an older CLI or hook could
+    // have persisted a placeholder (e.g. "System Serial Number"). Treat junk as a
+    // miss and re-probe, so a polluted cache self-heals instead of leaking a sentinel.
+    const cached = data.device_serial;
+    if (isValidSerial(cached)) return cached.trim();
+
+    const serial = await probeSerial();
+    if (serial) {
+      data.device_serial = serial;
+      writeCache(data);
+    } else {
+      debug('no serial could be determined; omitting device_serial');
+    }
+    return serial || null;
+  } catch (err) {
+    debug(`getDeviceSerial failed: ${err && err.message}`);
+    return null;
+  }
+}
+
+module.exports = { getDeviceSerial, isValidSerial };

package/test/device-serial.test.js

@@ -0,0 +1,37 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { isValidSerial, getDeviceSerial } = require('../src/device-serial');
+
+test('isValidSerial: accepts real hardware serials', () => {
+  assert.equal(isValidSerial('M6KYTR4M2Q'), true);
+  assert.equal(isValidSerial('DP4Y2K37VV'), true);
+  // Parallels VM serial (spaces are part of the value, not a separator)
+  assert.equal(isValidSerial('Parallels-74 09 F2 8A 55 09 40 3D AA 13 19 BD CC 96 0F 0B'), true);
+});
+
+test('isValidSerial: rejects OEM/VM placeholder sentinels', () => {
+  for (const junk of [
+    '', '0', '00000000', 'To Be Filled By O.E.M.', 'System Serial Number',
+    'Default String', 'None', 'N/A', 'unknown', 'invalid', '123456789',
+  ]) {
+    assert.equal(isValidSerial(junk), false, `expected placeholder rejected: ${JSON.stringify(junk)}`);
+  }
+});
+
+test('isValidSerial: placeholder match is case- and whitespace-insensitive', () => {
+  assert.equal(isValidSerial('  to be filled by o.e.m.  '), false);
+  assert.equal(isValidSerial('SYSTEM SERIAL NUMBER'), false);
+});
+
+test('isValidSerial: rejects non-string input', () => {
+  assert.equal(isValidSerial(null), false);
+  assert.equal(isValidSerial(undefined), false);
+  assert.equal(isValidSerial(12345), false);
+  assert.equal(isValidSerial({}), false);
+});
+
+test('getDeviceSerial: is async and resolves to a string or null without throwing', async () => {
+  const result = await getDeviceSerial();
+  assert.ok(result === null || (typeof result === 'string' && result.length > 0),
+    `expected string|null, got ${typeof result}: ${JSON.stringify(result)}`);
+});