unbound-cli 1.16.25 → 1.17.0

package/README.md

@@ -14,8 +14,8 @@ npm install -g unbound-cli
 # Login via browser
 unbound login
 
-# Or login with an API key (for CI/CD or headless environments)
-unbound login --api-key <your-api-key>
+# Or login with your CLI key from Configure → API Access (for CI/CD or headless environments)
+unbound login --api-key <your-cli-key>
 
 # Check your status, role, and connected tools
 unbound status
@@ -54,7 +54,7 @@ Only your API key is needed. Run with `sudo` to let the discovery step scan all
 | `unbound login` | Sign in via browser |
 | `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 logout` | Remove the CLI key from the OS keychain |
 | `unbound status` | Show CLI status, role, and connected tools |
 | `unbound doctor` | Diagnose per-tool health (config, hook, env) and API key |
 
@@ -286,6 +286,8 @@ unbound config show
 
 Bare hostnames are accepted (`backend.acme.com` becomes `https://backend.acme.com`). Each URL also accepts a per-process override via env var.
 
+**API keys.** The CLI key (Configure → API Access) can read your organization's data, so `unbound login` keeps it in the OS keychain: macOS Keychain, Windows Credential Manager, or the Linux Secret Service (`secret-tool`). Without a keychain, set `UNBOUND_TOKEN` instead; the CLI reads it only when the keychain has no key. The send-only device key that tools and hooks use is stored as `api_key` in `~/.unbound/config.json`. `unbound setup` fetches it from your login, and `--api-key` takes a device key. Run `unbound login` again after upgrading.
+
 **Backend URL priority** (highest to lowest):
 1. `UNBOUND_API_URL` environment variable
 2. `base_url` in `~/.unbound/config.json` (set via `unbound config set-backend-url`)

package/package.json

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

package/src/auth.js

@@ -10,6 +10,20 @@ const output = require('./output');
 const api = require('./api');
 const { getDeviceSerial, probeDeviceSerialLive } = require('./device-serial');
 
+const NOT_A_CLI_KEY = "This key can't be used with the CLI. Copy it from Configure \u2192 API Access, or run `unbound login`.";
+
+// 401/403 means the key is not a CLI key; anything else (offline, 5xx) is an outage, not an answer.
+function isRejected(err) {
+  return err.statusCode === 401 || err.statusCode === 403;
+}
+
+function warnIfNotStored(stored) {
+  if (stored === false) {
+    output.warn('No OS keychain is available, so this login lasts for this run only. '
+      + 'Set UNBOUND_TOKEN to your CLI key (Configure \u2192 API Access) to stay logged in.');
+  }
+}
+
 /**
  * Opens the browser for authentication and waits for the callback.
  * Starts a local HTTP server, opens the frontend auth page, and waits
@@ -67,6 +81,7 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
   // overwrite the just-persisted credentials after the login promise has
   // settled — reject duplicates outright instead of processing them.
   let callbackHandled = false;
+  let stored;
 
   server.on('request', (req, res) => {
     const url = new URL(req.url, `http://localhost`);
@@ -94,7 +109,7 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
       return;
     }
 
-    config.setApiKey(apiKey);
+    stored = config.setApiKey(apiKey);
     const cfg = config.readConfig();
     if (email) cfg.email = email;
     if (orgName) cfg.org_name = orgName;
@@ -138,6 +153,7 @@ async function loginWithBrowser(frontendUrl, { open: openFn } = {}) {
     const result = await callbackPromise;
     clearTimeout(timeout);
     clearInterval(reminder);
+    warnIfNotStored(stored);
     return result;
   } catch (err) {
     clearTimeout(timeout);
@@ -181,7 +197,22 @@ async function loginWithApiKey(apiKey, { baseUrl } = {}) {
     err.displayed = true;
     throw err;
   }
-  config.setApiKey(apiKey);
+  // Only a CLI key may fetch the device key, so this also rejects device and MDM keys.
+  let deviceKey;
+  try {
+    deviceKey = await fetchDeviceKey(apiKey, { baseUrl });
+  } catch (err) {
+    spin.fail(isRejected(err) ? NOT_A_CLI_KEY : 'Unable to fetch your device key. Please try again.');
+    err.displayed = true;
+    throw err;
+  }
+  // Where the backend allows any key here, a device key comes back as itself.
+  if (deviceKey === apiKey) {
+    spin.fail(NOT_A_CLI_KEY);
+    throw Object.assign(new Error(NOT_A_CLI_KEY), { displayed: true });
+  }
+  const stored = config.setApiKey(apiKey);
+  config.setDeviceKey(deviceKey);
   config.backfillUserInfo(response);
 
   const parts = [];
@@ -189,10 +220,52 @@ async function loginWithApiKey(apiKey, { baseUrl } = {}) {
   const orgName = response.org_name || response.organization_name || response.organization;
   if (orgName) parts.push(orgName);
   spin.succeed(parts.length > 0 ? `Authenticated as ${parts.join(' \u00b7 ')}` : 'Authenticated');
+  warnIfNotStored(stored);
 
   return true;
 }
 
+/** The send-only device key that the given CLI key's owner installs into tools. */
+async function fetchDeviceKey(cliKey, { baseUrl } = {}) {
+  const resp = await api.get('/api/v1/automations/get_application_api_key/', {
+    apiKey: cliKey, baseUrl, query: { app_type: 'default' },
+  });
+  if (!resp || !resp.api_key) {
+    throw new Error('The backend did not return a device key.');
+  }
+  return resp.api_key;
+}
+
+/**
+ * The send-only key setup installs into tools. A CLI key, passed or stored, is swapped for its
+ * device key; a passed --api-key is never saved as the login.
+ */
+async function resolveDeviceKey({ apiKey, baseUrl, frontendUrl } = {}) {
+  if (!apiKey && !config.getApiKey() && !config.getDeviceKey()) {
+    await ensureLoggedIn({ baseUrl, frontendUrl });
+  }
+  // A CLI from before the keychain kept its login in config.json, so that key is tried too.
+  const candidates = apiKey ? [apiKey] : [config.getApiKey(), config.getDeviceKey()];
+  for (const key of new Set(candidates.filter(Boolean))) {
+    let deviceKey;
+    try {
+      deviceKey = await fetchDeviceKey(key, { baseUrl });
+    } catch (err) {
+      // Only a rejection proves this is not a CLI key; an outage must not let a CLI key reach a tool.
+      if (isRejected(err)) continue;
+      throw err;
+    }
+    if (deviceKey === key) continue;
+    if (!apiKey) {
+      // Swapped even when the keychain refuses: setup scripts overwrite config.json anyway, and Configure shows the key again.
+      if (key !== config.getApiKey()) warnIfNotStored(config.setApiKey(key));
+      config.setDeviceKey(deviceKey);
+    }
+    return deviceKey;
+  }
+  return apiKey || config.getDeviceKey();
+}
+
 /**
  * Ensures the user is logged in. If an apiKey is provided, validates and
  * stores it first. If not logged in, triggers browser-based login.
@@ -250,4 +323,6 @@ async function fetchDeviceOwnerKey(adminApiKey, { baseUrl } = {}) {
   return ownerKey;
 }
 
-module.exports = { loginWithBrowser, loginWithApiKey, ensureLoggedIn, fetchDeviceOwnerKey };
+module.exports = {
+  loginWithBrowser, loginWithApiKey, ensureLoggedIn, fetchDeviceOwnerKey, fetchDeviceKey, resolveDeviceKey,
+};

package/src/commands/doctor.js

@@ -56,9 +56,11 @@ doctor can gate scripts/CI.
 Examples:
   $ unbound doctor
   $ unbound doctor --fix      Reinstall every tampered tool
+  $ sudo unbound doctor --fix --api-key <MDM_KEY>   Reinstall org-wide tools
   $ unbound doctor --json
 `)
     .option('--fix', 'Reinstall every tool reported as tampered')
+    .option('--api-key <key>', 'MDM key, required to reinstall org-wide tools with sudo')
     .option('--json', 'Output raw JSON')
     .action(async (opts) => {
       try {
@@ -153,8 +155,7 @@ Examples:
         const userNames = userTampered.map((t) => t.label).join(', ');
         const mdmNames = mdmTampered.map((t) => t.label).join(', ');
         const allFix = tampered.map((t) => t.key);
-        // A codex policy can live only in the user's cache, which a sudo re-detection may not see.
-        const mdmCmd = elevated(mdmTampered.some((t) => t.notEnforced) ? `unbound setup ${mdmFix.join(' ')}` : 'unbound doctor --fix');
+        const mdmCmd = elevated(`unbound setup ${mdmFix.join(' ')} --api-key <MDM_KEY>`);
         const anyInstalled = tools.some((t) => t.status !== 'not-installed');
 
         if (opts.fix) {
@@ -183,11 +184,18 @@ Examples:
             process.exitCode = 1;
             return;
           }
+          // Org-wide setup takes only the MDM key, never the CLI login.
+          if (root && !opts.apiKey) {
+            output.error('--api-key is required to reinstall tools for all users: use the MDM key from Configure \u2192 My Org.');
+            process.exitCode = 1;
+            return;
+          }
           const fixNow = root ? allFix : userFix;
           const fixDisplay = (root ? tampered : userTampered).map(labelOf).join(', ');
           output.info(`Reinstalling: ${fixDisplay}${root ? ' (org-wide, all users)' : ''}`);
           console.log('');
-          const r = spawnSync(process.argv[0], [process.argv[1], 'setup', ...fixNow], { stdio: 'inherit' });
+          const keyArgs = root ? ['--api-key', opts.apiKey] : [];
+          const r = spawnSync(process.argv[0], [process.argv[1], 'setup', ...fixNow, ...keyArgs], { stdio: 'inherit' });
           if (!root && mdmFix.length) console.error(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold(mdmCmd)} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);
           process.exitCode = fixExitCode(r.status, root, mdmFix.length > 0) || ((configMismatch || blankConfigDir) ? 1 : 0);
           return;

package/src/commands/login.js

@@ -2,7 +2,7 @@ const { Option } = require('commander');
 const config = require('../config');
 const output = require('../output');
 const api = require('../api');
-const { loginWithBrowser, loginWithApiKey } = require('../auth');
+const { loginWithBrowser, loginWithApiKey, fetchDeviceKey } = require('../auth');
 const { getDeviceSerial } = require('../device-serial');
 
 function register(program) {
@@ -23,8 +23,9 @@ Authentication methods:
     Times out after 120 seconds if no callback is received.
 
   API key login (--api-key):
-    Non-interactive login for CI/CD or automation. Stores the provided
-    API key directly without browser interaction.
+    Non-interactive login for CI/CD or automation. Takes the CLI key from
+    Configure → API Access and keeps it in the OS keychain (or set
+    UNBOUND_TOKEN where there is none). Device and MDM keys are refused.
 
 Tenant deployments (URL flags persist to ~/.unbound/config.json):
   Pass --gateway-url, --frontend-url, --backend-url at login time and the
@@ -84,6 +85,12 @@ Examples:
           await api.get('/api/v1/users/privileges/', {
             baseUrl: explicitBaseUrl, query: { device_serial: deviceSerial },
           });
+          // Replace whatever config.json held (an old CLI login, another org's key) with this login's device key.
+          try {
+            config.setDeviceKey(await fetchDeviceKey(config.getApiKey(), { baseUrl: explicitBaseUrl }));
+          } catch {
+            output.warn('Could not fetch your device key; `unbound setup` will fetch it.');
+          }
         }
 
         const cfg = config.readConfig();

package/src/commands/logout.js

@@ -1,26 +1,49 @@
 const config = require('../config');
 const output = require('../output');
+const auth = require('../auth');
 
 function register(program) {
   program
     .command('logout')
-    .description('Log out of Unbound. Removes stored credentials from ~/.unbound/config.json while preserving custom URL settings.')
+    .description('Log out of Unbound. Removes the CLI key from the OS keychain while preserving custom URL settings.')
     .addHelpText('after', `
 What this does:
-  Clears stored credentials (API key, email, organization) from
-  ~/.unbound/config.json. Custom URL settings (base_url, frontend_url)
-  are preserved so you don't need to reconfigure them.
+  Removes the CLI key from the OS keychain and clears email and organization
+  from ~/.unbound/config.json. The device key in config.json stays, because
+  installed hooks use it. Custom URL settings are preserved.
 
 Examples:
   $ unbound logout
 `)
-    .action(() => {
+    .action(async () => {
       try {
+        // A CLI from before the keychain left its login in config.json; keep only its device key there.
+        const stored = config.getDeviceKey();
+        let unchecked = false;
+        if (stored) {
+          try {
+            const deviceKey = await auth.fetchDeviceKey(stored);
+            if (deviceKey !== stored) config.setDeviceKey(deviceKey);
+          } catch (err) {
+            // 401/403 means it is already a device key; any other failure leaves a possible CLI key unchecked.
+            unchecked = err.statusCode !== 401 && err.statusCode !== 403;
+          }
+        }
+        if (!config.clearApiKey()) {
+          output.warn('Could not remove the CLI key from the OS keychain. Unlock it and run `unbound logout` again.');
+        }
+        if (process.env.UNBOUND_TOKEN) {
+          output.warn('UNBOUND_TOKEN is still set, so CLI commands stay logged in. Unset it to log out.');
+        }
         const cfg = config.readConfig();
-        delete cfg.api_key;
         delete cfg.email;
         delete cfg.org_name;
         config.writeConfig(cfg);
+        if (unchecked) {
+          output.error('Could not reach Unbound to check the key in ~/.unbound/config.json. Run `unbound logout` again when online.');
+          process.exitCode = 1;
+          return;
+        }
         output.success('Logged out successfully. Custom URL settings preserved.');
       } catch (err) {
         output.error(err.message);

package/src/commands/oacb.js

@@ -159,8 +159,7 @@ Read the framework at https://github.com/websentry-ai/oacb before applying basel
 // ─── Handlers ────────────────────────────────────────────────────────────────
 
 async function handleCheck() {
-  const cfg = config.readConfig();
-  const hasUnboundSession = !!cfg.api_key;
+  const hasUnboundSession = config.isLoggedIn();
 
   const { execSync } = require('node:child_process');
 

package/src/commands/onboard.js

@@ -2,7 +2,7 @@ const { Option } = require('commander');
 const config = require('../config');
 const output = require('../output');
 const telemetry = require('../telemetry');
-const { ensureLoggedIn, fetchDeviceOwnerKey } = require('../auth');
+const { resolveDeviceKey, fetchDeviceOwnerKey } = require('../auth');
 const { runSetupAllBundle, runMdmSetupAllBundle, hasRootPrivileges, elevated, scopeNotice, ALL_TOOLS, MDM_ALL_TOOLS, SETUP_TOOL_MAP, MDM_TOOLS } = require('./setup');
 const { runDiscoveryScan } = require('./discover');
 const toolDetect = require('../toolDetect');
@@ -54,7 +54,7 @@ function register(program) {
       '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>', 'API key (user key, or admin key when run with sudo). Falls back to UNBOUND_API_KEY or a stored `unbound login` key)')
+    .option('--api-key <key>', 'API key (device key, or the MDM key when run with sudo). Without sudo, falls back to UNBOUND_API_KEY or the key from `unbound login`')
     .addOption(new Option('--admin-api-key <key>', 'Alias for --api-key (back-compat)').hideHelp())
     .addOption(new Option('--discovery-key <key>', 'Deprecated and ignored. The scan uses your API key.').hideHelp())
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
@@ -96,10 +96,8 @@ Examples:
       const isMdm = hasRootPrivileges();
       output.info(scopeNotice(isMdm));
 
-      // --api-key (or a stored `unbound login` key) is all that's required, for
-      // both scopes. MDM scope resolves the admin key below (it may come from a
-      // stored login credential).
-      if (!isMdm && !apiKeyOpt && !config.isLoggedIn()) {
+      // User scope needs --api-key, a login, or a stored device key; MDM scope requires --api-key below.
+      if (!isMdm && !apiKeyOpt && !config.isLoggedIn() && !config.getDeviceKey()) {
         output.error('--api-key is required (or set UNBOUND_API_KEY env var, or run `unbound login` first)');
         process.exitCode = 1;
         return;
@@ -115,6 +113,7 @@ Examples:
       let skippedTools;
       let piFailed = false;
       let mdmScanKey;  // device-owner key resolved from the serial (MDM scope only)
+      let userKey;  // the user's device key (user scope only)
       try {
         // Persist URLs first, then login, then setup — order matters so the
         // login validates against the new backend and setup wires tools at the
@@ -136,10 +135,10 @@ Examples:
         discoveryDomain = opts.domain ? config.normalizeUrl(opts.domain) : backendUrl;
 
         if (isMdm) {
-          // Reuse the key stored by `unbound login` when no key was passed.
-          const adminApiKey = apiKeyOpt || config.getApiKey();
+          // The MDM key must be passed; the CLI login is never used to deploy.
+          const adminApiKey = apiKeyOpt;
           if (!adminApiKey) {
-            output.error('--api-key is required (or run `unbound login` first).');
+            output.error('--api-key is required: use the MDM key from Configure \u2192 My Org.');
             process.exitCode = 1;
             return;
           }
@@ -177,12 +176,13 @@ Examples:
           discoverySucceeded = true;
           skippedTools = skipped;
         } else {
-          await ensureLoggedIn({
+          const apiKey = await resolveDeviceKey({
             apiKey: apiKeyOpt,
             baseUrl: written.base_url,
             frontendUrl: written.frontend_url,
           });
-          const apiKey = config.getApiKey();
+          userKey = apiKey;
+          telemetry.rememberSecret(apiKey);
 
           console.log('');
           output.info('Step 1/2: Installing tool bundle');
@@ -237,7 +237,7 @@ Examples:
             output.info('Setting up daily scheduled run');
             await setupScheduledRun({
               command: 'onboard',
-              apiKey: apiKeyOpt || config.getApiKey(),
+              apiKey: userKey,
               domain: discoveryDomain,
               skipRunAtLoad: true,
             });

package/src/commands/setup.js

@@ -6,7 +6,7 @@ const path = require('path');
 const config = require('../config');
 const output = require('../output');
 const telemetry = require('../telemetry');
-const { ensureLoggedIn } = require('../auth');
+const auth = require('../auth');
 const { confirm, downloadToFile, withSecureTempFile } = require('../utils');
 const { reportSetupFailure, exitCodeForError } = require('../setup-report');
 const claudePaths = require('../claudePaths');
@@ -790,11 +790,11 @@ Examples:
 
   Install the default bundle (Cursor + Copilot + Augment + Claude Code hooks + Codex hooks):
   $ unbound setup --all                                    Set up the default bundle
-  $ unbound setup --all --api-key <key>                    Login + set up the bundle
+  $ unbound setup --all --api-key <key>                    Set up the bundle with a device key
 
   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 --all --api-key <MDM_KEY>           Configure all users (MDM)
+  $ sudo unbound setup cursor codex-subscription --api-key <MDM_KEY>   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):
@@ -856,9 +856,10 @@ must update the MDM configuration.
         output.info(scopeNotice(isMdm));
         if (isMdm) {
           const mdmToolNames = [...Object.keys(MDM_TOOLS), 'claude-code', 'codex'].join(', ');
-          const adminApiKey = opts.adminApiKey || opts.apiKey || config.getApiKey();
+          // The MDM key must be passed; the CLI login is never used to deploy.
+          const adminApiKey = opts.adminApiKey || opts.apiKey;
           if (!opts.clear && !adminApiKey) {
-            output.error('--api-key is required to set up tools (or run `unbound login` first).');
+            output.error('--api-key is required to set up tools for all users: use the MDM key from Configure \u2192 My Org.');
             process.exitCode = 1;
             return;
           }
@@ -942,14 +943,12 @@ must update the MDM configuration.
 
         // 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) {
-          await ensureLoggedIn({
-            apiKey: opts.apiKey,
-            baseUrl: written.base_url,
-            frontendUrl: written.frontend_url,
-          });
-        }
-        const apiKey = config.getApiKey();
+        const apiKey = opts.clear ? config.getDeviceKey() : await auth.resolveDeviceKey({
+          apiKey: opts.apiKey,
+          baseUrl: written.base_url,
+          frontendUrl: written.frontend_url,
+        });
+        telemetry.rememberSecret(apiKey);
         const urlOpts = { backendUrl, frontendUrl, gatewayUrl };
 
         // --all expands to the default bundle. Cannot be combined with explicit tool names.
@@ -1176,7 +1175,7 @@ What it clears:
     scheduled task, and the key in Keychain / creds file / Credential Manager. Under
     sudo this is torn down for the invoking user (the scan is a per-user artifact).
   - MDM (system-level) tool config across all users          [only when run as root]
-  - Stored credentials and settings (~/.unbound/config.json).
+  - Stored credentials and settings (~/.unbound/config.json and the CLI key in the OS keychain).
 
 After it finishes, run \`unbound login\` (or \`unbound onboard\`) to set things up
 fresh. Clearing never contacts the Unbound API, so no API key is needed. The
@@ -1263,8 +1262,11 @@ Examples:
         }
 
         // Wipe credentials + settings last, regardless of tool-clear outcomes.
-        config.clearConfig();
+        const keyRemoved = config.clearConfig();
         output.success('Stored credentials and settings removed.');
+        // As root, the keychain reached is root's, not the invoking user's.
+        if (hasRootPrivileges()) output.info('Run `unbound logout` without sudo to remove your CLI key from the keychain.');
+        else if (!keyRemoved) output.warn('Could not remove the CLI key from the OS keychain. Unlock it and run `unbound logout`.');
 
         console.log('');
         const failed = [...userFailed, ...mdmFailed, ...binaryFailed, ...scheduledFailed];

package/src/config.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const keychain = require('./keychain');
 
 const CONFIG_DIR = path.join(os.homedir(), '.unbound');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
@@ -59,12 +60,27 @@ function writeConfig(config) {
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
 }
 
+// The CLI login key reads org data, so it lives in the OS keychain; UNBOUND_TOKEN is read only when the keychain has none.
 function getApiKey() {
-  const config = readConfig();
-  return config.api_key || null;
+  return keychain.get() || process.env.UNBOUND_TOKEN || null;
 }
 
+/** Stores the CLI login key; false when no keychain could keep it past this run. */
 function setApiKey(apiKey) {
+  return keychain.set(apiKey);
+}
+
+/** True once no CLI key is left in the keychain. */
+function clearApiKey() {
+  return keychain.remove();
+}
+
+// The send-only device key, where setup scripts and hooks read it.
+function getDeviceKey() {
+  return readConfig().api_key || null;
+}
+
+function setDeviceKey(apiKey) {
   const config = readConfig();
   config.api_key = apiKey;
   writeConfig(config);
@@ -127,10 +143,13 @@ function setUrls({ gateway, frontend, backend } = {}) {
   return normalized;
 }
 
+/** Removes config.json and the keychain CLI key; false when the keychain kept the key. */
 function clearConfig() {
+  const keyRemoved = clearApiKey();
   if (fs.existsSync(CONFIG_FILE)) {
     fs.unlinkSync(CONFIG_FILE);
   }
+  return keyRemoved;
 }
 
 function isLoggedIn() {
@@ -174,6 +193,9 @@ module.exports = {
   writeConfig,
   getApiKey,
   setApiKey,
+  clearApiKey,
+  getDeviceKey,
+  setDeviceKey,
   getBaseUrl,
   setBaseUrl,
   getFrontendUrl,

package/src/keychain.js

@@ -0,0 +1,156 @@
+/**
+ * The CLI login key lives in the OS keychain, never in a file. The secret only
+ * ever travels on stdin, so it never shows up in `ps` or process-audit logs.
+ */
+const { execFileSync } = require('child_process');
+
+const SERVICE = 'ai.getunbound.cli';
+const ACCOUNT = 'api_key';
+const TIMEOUT_MS = 15_000;
+// Keys are url-safe tokens; this also keeps `security -i` from reading a second command.
+const KEY_PATTERN = /^[A-Za-z0-9._~-]{8,512}$/;
+
+const WINDOWS_CRED = `
+$ErrorActionPreference = 'Stop'
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class UnboundCred {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct CREDENTIAL {
+    public int Flags; public int Type;
+    [MarshalAs(UnmanagedType.LPWStr)] public string TargetName;
+    [MarshalAs(UnmanagedType.LPWStr)] public string Comment;
+    public long LastWritten; public int CredentialBlobSize; public IntPtr CredentialBlob;
+    public int Persist; public int AttributeCount; public IntPtr Attributes;
+    [MarshalAs(UnmanagedType.LPWStr)] public string TargetAlias;
+    [MarshalAs(UnmanagedType.LPWStr)] public string UserName;
+  }
+  [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] static extern bool CredWriteW(ref CREDENTIAL c, uint f);
+  [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] static extern bool CredReadW(string t, int type, int f, out IntPtr c);
+  [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)] static extern bool CredDeleteW(string t, int type, int f);
+  [DllImport("advapi32.dll")] static extern void CredFree(IntPtr c);
+  public static bool Write(string t, string u, string s) {
+    var b = Encoding.Unicode.GetBytes(s); var p = GCHandle.Alloc(b, GCHandleType.Pinned);
+    try {
+      var c = new CREDENTIAL { Type = 1, TargetName = t, UserName = u, CredentialBlob = p.AddrOfPinnedObject(), CredentialBlobSize = b.Length, Persist = 2 };
+      return CredWriteW(ref c, 0);
+    } finally { p.Free(); }
+  }
+  public static string Read(string t) {
+    IntPtr ptr; if (!CredReadW(t, 1, 0, out ptr)) return "";
+    try { var c = (CREDENTIAL)Marshal.PtrToStructure(ptr, typeof(CREDENTIAL)); return Marshal.PtrToStringUni(c.CredentialBlob, c.CredentialBlobSize / 2); }
+    finally { CredFree(ptr); }
+  }
+  public static bool Delete(string t) { return CredDeleteW(t, 1, 0); }
+}
+'@
+$target = '${SERVICE}:${ACCOUNT}'
+switch ($args[0]) {
+  'read'   { [Console]::Out.Write([UnboundCred]::Read($target)) }
+  'write'  { if (-not [UnboundCred]::Write($target, '${ACCOUNT}', [Console]::In.ReadToEnd())) { exit 1 } }
+  'delete' { [void][UnboundCred]::Delete($target) }
+}
+`;
+
+function run(cmd, args, input) {
+  return execFileSync(cmd, args, {
+    input: input === undefined ? '' : input,
+    stdio: ['pipe', 'pipe', 'ignore'],
+    timeout: TIMEOUT_MS,
+    windowsHide: true,
+  }).toString();
+}
+
+function windows(action, input) {
+  const script = `& { ${WINDOWS_CRED} } ${action}`;
+  return run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], input);
+}
+
+const backends = {
+  darwin: {
+    read: () => run('security', ['find-generic-password', '-s', SERVICE, '-a', ACCOUNT, '-w']),
+    write: (key) => {
+      // With no default keychain (sudo, odd HOME), add-generic-password pops a "Keychain Not Found" dialog; this fails quietly first.
+      run('security', ['default-keychain']);
+      return run('security', ['-i'], `add-generic-password -U -s ${SERVICE} -a ${ACCOUNT} -w ${key}\n`);
+    },
+    remove: () => run('security', ['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT]),
+  },
+  linux: {
+    read: () => run('secret-tool', ['lookup', 'service', SERVICE, 'account', ACCOUNT]),
+    write: (key) => run('secret-tool', ['store', '--label=Unbound CLI', 'service', SERVICE, 'account', ACCOUNT], key),
+    remove: () => run('secret-tool', ['clear', 'service', SERVICE, 'account', ACCOUNT]),
+  },
+  win32: {
+    read: () => windows('read'),
+    write: (key) => windows('write', key),
+    remove: () => windows('delete'),
+  },
+};
+
+let cached;
+
+function backend() {
+  return backends[process.platform] || null;
+}
+
+/** The stored CLI key, or null when there is none or no keychain is reachable. */
+function get() {
+  if (cached !== undefined) return cached;
+  let value = null;
+  try {
+    const b = backend();
+    value = (b && b.read().trim()) || null;
+  } catch {
+    value = null;
+  }
+  cached = value;
+  return value;
+}
+
+/** Stores the CLI key; true only once it reads back, since a locked keychain can report success and store nothing. */
+function set(key) {
+  if (!KEY_PATTERN.test(String(key || ''))) return false;
+  let stored = false;
+  try {
+    const b = backend();
+    if (b) {
+      b.write(key);
+      cached = undefined;
+      stored = get() === key;
+    }
+  } catch {
+    stored = false;
+  }
+  // Usable for the rest of this run even when no keychain kept it.
+  cached = key;
+  return stored;
+}
+
+// Exit codes that mean "no such item", as opposed to a locked or unreachable keychain.
+const NOT_FOUND_STATUS = { darwin: 44, linux: 1 };
+
+function isAbsent() {
+  try {
+    const b = backend();
+    return !b || !b.read().trim();
+  } catch (err) {
+    return err.status === NOT_FOUND_STATUS[process.platform];
+  }
+}
+
+/** Removes the CLI key; true only once the keychain confirms it is gone. */
+function remove() {
+  try {
+    const b = backend();
+    if (b) b.remove();
+  } catch {
+    // Already absent, or the keychain refused: the check below decides.
+  }
+  cached = undefined;
+  return isAbsent();
+}
+
+module.exports = { get, set, remove, SERVICE, ACCOUNT, _backends: backends, _reset: () => { cached = undefined; } };

package/src/setup-report.js

@@ -84,7 +84,7 @@ function exitCodeForError(err) {
  */
 async function reportSetupFailure({ step, exitCode, apiKey, backendUrl } = {}) {
   try {
-    const key = apiKey || config.getApiKey();
+    const key = apiKey || config.getDeviceKey();
     // No key → nothing to authenticate with; the ledger upserts by org, so a
     // keyless report can't be attributed. Skip quietly.
     if (!key) return false;

package/test/cli-key.test.js

@@ -0,0 +1,160 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const DEVICE_KEY_PATH = '/api/v1/automations/get_application_api_key/';
+const CLI_KEY = 'cli-key-123';
+
+function unauthorized() {
+  return Object.assign(new Error('Invalid API key. Run `unbound login`.'), { statusCode: 401 });
+}
+
+// A fake backend: only the CLI key may fetch a device key; any key passes privileges.
+function freshAuth({ keychainKey = null, configKey = null } = {}) {
+  for (const m of ['../src/auth', '../src/api', '../src/config', '../src/output', '../src/device-serial']) {
+    delete require.cache[require.resolve(m)];
+  }
+  const api = require('../src/api');
+  const config = require('../src/config');
+  const output = require('../src/output');
+  const deviceSerial = require('../src/device-serial');
+  const state = { keychain: keychainKey, config: configKey, warns: [] };
+
+  deviceSerial.getDeviceSerial = async () => 'SERIAL';
+  api.get = async (path, opts) => {
+    if (path !== DEVICE_KEY_PATH) return { email: 'a@b.co', org_name: 'Acme' };
+    if (opts.apiKey !== CLI_KEY) throw unauthorized();
+    return { api_key: 'device-key' };
+  };
+  config.getApiKey = () => state.keychain;
+  config.setApiKey = (k) => { state.keychain = k; return true; };
+  config.getDeviceKey = () => state.config;
+  config.setDeviceKey = (k) => { state.config = k; };
+  config.backfillUserInfo = () => {};
+  output.spinner = () => ({ succeed() {}, fail(msg) { state.failed = msg; } });
+  output.warn = (m) => state.warns.push(m);
+  return { auth: require('../src/auth'), state };
+}
+
+test('login --api-key keeps the CLI key in the keychain and the device key in config.json', async () => {
+  const { auth, state } = freshAuth();
+  await auth.loginWithApiKey(CLI_KEY);
+  assert.equal(state.keychain, CLI_KEY);
+  assert.equal(state.config, 'device-key');
+});
+
+test('login --api-key rejects a device or MDM key and stores nothing', async () => {
+  const { auth, state } = freshAuth();
+  await assert.rejects(() => auth.loginWithApiKey('device-key'));
+  assert.match(state.failed, /can't be used with the CLI/);
+  assert.equal(state.keychain, null);
+  assert.equal(state.config, null);
+});
+
+test('setup --api-key with a device key installs it as-is and never saves it as the login', async () => {
+  const { auth, state } = freshAuth();
+  assert.equal(await auth.resolveDeviceKey({ apiKey: 'device-key' }), 'device-key');
+  assert.equal(state.keychain, null);
+});
+
+test('setup --api-key with a CLI key installs the device key instead', async () => {
+  const { auth, state } = freshAuth();
+  assert.equal(await auth.resolveDeviceKey({ apiKey: CLI_KEY }), 'device-key');
+  assert.equal(state.keychain, null, 'a passed key is never saved as the login');
+});
+
+test('setup when logged in refreshes the device key from the login', async () => {
+  const { auth, state } = freshAuth({ keychainKey: CLI_KEY, configKey: 'stale-key' });
+  assert.equal(await auth.resolveDeviceKey({}), 'device-key');
+  assert.equal(state.config, 'device-key');
+});
+
+test('an old CLI login in config.json moves to the keychain and is replaced by the device key', async () => {
+  const { auth, state } = freshAuth({ configKey: CLI_KEY });
+  assert.equal(await auth.resolveDeviceKey({}), 'device-key');
+  assert.equal(state.keychain, CLI_KEY);
+  assert.equal(state.config, 'device-key');
+});
+
+test('the keychain wins; UNBOUND_TOKEN is only a fallback, and malformed keys never reach the keychain', () => {
+  delete require.cache[require.resolve('../src/config')];
+  delete require.cache[require.resolve('../src/keychain')];
+  const keychain = require('../src/keychain');
+  const config = require('../src/config');
+  const prev = process.env.UNBOUND_TOKEN;
+  process.env.UNBOUND_TOKEN = 'from-env';
+  try {
+    keychain.get = () => 'from-keychain';
+    assert.equal(config.getApiKey(), 'from-keychain');
+    keychain.get = () => null;
+    assert.equal(config.getApiKey(), 'from-env');
+  } finally {
+    if (prev === undefined) delete process.env.UNBOUND_TOKEN; else process.env.UNBOUND_TOKEN = prev;
+  }
+  delete require.cache[require.resolve('../src/keychain')];
+  assert.equal(require('../src/keychain').set('bad key\nadd-generic-password'), false);
+});
+
+test('an outage while checking a passed key fails setup instead of installing a possible CLI key', async () => {
+  const { auth } = freshAuth();
+  require('../src/api').get = async () => { throw Object.assign(new Error('Service unavailable'), { statusCode: 503 }); };
+  await assert.rejects(() => auth.resolveDeviceKey({ apiKey: CLI_KEY }), /Service unavailable/);
+});
+
+test('where the backend hands a device key back as itself, it is never stored as the login', async () => {
+  const { auth, state } = freshAuth({ configKey: 'device-key' });
+  require('../src/api').get = async (path, opts) => (path === DEVICE_KEY_PATH ? { api_key: opts.apiKey } : {});
+  await assert.rejects(() => auth.loginWithApiKey('device-key'));
+  assert.equal(state.keychain, null);
+  assert.equal(await auth.resolveDeviceKey({}), 'device-key');
+  assert.equal(state.keychain, null, 'a device key is not migrated into the keychain');
+});
+
+async function runLogout(fetchDeviceKey) {
+  for (const m of ['../src/commands/logout', '../src/auth', '../src/config', '../src/output']) {
+    delete require.cache[require.resolve(m)];
+  }
+  const auth = require('../src/auth');
+  const config = require('../src/config');
+  const output = require('../src/output');
+  const state = { config: CLI_KEY, errors: [], success: 0 };
+  auth.fetchDeviceKey = fetchDeviceKey;
+  config.getDeviceKey = () => state.config;
+  config.setDeviceKey = (k) => { state.config = k; };
+  config.clearApiKey = () => true;
+  config.readConfig = () => ({});
+  config.writeConfig = () => {};
+  output.error = (m) => state.errors.push(m);
+  output.warn = () => {};
+  output.success = () => { state.success++; };
+  const { Command } = require('commander');
+  const program = new Command();
+  program.exitOverride();
+  require('../src/commands/logout').register(program);
+  const prev = process.exitCode;
+  process.exitCode = 0;
+  await program.parseAsync(['node', 'unbound', 'logout']);
+  state.exitCode = process.exitCode;
+  process.exitCode = prev;
+  return state;
+}
+
+test('logout swaps an old CLI login in config.json for its device key', async () => {
+  const state = await runLogout(async () => 'device-key');
+  assert.equal(state.config, 'device-key');
+  assert.equal(state.success, 1);
+});
+
+test('logout offline does not claim success while config.json may still hold a CLI key', async () => {
+  const state = await runLogout(async () => { throw Object.assign(new Error('offline'), { code: 'ECONNREFUSED' }); });
+  assert.equal(state.exitCode, 1);
+  assert.equal(state.success, 0);
+  assert.match(state.errors[0], /again when online/);
+});
+
+test('moving an old CLI login warns when no keychain can keep it', async () => {
+  const { auth, state } = freshAuth({ configKey: CLI_KEY });
+  require('../src/config').setApiKey = () => false;
+  assert.equal(await auth.resolveDeviceKey({}), 'device-key');
+  assert.equal(state.config, 'device-key', 'the read-access key never stays where tools read it');
+  assert.match(state.warns[0], /UNBOUND_TOKEN/);
+});

package/test/flags.test.js

@@ -136,7 +136,7 @@ function runCli(port, args) {
     JSON.stringify({ api_key: 'test-key', base_url: `http://127.0.0.1:${port}` }));
   return new Promise((resolve) => {
     const child = spawn('node', [path.join(__dirname, '..', 'src', 'index.js'), ...args], {
-      env: { ...process.env, HOME: home, UNBOUND_API_URL: '', UNBOUND_TELEMETRY: '0', UNBOUND_NO_UPDATE_CHECK: '1' },
+      env: { ...process.env, HOME: home, UNBOUND_TOKEN: 'test-key', UNBOUND_API_URL: '', UNBOUND_TELEMETRY: '0', UNBOUND_NO_UPDATE_CHECK: '1' },
     });
     let stdout = '';
     let stderr = '';

package/test/onboard-cron.test.js

@@ -122,7 +122,7 @@ test('per-user onboard cron passes apiKey but NOT discoveryKey to setupScheduled
 // key; the MDM (sudo) branch resolves the device-owner key from the serial and
 // scans with THAT. Neither scan uses a separate org discovery key.
 test('per-user scans with the user key; MDM scans with the resolved device-owner key; no discovery key', () => {
-  const userBranchStart = onboardSrc.indexOf('const apiKey = config.getApiKey();');
+  const userBranchStart = onboardSrc.indexOf('const apiKey = await resolveDeviceKey(');
   assert.notEqual(userBranchStart, -1, 'expected the per-user branch in onboard.js');
   const userBranch = onboardSrc.slice(userBranchStart);
   assert.match(

package/test/onboard-failure-exit.test.js

@@ -46,7 +46,7 @@ function loadOnboard({ isRoot, setupOk, reportThrows }) {
   setup.runSetupAllBundle = bundle;
   setup.runMdmSetupAllBundle = bundle;
   discover.runDiscoveryScan = async () => { calls.discovery++; };
-  auth.ensureLoggedIn = async () => {};
+  auth.resolveDeviceKey = async () => 'resolved-key';
   config.setUrls = () => ({});
   config.getApiKey = () => 'resolved-key';
   config.getBaseUrl = () => 'https://b.acme';

package/test/onboard-scope.test.js

@@ -63,7 +63,8 @@ async function runOnboard(isRoot, { setCron = false, discoveryKey = 'd', domain,
   setup.runMdmSetupAllBundle = async () => { calls.mdm++; return { ok: true, skipped: [] }; };
   setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
   discover.runDiscoveryScan = async (o) => { calls.discovery++; calls.discoveryArgs = o; };
-  auth.ensureLoggedIn = async () => { calls.loggedIn++; };
+  // User scope resolves the device key (the stored or passed key, swapped for a device key).
+  auth.resolveDeviceKey = async () => { calls.loggedIn++; return 'resolved-key'; };
   // MDM scope resolves the device-owner key from the serial and scans with it.
   auth.fetchDeviceOwnerKey = async (adminKey, opts) => {
     calls.ownerFetchedFrom = adminKey;
@@ -101,7 +102,7 @@ test('onboard with sudo/root → installs the MDM bundle (all users), no login',
   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.loggedIn, 0, 'MDM scope does not resolve a user device key');
   assert.equal(calls.discovery, 1, 'discovery still runs');
   assert.equal(calls.ownerFetchedFrom, 'k', 'MDM scope resolves the owner key from the admin key');
   assert.equal(calls.discoveryArgs.apiKey, 'owner-key', 'MDM scope scans with the device-owner key resolved from the serial');
@@ -133,7 +134,7 @@ 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.loggedIn, 1, 'user scope resolves the device key');
   assert.equal(calls.discovery, 1, 'discovery still runs');
   // WEB-4891: per-user scan uses the resolved user key, NOT the org discovery key.
   assert.equal(calls.discoveryArgs.apiKey, 'resolved-key', 'user scope scans with the user API key');
@@ -156,7 +157,7 @@ test('onboard --set-cron without sudo → schedules the full onboard run', async
   assert.equal(calls.cron.command, 'onboard', 'user scope keeps the full onboard cron');
   // WEB-4891: the per-user cron re-runs onboard, which scans with the user's own
   // key — so the user key is stored and no separate discovery key is.
-  assert.equal(calls.cron.apiKey, 'k', 'per-user cron stores the user API key');
+  assert.equal(calls.cron.apiKey, 'resolved-key', 'per-user cron stores the resolved device key, never the CLI login');
   assert.equal(calls.cron.discoveryKey, undefined, 'per-user onboard cron no longer forwards a discovery key');
 });
 

package/test/setup-instruction-tools.test.js

@@ -70,7 +70,7 @@ async function driveSetup(tools) {
   // non-root and the run reaches the instruction-tool call sites on any host.
   const origGetuid = process.getuid;
   process.getuid = () => 1000;
-  auth.ensureLoggedIn = async () => {};
+  auth.resolveDeviceKey = async () => 'resolved-key';
   config.setUrls = () => ({});
   config.getBaseUrl = () => 'https://backend.acme';
   config.getFrontendUrl = () => 'https://frontend.acme';

package/test/setup-report.test.js

@@ -20,7 +20,7 @@ test('reportSetupFailure: posts the contract payload to /api/v1/setup/failed/',
   const { api, config, report } = freshReport();
   let captured = null;
   api.post = async (path, opts) => { captured = { path, opts }; return { ok: true }; };
-  config.getApiKey = () => 'stored-key';
+  config.getDeviceKey = () => 'stored-key';
 
   const ok = await report.reportSetupFailure({ step: 'cursor', exitCode: 2, backendUrl: 'https://b.acme' });
 
@@ -42,7 +42,7 @@ test('reportSetupFailure: bounds the POST with a 3s timeout (never blocks on def
   const { api, config, report } = freshReport();
   let captured = null;
   api.post = async (path, opts) => { captured = opts; return { ok: true }; };
-  config.getApiKey = () => 'k';
+  config.getDeviceKey = () => 'k';
 
   await report.reportSetupFailure({ step: 'cursor', exitCode: 1 });
   assert.equal(captured.timeoutMs, 3000, 'failure report must pass a tight 3s timeout');
@@ -51,7 +51,7 @@ test('reportSetupFailure: bounds the POST with a 3s timeout (never blocks on def
 test('reportSetupFailure: swallows a POST rejection and returns false (best-effort)', async () => {
   const { api, config, report } = freshReport();
   api.post = async () => { throw new Error('ECONNREFUSED / offline'); };
-  config.getApiKey = () => 'k';
+  config.getDeviceKey = () => 'k';
 
   let result;
   await assert.doesNotReject(async () => { result = await report.reportSetupFailure({ step: 'codex', exitCode: 1 }); });
@@ -61,7 +61,7 @@ test('reportSetupFailure: swallows a POST rejection and returns false (best-effo
 test('reportSetupFailure: a 429 (rate-limited) is swallowed too', async () => {
   const { api, config, report } = freshReport();
   api.post = async () => { const e = new Error('Too many requests'); e.statusCode = 429; throw e; };
-  config.getApiKey = () => 'k';
+  config.getDeviceKey = () => 'k';
 
   const result = await report.reportSetupFailure({ step: 'cursor', exitCode: 1 });
   assert.equal(result, false);
@@ -71,7 +71,7 @@ test('reportSetupFailure: no API key → skips quietly (false), no POST attempte
   const { api, config, report } = freshReport();
   let called = false;
   api.post = async () => { called = true; return {}; };
-  config.getApiKey = () => null;
+  config.getDeviceKey = () => null;
 
   const result = await report.reportSetupFailure({ step: 'cursor', exitCode: 1 });
   assert.equal(result, false);

package/test/tool-detect.test.js

@@ -309,7 +309,7 @@ async function runOnboard({ isRoot, detect, fail, discoveryThrows }) {
     calls.discovery++;
     if (discoveryThrows) throw new Error('scan failed');
   };
-  auth.ensureLoggedIn = async () => {};
+  auth.resolveDeviceKey = async () => 'resolved-key';
   auth.fetchDeviceOwnerKey = async () => 'owner-key';
   config.setUrls = () => ({});
   config.getApiKey = () => 'resolved-key';