unbound-cli 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to NPM
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/version-check.yml

@@ -0,0 +1,35 @@
+name: Version Check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+
+      - name: Get PR version
+        id: pr_version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Checkout main branch
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          path: main-branch
+
+      - name: Get main version
+        id: main_version
+        run: echo "version=$(node -p "require('./main-branch/package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Compare versions
+        run: |
+          if [ "${{ steps.pr_version.outputs.version }}" = "${{ steps.main_version.outputs.version }}" ]; then
+            echo "::error::Version in package.json (${{ steps.pr_version.outputs.version }}) is the same as main. Please bump the version before merging."
+            exit 1
+          fi
+          echo "Version check passed: main=${{ steps.main_version.outputs.version }} → PR=${{ steps.pr_version.outputs.version }}"

package/LOCAL_DEV.md

@@ -0,0 +1,126 @@
+# Local Development Guide
+
+## Prerequisites
+
+- Node.js >= 18
+- npm
+
+## Setup
+
+```bash
+cd unbound-cli
+npm install
+```
+
+## Run locally (without installing globally)
+
+```bash
+# Run directly
+node src/index.js --help
+node src/index.js status
+node src/index.js policy list
+
+# Or use npm link to get the `unbound` command locally
+npm link
+unbound --help
+```
+
+## Point to local backend
+
+```bash
+# Option 1: Set in config (persists across commands)
+node src/index.js config set-url http://localhost:8000
+node src/index.js config set-frontend-url http://localhost:3000
+
+# Option 2: Environment variable (per-command)
+UNBOUND_API_URL=http://localhost:8000 node src/index.js policy list
+
+# Option 3: Set during login
+node src/index.js login --base-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Reset to production
+node src/index.js config reset-url
+node src/index.js config reset-frontend-url
+```
+
+## Verify config
+
+```bash
+node src/index.js config show
+node src/index.js config get-url
+node src/index.js config get-frontend-url
+```
+
+## Test login flow
+
+```bash
+# Browser-based login (starts local HTTP server, opens browser)
+node src/index.js login --base-url http://localhost:8000 --frontend-url http://localhost:3000
+
+# Direct API key login (skip browser)
+node src/index.js login --base-url http://localhost:8000 --api-key <your-key>
+```
+
+## Test commands
+
+```bash
+# Auth
+node src/index.js whoami
+node src/index.js status
+
+# Policies
+node src/index.js policy list
+node src/index.js policy list --type SECURITY --json
+node src/index.js policy get 1
+node src/index.js policy form-data
+
+# Users
+node src/index.js users list
+node src/index.js users effective-policies 1
+
+# Groups
+node src/index.js user-groups list
+node src/index.js groups list  # alias
+
+# Tools
+node src/index.js tools list
+node src/index.js tools connect CURSOR
+node src/index.js tools approved
+
+# Setup
+node src/index.js setup cursor
+node src/index.js setup claude-code
+```
+
+## Unlink when done
+
+```bash
+npm unlink -g unbound-cli
+```
+
+### Switching environments
+
+```bash
+# Use local backend and frontend
+unbound config set-url http://localhost:8000
+unbound config set-frontend-url http://localhost:3000
+
+# Reset to production
+unbound config reset-url
+unbound config reset-frontend-url
+
+# One-time override via env vars
+UNBOUND_API_URL=http://localhost:8000 UNBOUND_FRONTEND_URL=http://localhost:3000 unbound login
+```
+
+### Configuration
+
+| Command | Description |
+|---------|-------------|
+| `unbound config set-url <url>` | Set API base URL |
+| `unbound config get-url` | Show current API base URL |
+| `unbound config reset-url` | Reset to default URL |
+| `unbound config set-frontend-url <url>` | Set frontend URL |
+| `unbound config get-frontend-url` | Show current frontend URL |
+| `unbound config reset-frontend-url` | Reset to default frontend URL |
+| `unbound config show` | Show all config values |

package/README.md

@@ -0,0 +1,128 @@
+# Unbound CLI
+
+Command-line tool for managing your Unbound AI Gateway. Configure policies, manage users and groups, connect AI coding tools, and set up tools like Cursor, Claude Code, Gemini CLI, and more.
+
+## Installation
+
+```bash
+npm install -g unbound-cli
+```
+
+## Quick Start
+
+```bash
+# Login via browser
+unbound login
+
+# Or login with an API key
+unbound login --api-key <your-api-key>
+
+# Check who you are
+unbound whoami
+
+# List policies
+unbound policy list
+
+# Set up Cursor to use Unbound
+unbound setup cursor
+```
+
+## Commands
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `unbound login` | Sign in via browser or `--api-key` |
+| `unbound logout` | Remove stored credentials |
+| `unbound whoami` | Show current user, org, and role |
+| `unbound status` | Show CLI status and API connectivity |
+
+### Policies (Admin only)
+
+| Command | Description |
+|---------|-------------|
+| `unbound policy list` | List all policies |
+| `unbound policy get <id>` | Get policy details |
+| `unbound policy create --name <n> --type <t>` | Create a policy |
+| `unbound policy update <id>` | Update a policy |
+| `unbound policy delete <id>` | Delete a policy |
+| `unbound policy form-data` | Get reference data for policy creation |
+| `unbound policy effective <id>` | View effective policies for a user/group |
+
+Policy types: `SECURITY`, `MODEL`, `COST`
+
+### Users
+
+| Command | Description |
+|---------|-------------|
+| `unbound users list` | List organization members |
+| `unbound users effective-policies <id>` | View effective policies for a user |
+
+### User Groups (Admin only)
+
+| Command | Description |
+|---------|-------------|
+| `unbound user-groups list` | List all groups |
+| `unbound user-groups get <id>` | Get group details |
+| `unbound user-groups create --name <n>` | Create a group |
+| `unbound user-groups update <id>` | Update a group |
+| `unbound user-groups delete <id>` | Delete a group |
+| `unbound user-groups effective-policies <id>` | View effective policies |
+
+Alias: `unbound groups` works the same as `unbound user-groups`.
+
+### Tools
+
+| Command | Description |
+|---------|-------------|
+| `unbound tools list` | List connected tools |
+| `unbound tools connect <type>` | Connect a tool |
+| `unbound tools approved` | List approved tool types |
+
+Supported tool types: `CLAUDE_CODE`, `CURSOR`, `COPILOT`, `ROO_CODE`, `CLINE`, `GEMINI_CLI`, `CODEX`, `KILO_CODE`, `CUSTOM_ACCESS`
+
+### Setup
+
+Automated setup (downloads scripts, sets env vars, configures tool):
+
+| Command | Description |
+|---------|-------------|
+| `unbound setup cursor` | Download hooks, set env, restart Cursor |
+| `unbound setup claude-code` | Configure gateway + install hooks |
+| `unbound setup gemini-cli` | Set GEMINI_API_KEY and base URL |
+| `unbound setup codex` | Set OPENAI_API_KEY and base URL |
+
+Instruction-only (shows API key and base URL to configure manually):
+
+| Command | Description |
+|---------|-------------|
+| `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 |
+
+
+## Configuration
+
+Config is stored in `~/.unbound/config.json`.
+
+**Backend URL priority** (highest to lowest):
+1. `UNBOUND_API_URL` environment variable
+2. `base_url` in `~/.unbound/config.json` (set via `unbound config set-url`)
+3. Default: `https://backend.getunbound.ai`
+
+**Frontend URL priority** (highest to lowest):
+1. `UNBOUND_FRONTEND_URL` environment variable
+2. `frontend_url` in `~/.unbound/config.json` (set via `unbound config set-frontend-url`)
+3. Default: `https://gateway.getunbound.ai`
+
+
+## Global Options
+
+All list/get commands support `--json` for machine-readable JSON output.
+
+```bash
+unbound policy list --json
+unbound users list --json | jq '.members[].email'
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "unbound-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for Unbound - AI Gateway management",
+  "main": "src/index.js",
+  "bin": {
+    "unbound": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "lint": "eslint src/",
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "unbound",
+    "ai-gateway",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "open": "^10.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,81 @@
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const config = require('./config');
+
+const USER_AGENT = 'UnboundCLI/0.1.0';
+
+class ApiError extends Error {
+  constructor(statusCode, body) {
+    const message = body?.error || body?.message || `HTTP ${statusCode}`;
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}
+
+function request(method, path, { body, query, apiKey } = {}) {
+  const baseUrl = config.getBaseUrl();
+  const key = apiKey || config.getApiKey();
+
+  if (!key) {
+    return Promise.reject(new Error('Not logged in. Run `unbound login` first.'));
+  }
+
+  const url = new URL(path, baseUrl);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null) {
+        url.searchParams.set(k, v);
+      }
+    }
+  }
+
+  const headers = {
+    'Authorization': `Bearer ${key}`,
+    'User-Agent': USER_AGENT,
+    'Accept': 'application/json',
+  };
+
+  if (body) {
+    headers['Content-Type'] = 'application/json';
+  }
+
+  const payload = body ? JSON.stringify(body) : null;
+  const transport = url.protocol === 'https:' ? https : http;
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(url, { method, headers }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        const raw = Buffer.concat(chunks).toString();
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          parsed = raw;
+        }
+
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(parsed);
+        } else {
+          reject(new ApiError(res.statusCode, parsed));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+module.exports = {
+  ApiError,
+  get: (path, opts) => request('GET', path, opts),
+  post: (path, opts) => request('POST', path, opts),
+  put: (path, opts) => request('PUT', path, opts),
+  del: (path, opts) => request('DELETE', path, opts),
+};

package/src/auth.js

@@ -0,0 +1,115 @@
+/**
+ * Shared browser-based authentication flow.
+ * Used by both `login` and `setup` commands.
+ */
+const http = require('http');
+const { URL } = require('url');
+const config = require('./config');
+const output = require('./output');
+
+/**
+ * Opens the browser for authentication and waits for the callback.
+ * Starts a local HTTP server, opens the frontend auth page, and waits
+ * for the redirect with API key, email, and org.
+ *
+ * @param {string} frontendUrl - The frontend URL to open
+ * @returns {Promise<{email: string, orgName: string}>}
+ */
+async function loginWithBrowser(frontendUrl) {
+  const server = http.createServer();
+  let callbackResolve;
+  let callbackReject;
+
+  const callbackPromise = new Promise((resolve, reject) => {
+    callbackResolve = resolve;
+    callbackReject = reject;
+  });
+
+  server.on('request', (req, res) => {
+    const url = new URL(req.url, `http://localhost`);
+
+    if (url.pathname !== '/callback') {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    const apiKey = url.searchParams.get('api_key');
+    const email = url.searchParams.get('email');
+    const orgName = url.searchParams.get('org');
+
+    if (!apiKey) {
+      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.end('<html><body><h2>Authentication failed</h2><p>No API key received. Please try again.</p></body></html>');
+      callbackReject(new Error('No API key received in callback'));
+      server.close();
+      return;
+    }
+
+    config.setApiKey(apiKey);
+    const cfg = config.readConfig();
+    if (email) cfg.email = email;
+    if (orgName) cfg.org_name = orgName;
+    config.writeConfig(cfg);
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
+
+    callbackResolve({ email, orgName });
+    server.close();
+  });
+
+  await new Promise((resolve, reject) => {
+    server.listen(0, '127.0.0.1', resolve);
+    server.on('error', reject);
+  });
+
+  const port = server.address().port;
+  const callbackUrl = `http://localhost:${port}/callback`;
+  const authUrl = `${frontendUrl}/cli/auth?callback=${encodeURIComponent(callbackUrl)}`;
+
+  const open = (await import('open')).default;
+
+  console.log('Opening browser for authentication...');
+  console.log(`If the browser does not open, visit:\n${authUrl}\n`);
+  console.log('Waiting for authentication...');
+
+  await open(authUrl);
+
+  const timeout = setTimeout(() => {
+    callbackReject(new Error('Authentication timed out after 120 seconds'));
+    server.close();
+  }, 120_000);
+
+  try {
+    const result = await callbackPromise;
+    clearTimeout(timeout);
+    return result;
+  } catch (err) {
+    clearTimeout(timeout);
+    throw err;
+  }
+}
+
+/**
+ * Ensures the user is logged in. If not, triggers browser-based login.
+ * Returns true if logged in (or just logged in), false on failure.
+ */
+async function ensureLoggedIn() {
+  if (config.isLoggedIn()) {
+    return true;
+  }
+
+  output.warn('Not logged in. Opening browser to authenticate...\n');
+  const frontendUrl = config.getFrontendUrl();
+  const result = await loginWithBrowser(frontendUrl);
+
+  const parts = [];
+  if (result.email) parts.push(`as ${result.email}`);
+  if (result.orgName) parts.push(`to ${result.orgName}`);
+  output.success(`Logged in successfully${parts.length ? ' ' + parts.join(' ') : ''}.\n`);
+
+  return true;
+}
+
+module.exports = { loginWithBrowser, ensureLoggedIn };

package/src/commands/login.js

@@ -0,0 +1,63 @@
+const config = require('../config');
+const output = require('../output');
+const { loginWithBrowser } = require('../auth');
+
+function register(program) {
+  program
+    .command('login')
+    .description('Authenticate with Unbound. Opens a browser for interactive login, or use --api-key for CI/CD environments.')
+    .option('--api-key <key>', 'Authenticate with an API key directly (non-interactive)')
+    .option('--base-url <url>', 'Set a custom API base URL before logging in')
+    .option('--frontend-url <url>', 'Set a custom frontend URL for browser login')
+    .addHelpText('after', `
+Authentication methods:
+  Browser login (default):
+    Opens a browser to the Unbound frontend for interactive login.
+    A local HTTP server listens for the auth callback with the API key.
+    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.
+
+Options:
+  --base-url sets the backend API URL before authenticating (persisted).
+  --frontend-url sets the frontend URL for browser login (persisted).
+
+Examples:
+  $ unbound login                        # Interactive browser-based login
+  $ unbound login --api-key sk-abc123    # Non-interactive login with API key
+  $ unbound login --base-url http://localhost:8000 --frontend-url http://localhost:3000
+  $ unbound login --base-url https://custom.api.example.com --api-key sk-abc123
+`)
+    .action(async (opts) => {
+      try {
+        if (opts.baseUrl) {
+          config.setBaseUrl(opts.baseUrl);
+        }
+
+        if (opts.frontendUrl) {
+          config.setFrontendUrl(opts.frontendUrl);
+        }
+
+        if (opts.apiKey) {
+          config.setApiKey(opts.apiKey);
+          output.success('Logged in successfully with API key.');
+          return;
+        }
+
+        const frontendUrl = config.getFrontendUrl();
+        const result = await loginWithBrowser(frontendUrl);
+
+        const parts = [];
+        if (result.email) parts.push(`as ${result.email}`);
+        if (result.orgName) parts.push(`to ${result.orgName}`);
+        output.success(`Logged in successfully${parts.length ? ' ' + parts.join(' ') : ''}.`);
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { register };

package/src/commands/logout.js

@@ -0,0 +1,28 @@
+const config = require('../config');
+const output = require('../output');
+
+function register(program) {
+  program
+    .command('logout')
+    .description('Log out of Unbound. Removes stored credentials and configuration from ~/.unbound/config.json.')
+    .addHelpText('after', `
+What this does:
+  Clears all stored credentials (API key, email, organization) from
+  ~/.unbound/config.json. Custom URL settings (base_url, frontend_url)
+  are also removed.
+
+Examples:
+  $ unbound logout
+`)
+    .action(() => {
+      try {
+        config.clearConfig();
+        output.success('Logged out successfully.');
+      } catch (err) {
+        output.error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { register };