unbound-cli 0.9.0 → 0.9.2

package/src/commands/onboard.js

@@ -26,6 +26,7 @@ function register(program) {
     .requiredOption('--api-key <key>', 'User API key (for tool setup and login)')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
+    .option('--backfill', 'Seed historical Claude Code / Codex 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())
@@ -46,6 +47,7 @@ For admin device enrollment via MDM, use \`unbound onboard-mdm\` instead.
 
 Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
   $ sudo unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
 `)
     .action(async (opts) => {
@@ -79,7 +81,9 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing tool bundle');
-        const ok = await runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl });
+        const ok = await runSetupAllBundle(apiKey, {
+          backendUrl, frontendUrl, gatewayUrl, backfill: !!opts.backfill,
+        });
         if (!ok) return;
         setupSucceeded = true;
 
@@ -112,6 +116,7 @@ Examples:
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
+    .option('--backfill', 'Seed historical Claude Code / Codex 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())
@@ -127,6 +132,7 @@ 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 --admin-api-key <ADMIN_KEY> --discovery-key <DISCOVERY_KEY> --backfill
 `)
     .action(async (opts) => {
       let setupSucceeded = false;
@@ -148,7 +154,9 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing MDM tool bundle');
-        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { backendUrl, gatewayUrl });
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, {
+          backendUrl, gatewayUrl, backfill: !!opts.backfill,
+        });
         if (!ok) return;
         setupSucceeded = true;
 

package/src/commands/setup.js

@@ -212,20 +212,42 @@ async function runPythonScriptWindows(scriptPath, args, { capture }) {
  * own defaults. `mdm: true` skips --domain (frontend URL) since MDM scripts
  * have no browser-auth flow.
  */
-function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm } = {}) {
+function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm, backfill } = {}) {
   let args = `--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 (clear) args += ' --clear';
+  if (backfill) args += ' --backfill';
   return args;
 }
 
+// Backfill only applies to the hooks variants of Claude Code / Codex; gateway
+// mode and Cursor have no local transcripts to seed.
+function scriptSupportsBackfill(scriptPath) {
+  return scriptPath.includes('/hooks/') && (
+    scriptPath.startsWith('claude-code/') || scriptPath.startsWith('codex/')
+  );
+}
+
+// Surfaces an early note when --backfill was requested for a tool that can't
+// use it. The setup scripts no-op safely too, but earlier user signal is better UX.
+function noteBackfillUnsupported(label, scriptPath) {
+  if (scriptPath.startsWith('cursor/')) {
+    output.info(`${label} backfill is not supported (no historical transcript data on disk). Continuing without backfill for ${label}.`);
+    return;
+  }
+  if (scriptPath.includes('/gateway/')) {
+    output.info(`--backfill is not supported in gateway mode for ${label}. Continuing without backfill for ${label}.`);
+    return;
+  }
+}
+
 /**
  * Runs a Python setup script from the setup repo with inherited stdio (live output).
  */
-async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl, gatewayUrl } = {}) {
-  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear });
+async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
+  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, backfill });
   console.log('');
   if (isWindowsNative()) {
     await runPythonScriptWindows(scriptPath, args, { capture: false });
@@ -318,6 +340,7 @@ function register(program) {
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
     .option('--all', 'Set up the default bundle: Cursor, Claude Code (hooks), Codex (hooks)')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
     .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())
@@ -349,6 +372,10 @@ Examples:
   $ unbound setup --all                                    Set up the default bundle
   $ unbound setup --all --api-key <key>                    Login + set up the bundle
 
+  Seed historical sessions (Claude Code / Codex subscription mode only):
+  $ unbound setup claude-code --subscription --backfill   Install hooks AND backfill local history
+  $ unbound setup codex --subscription --backfill         Install hooks AND backfill local history
+
   One-step login and setup:
   $ unbound setup cursor --api-key <key>                   Login + set up Cursor
   $ unbound setup cursor claude-code-gateway --api-key <key>
@@ -414,10 +441,18 @@ automatically to authenticate before proceeding.
           const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
           console.log('');
 
-          const interactiveArgs = buildScriptArgs(apiKey, urlOpts);
-          const ok = await runBatch(selectedTools, (tool) =>
-            runScriptPiped(tool.script, interactiveArgs)
-          );
+          if (opts.backfill) {
+            for (const tool of selectedTools) {
+              if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+            }
+          }
+          const ok = await runBatch(selectedTools, (tool) => {
+            const toolArgs = buildScriptArgs(apiKey, {
+              ...urlOpts,
+              backfill: opts.backfill && scriptSupportsBackfill(tool.script),
+            });
+            return runScriptPiped(tool.script, toolArgs);
+          });
           if (!ok) return;
 
           console.log('');
@@ -481,7 +516,10 @@ automatically to authenticate before proceeding.
           const toolName = tools[0];
 
           if (SETUP_TOOL_MAP[toolName]) {
-            await runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear, ...urlOpts });
+            const { script, label } = SETUP_TOOL_MAP[toolName];
+            const backfill = opts.backfill && scriptSupportsBackfill(script);
+            if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
+            await runSetupScript(script, apiKey, { clear: opts.clear, backfill, ...urlOpts });
           } else if (MODE_TOOLS[toolName]) {
             const mode = MODE_TOOLS[toolName];
             if (opts.clear) {
@@ -495,7 +533,10 @@ automatically to authenticate before proceeding.
                 useSubscription = choice === 'subscription';
               }
               const resolved = useSubscription ? mode.subscription : mode.gateway;
-              await runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, urlOpts);
+              const { script, label } = SETUP_TOOL_MAP[resolved];
+              const backfill = opts.backfill && scriptSupportsBackfill(script);
+              if (opts.backfill && !backfill) noteBackfillUnsupported(label, script);
+              await runSetupScript(script, apiKey, { ...urlOpts, backfill });
             }
           } else if (INSTRUCTION_TOOLS[toolName]) {
             output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));
@@ -533,10 +574,19 @@ automatically to authenticate before proceeding.
         // Run automated tools with spinners
         if (resolvedScripts.length > 0) {
           console.log('');
-          const args = buildScriptArgs(apiKey, { ...urlOpts, clear: opts.clear });
-          const ok = await runBatch(resolvedScripts, (tool) =>
-            runScriptPiped(tool.script, args)
-          , { clear: opts.clear });
+          if (opts.backfill) {
+            for (const tool of resolvedScripts) {
+              if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+            }
+          }
+          const ok = await runBatch(resolvedScripts, (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;
         }
 
@@ -572,6 +622,7 @@ automatically to authenticate before proceeding.
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .option('--clear', 'Remove Unbound configuration for the specified tools')
     .option('--all', 'Set up all available tools')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -590,6 +641,8 @@ Examples:
   $ 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 --admin-api-key KEY --clear cursor codex-subscription
+  $ sudo unbound setup mdm --admin-api-key KEY claude-code-subscription --backfill
+                                                           Install hooks AND backfill local history
 `)
     .action(async (tools, opts, command) => {
       try {
@@ -650,16 +703,24 @@ Examples:
         const resolvedTools = toolNames.map(name => ({ name, ...MDM_TOOLS[name] }));
         console.log('');
 
-        const args = buildScriptArgs(opts.adminApiKey, {
-          backendUrl,
-          gatewayUrl,
-          clear: globalOpts.clear,
-          mdm: true,
-        });
+        if (globalOpts.backfill) {
+          for (const tool of resolvedTools) {
+            if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+          }
+        }
 
         const ok = await runBatch(
           resolvedTools,
-          (tool) => runScriptPiped(tool.script, args),
+          (tool) => {
+            const toolArgs = buildScriptArgs(opts.adminApiKey, {
+              backendUrl,
+              gatewayUrl,
+              clear: globalOpts.clear,
+              mdm: true,
+              backfill: globalOpts.backfill && scriptSupportsBackfill(tool.script),
+            });
+            return runScriptPiped(tool.script, toolArgs);
+          },
           { clear: globalOpts.clear }
         );
         if (!ok) return;
@@ -678,10 +739,24 @@ Examples:
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl } = {}) {
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl, backfill = false } = {}) {
   const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
-  const args = buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl });
-  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+  if (backfill) {
+    for (const tool of resolvedTools) {
+      if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+    }
+  }
+  // Build args per-tool so --backfill only goes to tools whose script
+  // actually supports it (Claude Code hooks and Codex hooks). Cursor would
+  // print "not supported"; passing the flag to gateway-mode scripts would
+  // error out — `scriptSupportsBackfill` checks for both.
+  return runBatch(resolvedTools, (tool) => {
+    const args = buildScriptArgs(apiKey, {
+      backendUrl, frontendUrl, gatewayUrl,
+      backfill: backfill && scriptSupportsBackfill(tool.script),
+    });
+    return runScriptPiped(tool.script, args);
+  });
 }
 
 /**
@@ -689,10 +764,20 @@ 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 } = {}) {
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, gatewayUrl, backfill = false } = {}) {
   const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
-  const args = buildScriptArgs(adminApiKey, { backendUrl, gatewayUrl, mdm: true });
-  return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
+  if (backfill) {
+    for (const tool of resolvedTools) {
+      if (!scriptSupportsBackfill(tool.script)) noteBackfillUnsupported(tool.label, tool.script);
+    }
+  }
+  return runBatch(resolvedTools, (tool) => {
+    const args = buildScriptArgs(adminApiKey, {
+      backendUrl, gatewayUrl, mdm: true,
+      backfill: backfill && scriptSupportsBackfill(tool.script),
+    });
+    return runScriptPiped(tool.script, args);
+  });
 }
 
 module.exports = {