unbound-cli 0.2.1 → 0.3.1

package/README.md

@@ -30,6 +30,7 @@ unbound setup
 unbound setup cursor
 ```
 
+
 ## Commands
 
 ### Authentication

package/package.json

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

package/src/auth.js

@@ -6,6 +6,7 @@ const http = require('http');
 const { URL } = require('url');
 const config = require('./config');
 const output = require('./output');
+const api = require('./api');
 
 /**
  * Opens the browser for authentication and waits for the callback.
@@ -102,10 +103,53 @@ async function loginWithBrowser(frontendUrl) {
 }
 
 /**
- * Ensures the user is logged in. If not, triggers browser-based login.
+ * Validates an API key against the backend and stores it.
+ * Shows a spinner during validation and a success message with user info.
+ *
+ * @param {string} apiKey - The API key to validate and store
+ * @returns {Promise<true>}
+ */
+async function loginWithApiKey(apiKey) {
+  const spin = output.spinner('Authenticating...');
+  let response;
+  try {
+    response = await api.get('/api/v1/users/privileges/', { apiKey });
+  } catch (err) {
+    let msg;
+    if (err.statusCode === 401 || err.statusCode === 403) {
+      msg = 'Authentication failed. The API key may be invalid or expired.';
+    } else if (err.statusCode) {
+      msg = `Authentication failed (HTTP ${err.statusCode}). Please try again.`;
+    } else {
+      msg = 'Unable to reach the server. Please check your internet connection.';
+    }
+    spin.fail(msg);
+    err.displayed = true;
+    throw err;
+  }
+  config.setApiKey(apiKey);
+  config.backfillUserInfo(response);
+
+  const parts = [];
+  if (response.email) parts.push(response.email);
+  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');
+
+  return true;
+}
+
+/**
+ * Ensures the user is logged in. If an apiKey is provided, validates and
+ * stores it first. If not logged in, triggers browser-based login.
  * Returns true if logged in (or just logged in), false on failure.
  */
-async function ensureLoggedIn() {
+async function ensureLoggedIn({ apiKey } = {}) {
+  if (apiKey) {
+    await loginWithApiKey(apiKey);
+    return true;
+  }
+
   if (config.isLoggedIn()) {
     return true;
   }
@@ -122,4 +166,4 @@ async function ensureLoggedIn() {
   return true;
 }
 
-module.exports = { loginWithBrowser, ensureLoggedIn };
+module.exports = { loginWithBrowser, loginWithApiKey, ensureLoggedIn };

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 } = require('../auth');
+const { loginWithBrowser, loginWithApiKey } = require('../auth');
 
 function register(program) {
   program
@@ -39,18 +39,13 @@ Examples:
         let apiKey;
 
         if (opts.apiKey) {
-          apiKey = opts.apiKey;
-          // Validate the key before storing
-          const spin = output.spinner('Validating API key...');
           try {
-            await api.get('/api/v1/users/privileges/', { apiKey });
-            spin.stop();
-          } catch (err) {
-            spin.fail('Invalid API key. Check your key and try again.');
+            await loginWithApiKey(opts.apiKey);
+          } catch {
             process.exitCode = 1;
             return;
           }
-          config.setApiKey(apiKey);
+          return;
         } else {
           // Browser flow — key is already saved by auth.loginWithBrowser()
           let frontendUrl;

package/src/commands/setup.js

@@ -27,6 +27,54 @@ const MDM_TOOLS = {
 // Default tools for --all (uses subscription mode for Claude Code and Codex since only one can be active)
 const MDM_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription'];
 
+// Tool name → script mapping for automated tools
+const SETUP_TOOL_MAP = {
+  'cursor':                   { label: 'Cursor',                     script: 'cursor/setup.py' },
+  'claude-code-subscription': { label: 'Claude Code (subscription)', script: 'claude-code/hooks/setup.py' },
+  'claude-code-gateway':      { label: 'Claude Code (gateway)',      script: 'claude-code/gateway/setup.py' },
+  'gemini-cli':               { label: 'Gemini CLI',                 script: 'gemini-cli/gateway/setup.py' },
+  'codex-subscription':       { label: 'Codex (subscription)',       script: 'codex/hooks/setup.py' },
+  'codex-gateway':            { label: 'Codex (gateway)',            script: 'codex/gateway/setup.py' },
+};
+
+// Instruction-only tools (display config values, no setup scripts)
+const INSTRUCTION_TOOLS = {
+  'roo-code':      { label: 'Roo Code',     values: (apiKey) => [['API Provider', 'unbound'], ['API Key', apiKey]] },
+  'cline':         { label: 'Cline',         values: (apiKey, frontendUrl) => [['API Provider', 'OpenAI Compatible'], ['Base URL', frontendUrl], ['API Key', apiKey]] },
+  'kilo-code':     { label: 'Kilo Code',     values: (apiKey) => [['API Provider', 'Unbound'], ['API Key', apiKey]] },
+  'custom-access': { label: 'Custom Access', values: (apiKey, frontendUrl) => [['API Key', apiKey], ['Base URL', frontendUrl]] },
+};
+
+// Tools that need interactive mode selection (claude-code, codex without suffix)
+const MODE_TOOLS = {
+  'claude-code': {
+    prompt: 'How do you want to use Claude Code with Unbound?',
+    options: [
+      { label: 'Use my Claude subscription (hooks)', value: 'subscription' },
+      { label: 'Use Unbound as the AI provider (gateway)', value: 'gateway' },
+    ],
+    subscription: 'claude-code-subscription',
+    gateway: 'claude-code-gateway',
+  },
+  'codex': {
+    prompt: 'How do you want to use Codex with Unbound?',
+    options: [
+      { label: 'Use my OpenAI subscription (hooks)', value: 'subscription' },
+      { label: 'Use Unbound as the AI provider (gateway)', value: 'gateway' },
+    ],
+    subscription: 'codex-subscription',
+    gateway: 'codex-gateway',
+  },
+};
+
+/**
+ * Escapes a string for safe embedding in a shell command.
+ * Wraps in single quotes and escapes any embedded single quotes.
+ */
+function shellEscape(str) {
+  return "'" + str.replace(/'/g, "'\\''") + "'";
+}
+
 /**
  * Builds a shell command that curls a setup script and pipes it to python3.
  */
@@ -39,7 +87,7 @@ 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 "${apiKey}"${clear ? ' --clear' : ''}`;
+  const args = `--api-key ${shellEscape(apiKey)}${clear ? ' --clear' : ''}`;
   console.log('');
   try {
     execSync(buildSetupCommand(scriptPath, args), { stdio: 'inherit' });
@@ -111,418 +159,218 @@ async function runBatch(tools, runFn, { clear = false } = {}) {
   return true;
 }
 
-/**
- * Ensures login, gets the stored API key, and runs the setup script(s).
- */
-function makeAction(...scriptPaths) {
-  return async (opts) => {
-    try {
-      await ensureLoggedIn();
-      const apiKey = config.getApiKey();
-
-      for (const scriptPath of scriptPaths) {
-        runSetupScript(scriptPath, apiKey, { clear: opts.clear });
-      }
-    } catch (err) {
-      output.error(err.message);
-      process.exitCode = 1;
-    }
-  };
-}
-
 function register(program) {
   const setup = program
     .command('setup')
+    .argument('[tools...]', 'Tools to set up')
     .description(
       'Configure AI coding tools to use Unbound as their API gateway. ' +
-      'Supported tools: cursor, claude-code, gemini-cli, codex, roo-code, cline, kilo-code, custom-access.'
+      'Run with no arguments for interactive setup, or specify tools directly.'
     )
+    .option('--api-key <key>', 'Authenticate with an API key (skips browser login)')
+    .option('--clear', 'Remove Unbound configuration for the specified tools')
+    .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
+    .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
     .addHelpText('after', `
-Interactive batch setup:
-  $ unbound setup                # Select and install multiple tools at once
-
-Single-tool setup (downloads scripts, sets env vars, configures tool):
-  $ unbound setup cursor         # Download hooks, set env, restart Cursor
-  $ unbound setup claude-code    # Set up gateway + hooks for Claude Code
-  $ unbound setup gemini-cli     # Set GEMINI_API_KEY and base URL
-  $ unbound setup codex          # Set up gateway + hooks for Codex
-
-Instruction-only (shows API key and base URL to configure manually):
-  $ unbound setup roo-code       # Show Roo Code config values
-  $ unbound setup cline          # Show Cline config values
-  $ unbound setup kilo-code      # Show Kilo Code config values
-  $ unbound setup custom-access  # Show API key and base URL for direct API access
-
-All setup commands require login. If not logged in, the browser will
-open automatically to authenticate before proceeding.
-`)
-    // Parent action: runs when `unbound setup` is invoked with no subcommand.
-    // Subcommand actions (cursor, claude-code, etc.) take precedence when specified.
-    .action(async () => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-
-        const selected = await output.multiSelect(
-          'Select tools to set up with Unbound:',
-          SETUP_TOOLS
-        );
-
-        if (selected.length === 0) {
-          output.warn('No tools selected.');
-          return;
-        }
-
-        const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
-        console.log('');
-
-        const ok = await runBatch(selectedTools, (tool) =>
-          runScriptPiped(tool.script, `--api-key "${apiKey}"`)
-        );
-        if (!ok) return;
-
-        console.log('');
-        output.success('All tools configured');
-      } catch (err) {
-        if (err.message === 'Selection cancelled') return;
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  setup
-    .command('cursor')
-    .description(
-      'Set up Cursor to use Unbound. Downloads hook scripts, sets the ' +
-      'UNBOUND_CURSOR_API_KEY environment variable, and restarts Cursor.'
-    )
-    .option('--clear', 'Remove Unbound configuration for Cursor')
-    .addHelpText('after', `
-What this does:
-  1. Downloads Cursor hook scripts from the Unbound setup repository
-  2. Sets the UNBOUND_CURSOR_API_KEY environment variable in your shell profile
-  3. Restarts Cursor to apply changes
-
-Prerequisites:
-  - Must be logged in (will auto-open browser to authenticate if not)
-  - Python 3 and curl must be installed
-  - Cursor must be installed
+Available tools:
+  cursor                    Cursor IDE
+  claude-code               Claude Code (use --subscription or --gateway)
+  gemini-cli                Gemini CLI
+  codex                     Codex (use --subscription or --gateway)
+  roo-code                  Roo Code (shows config values)
+  cline                     Cline (shows config values)
+  kilo-code                 Kilo Code (shows config values)
+  custom-access             Direct API access (shows config values)
+
+For multi-tool setup, use explicit mode names:
+  claude-code-subscription  Claude Code with your own subscription (hooks)
+  claude-code-gateway       Claude Code with Unbound as AI provider
+  codex-subscription        Codex with your own subscription (hooks)
+  codex-gateway             Codex with Unbound as AI provider
 
 Examples:
-  $ unbound setup cursor
-  $ unbound setup cursor --clear   # Remove Unbound configuration
+  Single tool:
+  $ unbound setup cursor                                   Set up Cursor
+  $ unbound setup claude-code --gateway                    Claude Code gateway mode
+  $ unbound setup claude-code --subscription               Claude Code hooks only
+  $ unbound setup codex --gateway                          Codex gateway mode
+
+  One-step login and setup:
+  $ unbound setup cursor --api-key <key>                   Login + set up Cursor
+  $ unbound setup cursor claude-code-gateway --api-key <key>
+                                                           Login + set up multiple tools
+
+  Remove configuration:
+  $ unbound setup cursor --clear                           Remove Cursor config
+  $ unbound setup claude-code --clear                      Remove Claude Code config
+
+  Interactive:
+  $ unbound setup                                          Select tools interactively
+  $ unbound setup --api-key <key>                          Login, then select interactively
+
+If not logged in and --api-key is not provided, the browser will open
+automatically to authenticate before proceeding.
 `)
-    .action(makeAction('cursor/setup.py'));
+    .action(async (tools, opts) => {
+      try {
+        await ensureLoggedIn({ apiKey: opts.apiKey });
+        const apiKey = config.getApiKey();
+        const frontendUrl = config.getFrontendUrl();
 
-  setup
-    .command('claude-code')
-    .description(
-      'Set up Claude Code to use Unbound. Prompts whether to use your existing ' +
-      'Claude subscription or use Unbound as the AI provider.'
-    )
-    .option('--subscription', 'Use your existing Claude subscription (hooks only)')
-    .option('--gateway', 'Use Unbound as the AI provider (gateway mode)')
-    .option('--clear', 'Remove Unbound configuration for Claude Code')
-    .addHelpText('after', `
-Modes:
-  Subscription (hooks only):
-    Keep your existing Claude subscription. Installs Unbound hooks for
-    policy enforcement (security guardrails, cost limits) without changing
-    the AI provider. Runs claude-code/hooks/setup.py.
+        // No tools specified → interactive multi-select (existing flow)
+        if (tools.length === 0) {
+          const selected = await output.multiSelect(
+            'Select tools to set up with Unbound:',
+            SETUP_TOOLS
+          );
 
-  Gateway:
-    Use Unbound as the AI provider. Routes all Claude Code requests through
-    the Unbound gateway for full policy enforcement and model management.
-    Runs claude-code/gateway/setup.py.
+          if (selected.length === 0) {
+            output.warn('No tools selected.');
+            return;
+          }
 
-  If neither --subscription nor --gateway is provided, an interactive
-  prompt will ask you to choose.
+          const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
+          console.log('');
 
-Prerequisites:
-  - Must be logged in (will auto-open browser to authenticate if not)
-  - Python 3 and curl must be installed
-  - Claude Code must be installed
+          const ok = await runBatch(selectedTools, (tool) =>
+            runScriptPiped(tool.script, `--api-key ${shellEscape(apiKey)}`)
+          );
+          if (!ok) return;
 
-Examples:
-  $ unbound setup claude-code                # Interactive mode selection
-  $ unbound setup claude-code --subscription # Hooks only (keep your subscription)
-  $ unbound setup claude-code --gateway      # Use Unbound as AI provider
-  $ unbound setup claude-code --clear        # Remove Unbound configuration
-`)
-    .action(async (opts) => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-        const scriptOpts = { clear: opts.clear };
+          console.log('');
+          output.success('All tools configured');
+          return;
+        }
 
+        // Validate --subscription and --gateway mutual exclusivity
         if (opts.subscription && opts.gateway) {
           output.error('Cannot use both --subscription and --gateway. Choose one.');
           process.exitCode = 1;
           return;
         }
 
-        let useSubscription = opts.subscription;
-        if (!opts.clear && !opts.subscription && !opts.gateway) {
-          const mode = await output.select('How do you want to use Claude Code with Unbound?', [
-            { label: 'Use my Claude subscription (hooks)', value: 'subscription' },
-            { label: 'Use Unbound as the AI provider (gateway)', value: 'gateway' },
-          ]);
-          useSubscription = mode === 'subscription';
-        }
+        // Deduplicate tool names
+        tools = [...new Set(tools)];
 
-        if (opts.clear) {
-          runSetupScript('claude-code/hooks/setup.py', apiKey, scriptOpts);
-          runSetupScript('claude-code/gateway/setup.py', apiKey, scriptOpts);
-        } else if (useSubscription) {
-          runSetupScript('claude-code/hooks/setup.py', apiKey, scriptOpts);
-        } else {
-          runSetupScript('claude-code/gateway/setup.py', apiKey, scriptOpts);
+        // Validate all tool names
+        const allKnown = { ...SETUP_TOOL_MAP, ...MODE_TOOLS, ...INSTRUCTION_TOOLS };
+        const invalid = tools.filter(t => !allKnown[t]);
+        if (invalid.length > 0) {
+          output.error(`Unknown tool(s): ${invalid.join(', ')}`);
+          console.error('  Run "unbound setup --help" to see available tools.');
+          process.exitCode = 1;
+          return;
         }
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
 
-  setup
-    .command('gemini-cli')
-    .description(
-      'Set up Gemini CLI to use Unbound. Sets GEMINI_API_KEY and ' +
-      'GOOGLE_GEMINI_BASE_URL environment variables.'
-    )
-    .option('--clear', 'Remove Unbound configuration for Gemini CLI')
-    .addHelpText('after', `
-What this does:
-  1. Sets GEMINI_API_KEY to your Unbound API key in your shell profile
-  2. Sets GOOGLE_GEMINI_BASE_URL to the Unbound gateway endpoint
-  3. Gemini CLI will route all requests through Unbound
-
-Prerequisites:
-  - Must be logged in (will auto-open browser to authenticate if not)
-  - Python 3 and curl must be installed
-  - Gemini CLI must be installed
-
-Examples:
-  $ unbound setup gemini-cli
-  $ unbound setup gemini-cli --clear   # Remove Unbound configuration
-`)
-    .action(makeAction('gemini-cli/gateway/setup.py'));
-
-  setup
-    .command('codex')
-    .description(
-      'Set up Codex to use Unbound. Prompts whether to use your existing ' +
-      'OpenAI subscription or use Unbound as the AI provider.'
-    )
-    .option('--subscription', 'Use your existing OpenAI subscription (hooks only)')
-    .option('--gateway', 'Use Unbound as the AI provider (gateway mode)')
-    .option('--clear', 'Remove Unbound configuration for Codex')
-    .addHelpText('after', `
-Modes:
-  Subscription (hooks only):
-    Keep your existing OpenAI subscription. Installs Unbound hooks for
-    policy enforcement (security guardrails, cost limits) without changing
-    the AI provider. Runs codex/hooks/setup.py.
-
-  Gateway:
-    Use Unbound as the AI provider. Routes all Codex requests through
-    the Unbound gateway for full policy enforcement and model management.
-    Runs codex/gateway/setup.py.
-
-  If neither --subscription nor --gateway is provided, an interactive
-  prompt will ask you to choose.
-
-Prerequisites:
-  - Must be logged in (will auto-open browser to authenticate if not)
-  - Python 3 and curl must be installed
-  - Codex must be installed
-
-Examples:
-  $ unbound setup codex                # Interactive mode selection
-  $ unbound setup codex --subscription # Hooks only (keep your subscription)
-  $ unbound setup codex --gateway      # Use Unbound as AI provider
-  $ unbound setup codex --clear        # Remove Unbound configuration
-`)
-    .action(async (opts) => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-        const scriptOpts = { clear: opts.clear };
-
-        if (opts.subscription && opts.gateway) {
-          output.error('Cannot use both --subscription and --gateway. Choose one.');
+        // Validate mutual exclusivity
+        if (tools.includes('claude-code-subscription') && tools.includes('claude-code-gateway')) {
+          output.error('Cannot set up both claude-code-subscription and claude-code-gateway. Choose one.');
           process.exitCode = 1;
           return;
         }
-
-        let useSubscription = opts.subscription;
-        if (!opts.clear && !opts.subscription && !opts.gateway) {
-          const mode = await output.select('How do you want to use Codex with Unbound?', [
-            { label: 'Use my OpenAI subscription (hooks)', value: 'subscription' },
-            { label: 'Use Unbound as the AI provider (gateway)', value: 'gateway' },
-          ]);
-          useSubscription = mode === 'subscription';
+        if (tools.includes('codex-subscription') && tools.includes('codex-gateway')) {
+          output.error('Cannot set up both codex-subscription and codex-gateway. Choose one.');
+          process.exitCode = 1;
+          return;
         }
 
-        if (opts.clear) {
-          runSetupScript('codex/hooks/setup.py', apiKey, scriptOpts);
-          runSetupScript('codex/gateway/setup.py', apiKey, scriptOpts);
-        } else if (useSubscription) {
-          runSetupScript('codex/hooks/setup.py', apiKey, scriptOpts);
-        } else {
-          runSetupScript('codex/gateway/setup.py', apiKey, scriptOpts);
+        // Validate no bare + suffixed name conflicts
+        if (tools.includes('claude-code') && (tools.includes('claude-code-subscription') || tools.includes('claude-code-gateway'))) {
+          output.error('Cannot combine claude-code with claude-code-subscription or claude-code-gateway.');
+          console.error('  Use --subscription or --gateway with claude-code, or use the explicit name directly.');
+          process.exitCode = 1;
+          return;
+        }
+        if (tools.includes('codex') && (tools.includes('codex-subscription') || tools.includes('codex-gateway'))) {
+          output.error('Cannot combine codex with codex-subscription or codex-gateway.');
+          console.error('  Use --subscription or --gateway with codex, or use the explicit name directly.');
+          process.exitCode = 1;
+          return;
         }
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  // --- Instruction-only tools ---
-
-  setup
-    .command('roo-code')
-    .description('Show setup values for Roo Code (VS Code extension). Displays the API provider and API key to configure in Roo Code settings.')
-    .addHelpText('after', `
-Output:
-  API Provider - Select "unbound" in Roo Code provider settings
-  API Key      - Your Unbound API key to paste into the extension
-
-To configure:
-  1. Open Command Palette (Ctrl/Cmd + Shift + P)
-  2. Type "Roo Code: Open Settings"
-  3. Select "unbound" as the API provider
-  4. Paste the API key shown below
-  5. Select your preferred model from the dropdown
-
-Examples:
-  $ unbound setup roo-code
-`)
-    .action(async () => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-
-        output.keyValue([
-          ['API Provider', 'unbound'],
-          ['API Key', apiKey],
-        ]);
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  setup
-    .command('cline')
-    .description('Show setup values for Cline (VS Code extension). Displays the API provider, Base URL, and API key to configure in Cline settings.')
-    .addHelpText('after', `
-Output:
-  API Provider - Use "OpenAI Compatible" in Cline provider settings
-  Base URL     - The Unbound gateway URL to paste as the Base URL
-  API Key      - Your Unbound API key to paste into the extension
-
-To configure:
-  1. Open Cline extension in VS Code
-  2. Select "Bring your own API key"
-  3. Set API Provider to "OpenAI Compatible"
-  4. Paste the Base URL and API Key shown below
-  5. Select a model (e.g., gpt-5.1)
-
-Examples:
-  $ unbound setup cline
-`)
-    .action(async () => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-        const frontendUrl = config.getFrontendUrl();
-
-        output.keyValue([
-          ['API Provider', 'OpenAI Compatible'],
-          ['Base URL', frontendUrl],
-          ['API Key', apiKey],
-        ]);
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
-
-  setup
-    .command('kilo-code')
-    .description('Show setup values for Kilo Code (VS Code extension or CLI). Displays the API provider and API key to configure in Kilo Code.')
-    .addHelpText('after', `
-Output:
-  API Provider - Select "Unbound" in Kilo Code provider settings
-  API Key      - Your Unbound API key to paste into the extension or CLI
-
-To configure (IDE extension):
-  1. Open Extensions (Ctrl/Cmd + Shift + X), install Kilo Code
-  2. Select "Use your own API key"
-  3. Set API Provider to "Unbound"
-  4. Paste the API Key shown below
-  5. Select a model (e.g., claude-opus-4-5, gpt-5.1)
-
-To configure (CLI):
-  1. Install: npm install -g @kilocode/cli
-  2. Run: kilocode
-  3. Set API Provider to "Unbound"
-  4. Paste the API Key shown below
-
-Examples:
-  $ unbound setup kilo-code
-`)
-    .action(async () => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-
-        output.keyValue([
-          ['API Provider', 'Unbound'],
-          ['API Key', apiKey],
-        ]);
-      } catch (err) {
-        output.error(err.message);
-        process.exitCode = 1;
-      }
-    });
 
-  setup
-    .command('custom-access')
-    .description('Show API key and base URL for direct API access. Use this to build custom integrations with the Unbound gateway.')
-    .addHelpText('after', `
-Output:
-  API Key   - Your Unbound API key for authentication
-  Base URL  - The Unbound gateway endpoint for API requests
+        // Validate --subscription/--gateway only with tools that need them
+        if ((opts.subscription || opts.gateway) && !tools.some(t => MODE_TOOLS[t])) {
+          output.warn('--subscription and --gateway only apply to claude-code and codex. Ignoring.');
+        }
 
-The Base URL is OpenAI-compatible. Use it with any OpenAI SDK or HTTP client:
+        // Single tool → live output (inherited stdio)
+        if (tools.length === 1) {
+          const toolName = tools[0];
+
+          if (SETUP_TOOL_MAP[toolName]) {
+            runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear });
+          } 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 });
+            } else {
+              let useSubscription = opts.subscription;
+              if (!opts.subscription && !opts.gateway) {
+                const choice = await output.select(mode.prompt, mode.options);
+                useSubscription = choice === 'subscription';
+              }
+              const resolved = useSubscription ? mode.subscription : mode.gateway;
+              runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, {});
+            }
+          } else if (INSTRUCTION_TOOLS[toolName]) {
+            output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));
+          }
+          return;
+        }
 
-  curl -X POST {base_url}/v1/chat/completions \\
-    -H "Authorization: Bearer {api_key}" \\
-    -H "Content-Type: application/json" \\
-    -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'
+        // Multi-tool → resolve all tools, then batch with spinners
+        const resolvedScripts = [];  // { label, script } for automated tools
+        const instructionResults = [];  // toolName for instruction-only
+
+        for (const toolName of tools) {
+          if (SETUP_TOOL_MAP[toolName]) {
+            resolvedScripts.push({ ...SETUP_TOOL_MAP[toolName], name: toolName });
+          } else if (MODE_TOOLS[toolName]) {
+            const mode = MODE_TOOLS[toolName];
+            if (opts.clear) {
+              // Expand to both scripts for clearing
+              resolvedScripts.push({ ...SETUP_TOOL_MAP[mode.subscription], name: mode.subscription });
+              resolvedScripts.push({ ...SETUP_TOOL_MAP[mode.gateway], name: mode.gateway });
+            } else {
+              let useSubscription = opts.subscription;
+              if (!opts.subscription && !opts.gateway) {
+                const choice = await output.select(mode.prompt, mode.options);
+                useSubscription = choice === 'subscription';
+              }
+              const resolved = useSubscription ? mode.subscription : mode.gateway;
+              resolvedScripts.push({ ...SETUP_TOOL_MAP[resolved], name: resolved });
+            }
+          } else if (INSTRUCTION_TOOLS[toolName]) {
+            instructionResults.push(toolName);
+          }
+        }
 
-Or with the Python SDK:
-  pip install unbound-gateway
-  from unbound import Unbound
-  client = Unbound(base_url="{base_url}", api_key="{api_key}")
+        // Run automated tools with spinners
+        if (resolvedScripts.length > 0) {
+          console.log('');
+          const args = `--api-key ${shellEscape(apiKey)}${opts.clear ? ' --clear' : ''}`;
+          const ok = await runBatch(resolvedScripts, (tool) =>
+            runScriptPiped(tool.script, args)
+          , { clear: opts.clear });
+          if (!ok) return;
+        }
 
-Examples:
-  $ unbound setup custom-access
-`)
-    .action(async () => {
-      try {
-        await ensureLoggedIn();
-        const apiKey = config.getApiKey();
-        const frontendUrl = config.getFrontendUrl();
+        // Display instruction-only tool values
+        for (const toolName of instructionResults) {
+          console.log('');
+          output.info(`${INSTRUCTION_TOOLS[toolName].label}:`);
+          output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));
+        }
 
-        output.keyValue([
-          ['API Key', apiKey],
-          ['Base URL', frontendUrl],
-        ]);
+        if (resolvedScripts.length > 0) {
+          console.log('');
+          output.success(opts.clear ? 'All tools cleared' : 'All tools configured');
+        }
       } catch (err) {
-        output.error(err.message);
+        if (err.message === 'Selection cancelled') return;
+        if (!err.displayed) output.error(err.message);
         process.exitCode = 1;
       }
     });
@@ -607,8 +455,8 @@ Examples:
         console.log('');
 
         const mdmArgs = (tool) => {
-          let args = `--api_key "${opts.adminApiKey}"`;
-          if (opts.url) args += ` --url "${opts.url}"`;
+          let args = `--api-key ${shellEscape(opts.adminApiKey)}`;
+          if (opts.url) args += ` --url ${shellEscape(opts.url)}`;
           if (opts.clear) args += ' --clear';
           return args;
         };

package/src/index.js

@@ -34,6 +34,12 @@ TOOL SETUP
   $ unbound setup codex --gateway          Use Unbound as AI provider
   $ unbound setup codex --subscription     Hooks only (keep your subscription)
 
+  One-step login and setup (--api-key):
+  $ unbound setup cursor --api-key <key>   Login and set up Cursor
+  $ unbound setup cursor claude-code-gateway --api-key <key>
+                                           Login and set up multiple tools
+  $ unbound setup --api-key <key>          Login, then select interactively
+
   Instruction-only (shows config values to set manually):
   $ unbound setup roo-code                 Show Roo Code config values
   $ unbound setup cline                    Show Cline config values