unbound-cli 0.5.0 → 0.5.1

package/LOCAL_DEV.md

@@ -43,6 +43,47 @@ node src/index.js config reset-url
 node src/index.js config reset-frontend-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:
+
+- 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`).
+
+Both flags are hidden from `--help` (dev-only) and work on every setup-invoking command:
+
+```bash
+# Single tool — override backend only, or both
+node src/index.js setup cursor --backend-url http://localhost:8000
+node src/index.js setup cursor --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+node src/index.js setup claude-code --gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Default bundle
+node src/index.js setup --all --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Multiple explicit tools
+node src/index.js setup cursor claude-code-gateway --backend-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# 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
+
+# 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
+```
+
+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 a no-op there; only `--backend-url` is meaningful.
+
 ## Verify config
 
 ```bash

package/package.json

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

package/src/commands/onboard.js

@@ -27,6 +27,8 @@ 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', DEFAULT_DOMAIN)
+    .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())
     .addHelpText('after', `
 Runs the full onboarding flow for an end user:
   1. Logs in with --api-key and stores credentials.
@@ -54,7 +56,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing tool bundle');
-        const ok = await runSetupAllBundle(apiKey);
+        const ok = await runSetupAllBundle(apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;
 
@@ -87,7 +89,8 @@ 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', DEFAULT_DOMAIN)
-    .addOption(new Option('--url <url>', 'Override backend URL for setup scripts').hideHelp())
+    .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())
     .addHelpText('after', `
 Runs the full MDM onboarding flow for device enrollment:
   1. Installs the MDM tool bundle: ${MDM_ALL_TOOLS.join(', ')}.
@@ -108,7 +111,7 @@ Examples:
 
         console.log('');
         output.info('Step 1/2: Installing MDM tool bundle');
-        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { url: opts.url });
+        const ok = await runMdmSetupAllBundle(opts.adminApiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
         if (!ok) return;
         setupSucceeded = true;
 

package/src/commands/setup.js

@@ -90,8 +90,11 @@ function buildSetupCommand(scriptPath, args) {
 /**
  * Runs a Python setup script from the setup repo with inherited stdio (live output).
  */
-function runSetupScript(scriptPath, apiKey, { clear = false } = {}) {
-  const args = `--api-key ${shellEscape(apiKey)}${clear ? ' --clear' : ''}`;
+function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl } = {}) {
+  let args = `--api-key ${shellEscape(apiKey)}`;
+  if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
+  if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
+  if (clear) args += ' --clear';
   console.log('');
   try {
     execSync(buildSetupCommand(scriptPath, args), { stdio: 'inherit' });
@@ -177,6 +180,8 @@ 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)')
+    .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())
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -252,8 +257,11 @@ automatically to authenticate before proceeding.
           const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
           console.log('');
 
+          let interactiveArgs = `--api-key ${shellEscape(apiKey)}`;
+          if (opts.backendUrl) interactiveArgs += ` --backend-url ${shellEscape(opts.backendUrl)}`;
+          if (opts.frontendUrl) interactiveArgs += ` --domain ${shellEscape(opts.frontendUrl)}`;
           const ok = await runBatch(selectedTools, (tool) =>
-            runScriptPiped(tool.script, `--api-key ${shellEscape(apiKey)}`)
+            runScriptPiped(tool.script, interactiveArgs)
           );
           if (!ok) return;
 
@@ -318,13 +326,13 @@ automatically to authenticate before proceeding.
           const toolName = tools[0];
 
           if (SETUP_TOOL_MAP[toolName]) {
-            runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear });
+            runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
           } else if (MODE_TOOLS[toolName]) {
             const mode = MODE_TOOLS[toolName];
             if (opts.clear) {
               // Clear both modes
-              runSetupScript(SETUP_TOOL_MAP[mode.subscription].script, apiKey, { clear: true });
-              runSetupScript(SETUP_TOOL_MAP[mode.gateway].script, apiKey, { clear: true });
+              runSetupScript(SETUP_TOOL_MAP[mode.subscription].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
+              runSetupScript(SETUP_TOOL_MAP[mode.gateway].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
             } else {
               let useSubscription = opts.subscription;
               if (!opts.subscription && !opts.gateway) {
@@ -332,7 +340,7 @@ automatically to authenticate before proceeding.
                 useSubscription = choice === 'subscription';
               }
               const resolved = useSubscription ? mode.subscription : mode.gateway;
-              runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, {});
+              runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
             }
           } else if (INSTRUCTION_TOOLS[toolName]) {
             output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));
@@ -370,7 +378,10 @@ automatically to authenticate before proceeding.
         // Run automated tools with spinners
         if (resolvedScripts.length > 0) {
           console.log('');
-          const args = `--api-key ${shellEscape(apiKey)}${opts.clear ? ' --clear' : ''}`;
+          let args = `--api-key ${shellEscape(apiKey)}`;
+          if (opts.backendUrl) args += ` --backend-url ${shellEscape(opts.backendUrl)}`;
+          if (opts.frontendUrl) args += ` --domain ${shellEscape(opts.frontendUrl)}`;
+          if (opts.clear) args += ' --clear';
           const ok = await runBatch(resolvedScripts, (tool) =>
             runScriptPiped(tool.script, args)
           , { clear: opts.clear });
@@ -409,7 +420,6 @@ 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')
-    .addOption(new Option('--url <url>', 'Override backend URL').hideHelp())
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -429,18 +439,22 @@ Examples:
   $ sudo unbound setup mdm --admin-api-key KEY --all
   $ sudo unbound setup mdm --admin-api-key KEY --clear cursor codex-subscription
 `)
-    .action(async (tools, opts) => {
+    .action(async (tools, opts, command) => {
       try {
         checkRoot();
+        // --all and --clear are defined on both this command and the parent `setup` command;
+        // --backend-url and --frontend-url are defined only on the parent `setup` command.
+        // Use optsWithGlobals() so all four work regardless of position relative to `mdm`.
+        const globalOpts = command.optsWithGlobals();
 
-        if (opts.all && tools.length > 0) {
+        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 (opts.all) {
+        if (globalOpts.all) {
           toolNames = MDM_ALL_TOOLS;
         } else if (tools.length > 0) {
           toolNames = tools;
@@ -476,20 +490,21 @@ Examples:
 
         const mdmArgs = (tool) => {
           let args = `--api-key ${shellEscape(opts.adminApiKey)}`;
-          if (opts.url) args += ` --url ${shellEscape(opts.url)}`;
-          if (opts.clear) args += ' --clear';
+          if (globalOpts.backendUrl) args += ` --backend-url ${shellEscape(globalOpts.backendUrl)}`;
+          if (globalOpts.frontendUrl) args += ` --domain ${shellEscape(globalOpts.frontendUrl)}`;
+          if (globalOpts.clear) args += ' --clear';
           return args;
         };
 
         const ok = await runBatch(
           resolvedTools,
           (tool) => runScriptPiped(tool.script, mdmArgs(tool)),
-          { clear: opts.clear }
+          { clear: globalOpts.clear }
         );
         if (!ok) return;
 
         console.log('');
-        output.success(opts.clear ? 'All tools cleared' : 'All tools configured');
+        output.success(globalOpts.clear ? 'All tools cleared' : 'All tools configured');
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;
@@ -502,9 +517,11 @@ Examples:
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey) {
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl } = {}) {
   const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
-  const args = `--api-key ${shellEscape(apiKey)}`;
+  let args = `--api-key ${shellEscape(apiKey)}`;
+  if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
+  if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
 }
 
@@ -513,10 +530,11 @@ async function runSetupAllBundle(apiKey) {
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { url } = {}) {
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl } = {}) {
   const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
   let args = `--api-key ${shellEscape(adminApiKey)}`;
-  if (url) args += ` --url ${shellEscape(url)}`;
+  if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
+  if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
 }