@obol/cli 0.1.0

package/bin/obol.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { runSetup } from '../src/setup.js';
+import { runStatus } from '../src/status.js';
+import { runConnect } from '../src/connect.js';
+import { getBalance, getTiers } from '../src/api.js';
+import { loadEnv } from '../src/config.js';
+import pc from 'picocolors';
+
+const command = process.argv[2];
+
+async function main() {
+  switch (command) {
+    case 'setup':
+      await runSetup();
+      break;
+
+    case 'status':
+      await runStatus();
+      break;
+
+    case 'connect':
+      await runConnect(process.argv[3]);
+      break;
+
+    case 'balance': {
+      const env = loadEnv();
+      if (!env.OBOL_GATEWAY_URL || !env.OBOL_JWT_TOKEN) {
+        console.log(pc.red('No agent configured. Run: obol setup'));
+        process.exit(1);
+      }
+      try {
+        const data = await getBalance(env.OBOL_GATEWAY_URL, env.OBOL_JWT_TOKEN);
+        console.log(`\n  ${pc.bold('Credit Balance')}`);
+        console.log(`  ${pc.green('$' + data.balance_usdc.toFixed(2))} USDC available`);
+        if (data.reserved_usdc > 0) {
+          console.log(`  ${pc.yellow('$' + data.reserved_usdc.toFixed(2))} reserved in active sessions`);
+        }
+        console.log();
+      } catch (err) {
+        console.log(pc.red(`  Couldn't fetch balance: ${err.message}`));
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'tiers': {
+      const env = loadEnv();
+      const url = env.OBOL_GATEWAY_URL || 'https://www.obolagents.com';
+      try {
+        const data = await getTiers(url);
+        console.log(`\n  ${pc.bold('Credit Tiers')}\n`);
+        for (const t of data.tiers) {
+          const bonus = t.bonus_pct > 0 ? pc.green(` +${t.bonus_pct}% bonus`) : '';
+          console.log(`  ${pc.bold(t.name.padEnd(10))} $${t.price_usd}  →  ${pc.green(t.credits_usdc + ' credits')}${bonus}`);
+        }
+        console.log();
+      } catch (err) {
+        console.log(pc.red(`  Couldn't fetch tiers: ${err.message}`));
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(`
+  ${pc.bold(pc.green('obol'))} — CLI for the Obol Agent Execution Gateway
+
+  ${pc.bold('Commands:')}
+    ${pc.green('setup')}              Set up a new agent (interactive wizard)
+    ${pc.green('status')}             Check agent health, balance & connections
+    ${pc.green('connect')} ${pc.dim('<provider>')}  Add a service API key (github, slack, etc.)
+    ${pc.green('balance')}            Check your credit balance
+    ${pc.green('tiers')}              Show credit purchase tiers
+    ${pc.green('help')}               Show this help message
+
+  ${pc.bold('Quick start:')}
+    ${pc.dim('$')} npx @obol/cli setup
+`);
+      break;
+
+    default:
+      console.log(pc.red(`  Unknown command: ${command}`));
+      console.log(`  Run ${pc.green('obol help')} to see available commands.`);
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(pc.red(`\n  Something went wrong: ${err.message}`));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@obol/cli",
+  "version": "0.1.0",
+  "description": "CLI for the Obol Agent Execution Gateway",
+  "type": "module",
+  "bin": {
+    "obol": "./bin/obol.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "picocolors": "^1.1.1"
+  }
+}

package/src/api.js

@@ -0,0 +1,103 @@
+/**
+ * Obol Gateway API client — uses built-in fetch (Node 18+).
+ */
+
+class ApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+  }
+}
+
+async function request(url, options = {}) {
+  let res;
+  try {
+    res = await fetch(url, { ...options, signal: AbortSignal.timeout(15000) });
+  } catch (err) {
+    if (err.name === 'TimeoutError') throw new ApiError('Request timed out', 0);
+    throw new ApiError(`Couldn't reach the gateway: ${err.message}`, 0);
+  }
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const body = await res.json();
+      detail = body.detail || JSON.stringify(body);
+    } catch { detail = res.statusText; }
+    throw new ApiError(detail, res.status);
+  }
+  return res.json();
+}
+
+function adminHeaders(adminKey) {
+  return { 'Content-Type': 'application/json', 'x-obol-admin-key': adminKey };
+}
+
+function jwtHeaders(jwt) {
+  return { 'Content-Type': 'application/json', 'Authorization': `Bearer ${jwt}` };
+}
+
+// --- Public API ---
+
+export async function checkHealth(gatewayUrl) {
+  return request(`${gatewayUrl}/healthz`);
+}
+
+export async function registerAgent(gatewayUrl, adminKey, agentId, secret, ownerId) {
+  const body = { agent_id: agentId, secret };
+  if (ownerId) body.owner_id = ownerId;
+  return request(`${gatewayUrl}/v1/agents`, {
+    method: 'POST',
+    headers: adminHeaders(adminKey),
+    body: JSON.stringify(body),
+  });
+}
+
+export async function issueToken(gatewayUrl, adminKey, agentId, policyId) {
+  const body = {};
+  if (policyId) body.policy_id = policyId;
+  return request(`${gatewayUrl}/v1/agents/${agentId}/token`, {
+    method: 'POST',
+    headers: adminHeaders(adminKey),
+    body: JSON.stringify(body),
+  });
+}
+
+export async function createPolicy(gatewayUrl, adminKey, agentId, protocols) {
+  return request(`${gatewayUrl}/v1/agents/${agentId}/policies`, {
+    method: 'POST',
+    headers: adminHeaders(adminKey),
+    body: JSON.stringify({
+      name: 'default',
+      allowed_protocols: protocols,
+      is_default: true,
+    }),
+  });
+}
+
+export async function storeBYOK(gatewayUrl, jwt, provider, apiKey, resourceScopes) {
+  const body = { provider, api_key: apiKey };
+  if (resourceScopes) body.resource_scopes = resourceScopes;
+  return request(`${gatewayUrl}/v1/connections/byok`, {
+    method: 'POST',
+    headers: jwtHeaders(jwt),
+    body: JSON.stringify(body),
+  });
+}
+
+export async function listConnections(gatewayUrl, jwt) {
+  return request(`${gatewayUrl}/v1/connections`, { headers: jwtHeaders(jwt) });
+}
+
+export async function getBalance(gatewayUrl, jwt) {
+  return request(`${gatewayUrl}/v1/credits/balance`, { headers: jwtHeaders(jwt) });
+}
+
+export async function getTiers(gatewayUrl) {
+  return request(`${gatewayUrl}/v1/credits/tiers`);
+}
+
+export async function getAgentInfo(gatewayUrl, adminKey, agentId) {
+  return request(`${gatewayUrl}/v1/agents/${agentId}`, {
+    headers: adminHeaders(adminKey),
+  });
+}

package/src/config.js

@@ -0,0 +1,79 @@
+/**
+ * Read/write .env config file for Obol CLI.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const ENV_PATH = resolve(process.cwd(), '.env');
+
+const OBOL_KEYS = [
+  'OBOL_GATEWAY_URL',
+  'OBOL_AGENT_ID',
+  'OBOL_JWT_TOKEN',
+  'OBOL_WALLET_ADDRESS',
+  'OBOL_ADMIN_API_KEY',
+];
+
+export function loadEnv(path) {
+  const file = path || ENV_PATH;
+  const env = {};
+  if (!existsSync(file)) return env;
+  const lines = readFileSync(file, 'utf-8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    let val = trimmed.slice(eqIdx + 1).trim();
+    // Strip quotes
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    env[key] = val;
+  }
+  return env;
+}
+
+export function saveEnv(vars, path) {
+  const file = path || ENV_PATH;
+  let existing = '';
+  if (existsSync(file)) {
+    existing = readFileSync(file, 'utf-8');
+  }
+
+  // Parse existing lines, update OBOL_ keys, preserve everything else
+  const lines = existing ? existing.split('\n') : [];
+  const updated = new Set();
+  const result = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx !== -1) {
+      const key = trimmed.slice(0, eqIdx).trim();
+      if (key in vars) {
+        result.push(`${key}=${vars[key]}`);
+        updated.add(key);
+        continue;
+      }
+    }
+    result.push(line);
+  }
+
+  // Add new keys that weren't in the file
+  const newKeys = Object.keys(vars).filter(k => !updated.has(k));
+  if (newKeys.length > 0) {
+    if (result.length > 0 && result[result.length - 1].trim() !== '') {
+      result.push('');
+    }
+    result.push('# Obol Agent Configuration');
+    for (const key of newKeys) {
+      result.push(`${key}=${vars[key]}`);
+    }
+  }
+
+  writeFileSync(file, result.join('\n') + '\n');
+  return file;
+}

package/src/connect.js

@@ -0,0 +1,78 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { storeBYOK, listConnections } from './api.js';
+import { loadEnv } from './config.js';
+
+const providerInfo = {
+  stripe: { name: 'Stripe', keyHint: 'Starts with sk_live_ or sk_test_', prefix: 'sk_' },
+  github: { name: 'GitHub', keyHint: 'Personal access token (ghp_ or github_pat_)', prefix: '' },
+  slack: { name: 'Slack', keyHint: 'Bot token (xoxb-...)', prefix: 'xoxb-' },
+  notion: { name: 'Notion', keyHint: 'Internal integration token (ntn_ or secret_)', prefix: '' },
+  discord: { name: 'Discord', keyHint: 'Bot token from Discord Developer Portal', prefix: '' },
+  twitter: { name: 'Twitter/X', keyHint: 'Bearer token from Twitter Developer Portal', prefix: '' },
+};
+
+export async function runConnect(providerArg) {
+  const env = loadEnv();
+
+  if (!env.OBOL_GATEWAY_URL || !env.OBOL_JWT_TOKEN) {
+    console.log();
+    p.log.warn('No agent configured yet.');
+    p.log.info(`Run ${pc.green('npx @obol/cli setup')} first.`);
+    console.log();
+    return;
+  }
+
+  console.log();
+  p.intro(pc.bgGreen(pc.black(' Connect a Service ')));
+
+  // Pick provider
+  let provider = providerArg?.toLowerCase();
+  if (!provider || !providerInfo[provider]) {
+    provider = await p.select({
+      message: 'Which service do you want to connect?',
+      options: Object.entries(providerInfo).map(([key, info]) => ({
+        value: key,
+        label: info.name,
+      })),
+    });
+    if (p.isCancel(provider)) { p.cancel('Cancelled.'); return; }
+  }
+
+  const info = providerInfo[provider];
+
+  // Get API key
+  const apiKey = await p.password({
+    message: `Paste your ${info.name} API key`,
+    validate: (val) => {
+      if (!val || val.length < 10) return `That looks too short. ${info.keyHint}`;
+    },
+  });
+  if (p.isCancel(apiKey)) { p.cancel('Cancelled.'); return; }
+
+  // Store it
+  const s = p.spinner();
+  s.start(`Encrypting and storing your ${info.name} key...`);
+
+  try {
+    const result = await storeBYOK(env.OBOL_GATEWAY_URL, env.OBOL_JWT_TOKEN, provider, apiKey);
+    s.stop(pc.green(`${info.name} connected!`) + pc.dim(` (connection: ${result.connection_id?.slice(0, 8)}...)`));
+  } catch (err) {
+    s.stop(pc.red(`Couldn't connect ${info.name}: ${err.message}`));
+    p.outro(pc.dim('Check your API key and try again.'));
+    process.exit(1);
+  }
+
+  // Show summary
+  s.start('Checking your connections...');
+  try {
+    const data = await listConnections(env.OBOL_GATEWAY_URL, env.OBOL_JWT_TOKEN);
+    const conns = data.connections || data || [];
+    const names = conns.map(c => pc.green(c.provider)).join(', ');
+    s.stop(`${pc.bold('Connected services:')} ${names}`);
+  } catch {
+    s.stop();
+  }
+
+  p.outro(`${info.name} is ready to go! Your agent can now use it via Obol.`);
+}

package/src/setup.js

@@ -0,0 +1,181 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { randomBytes } from 'node:crypto';
+import { checkHealth, registerAgent, issueToken, createPolicy } from './api.js';
+import { saveEnv } from './config.js';
+
+const cheers = ['Nice!', 'Boom!', "Let's go.", 'Easy.', 'Done.'];
+const cheer = () => cheers[Math.floor(Math.random() * cheers.length)];
+
+export async function runSetup() {
+  console.log();
+  p.intro(pc.bgGreen(pc.black(' Welcome to Obol! ')));
+
+  p.log.info("Let's get your agent connected. This takes about 60 seconds.");
+
+  // --- Gateway URL ---
+  const gatewayUrl = await p.text({
+    message: "Where's your Obol gateway?",
+    placeholder: 'https://www.obolagents.com',
+    defaultValue: 'https://www.obolagents.com',
+    validate: (val) => {
+      const v = val || 'https://www.obolagents.com';
+      if (!v.startsWith('http://') && !v.startsWith('https://')) {
+        return 'Should start with http:// or https://';
+      }
+    },
+  });
+  if (p.isCancel(gatewayUrl)) return cancelled();
+  const url = (gatewayUrl || 'https://www.obolagents.com').replace(/\/+$/, '');
+
+  // Verify connectivity
+  const healthSpin = p.spinner();
+  healthSpin.start('Saying hello to the gateway...');
+  try {
+    await checkHealth(url);
+    healthSpin.stop(pc.green('Gateway is up and running! ') + cheer());
+  } catch (err) {
+    healthSpin.stop(pc.red('Hmm, couldn\'t reach the gateway.'));
+    p.log.error(`Make sure it's running at ${pc.bold(url)}`);
+    p.log.error(`Details: ${err.message}`);
+    p.outro(pc.dim('Fix the URL and try again.'));
+    process.exit(1);
+  }
+
+  // --- Admin Key ---
+  const adminKey = await p.password({
+    message: 'Paste your admin API key',
+    validate: (val) => {
+      if (!val || val.length < 8) return 'That looks too short. Check your Render dashboard → Environment Variables → OBOL_ADMIN_API_KEY';
+    },
+  });
+  if (p.isCancel(adminKey)) return cancelled();
+
+  // --- Agent Name ---
+  const agentId = await p.text({
+    message: 'Give your agent a name',
+    placeholder: 'my-agent',
+    validate: (val) => {
+      if (!val) return 'Your agent needs a name!';
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{1,62}[a-zA-Z0-9]$/.test(val)) {
+        return 'Letters, numbers, hyphens, and underscores only (3-64 chars)';
+      }
+    },
+  });
+  if (p.isCancel(agentId)) return cancelled();
+
+  // --- Wallet Address ---
+  const walletAddress = await p.text({
+    message: `Got a USDC wallet on Base? ${pc.dim('(recommended for automatic micropayments)')}`,
+    placeholder: '0x... or press Enter to skip',
+    validate: (val) => {
+      if (!val) return;  // optional
+      if (!/^0x[0-9a-fA-F]{40}$/.test(val)) {
+        return 'That doesn\'t look like an EVM address. Should be 0x followed by 40 hex characters.';
+      }
+    },
+  });
+  if (p.isCancel(walletAddress)) return cancelled();
+
+  // --- Services ---
+  const services = await p.multiselect({
+    message: 'Which services does your agent need?',
+    options: [
+      { value: 'stripe', label: 'Stripe', hint: 'invoices, payments, subscriptions' },
+      { value: 'github', label: 'GitHub', hint: 'issues, PRs, repos' },
+      { value: 'slack', label: 'Slack', hint: 'messages, channels' },
+      { value: 'notion', label: 'Notion', hint: 'pages, databases' },
+      { value: 'discord', label: 'Discord', hint: 'messages, servers' },
+      { value: 'twitter', label: 'Twitter/X', hint: 'tweets, threads' },
+    ],
+    required: true,
+  });
+  if (p.isCancel(services)) return cancelled();
+
+  // --- Confirm ---
+  const confirmed = await p.confirm({
+    message: `Register ${pc.bold(pc.green(agentId))} with ${services.length} service${services.length > 1 ? 's' : ''}?`,
+  });
+  if (p.isCancel(confirmed) || !confirmed) return cancelled();
+
+  // --- Execute! ---
+  console.log();
+  const s = p.spinner();
+
+  // 1. Register agent
+  s.start('Registering your agent...');
+  const secret = randomBytes(32).toString('base64url');
+  try {
+    await registerAgent(url, adminKey, agentId, secret);
+    s.stop(pc.green(`Agent "${agentId}" registered. `) + cheer());
+  } catch (err) {
+    if (err.status === 409) {
+      s.stop(pc.yellow(`Agent "${agentId}" already exists — that's fine, we'll keep going.`));
+    } else {
+      s.stop(pc.red(`Couldn't register agent: ${err.message}`));
+      p.outro(pc.dim('Check your admin key and try again.'));
+      process.exit(1);
+    }
+  }
+
+  // 2. Issue JWT
+  s.start('Getting your agent a JWT token...');
+  let jwt;
+  try {
+    const tokenData = await issueToken(url, adminKey, agentId);
+    jwt = tokenData.token;
+    const expiresAt = new Date(tokenData.expires_at * 1000);
+    s.stop(pc.green('JWT issued ') + pc.dim(`(expires ${expiresAt.toLocaleDateString()})`));
+  } catch (err) {
+    s.stop(pc.red(`Couldn't issue token: ${err.message}`));
+    p.outro(pc.dim('Something went wrong. Try again or check the gateway logs.'));
+    process.exit(1);
+  }
+
+  // 3. Create default policy
+  s.start('Setting up execution policy...');
+  try {
+    await createPolicy(url, adminKey, agentId, services);
+    s.stop(pc.green(`Policy created for ${services.join(', ')}. `) + cheer());
+  } catch (err) {
+    // Non-fatal — agent can still work without a named policy
+    s.stop(pc.yellow(`Couldn't create policy (${err.message}) — no worries, defaults apply.`));
+  }
+
+  // 4. Save config
+  s.start('Saving configuration...');
+  const vars = {
+    OBOL_GATEWAY_URL: url,
+    OBOL_AGENT_ID: agentId,
+    OBOL_JWT_TOKEN: jwt,
+  };
+  if (walletAddress) {
+    vars.OBOL_WALLET_ADDRESS = walletAddress;
+  }
+  const envPath = saveEnv(vars);
+  s.stop(pc.green(`Saved to ${envPath}`));
+
+  // --- Celebration! ---
+  console.log();
+  p.log.success(pc.bold(`Your agent "${agentId}" is live on Obol!`));
+  console.log();
+
+  if (walletAddress) {
+    p.log.info(`Micropayments enabled — your agent pays a few cents per call from ${pc.cyan(walletAddress.slice(0, 6) + '...' + walletAddress.slice(-4))}.`);
+  } else {
+    p.log.info(`No wallet linked. Buy credits with ${pc.green('obol tiers')} or add a wallet later.`);
+  }
+
+  console.log();
+  console.log(`  ${pc.dim('Check status:')}  ${pc.green('npx @obol/cli status')}`);
+  console.log(`  ${pc.dim('Add a key:')}     ${pc.green('npx @obol/cli connect github')}`);
+  console.log(`  ${pc.dim('View balance:')}  ${pc.green('npx @obol/cli balance')}`);
+  console.log();
+
+  p.outro('Go build something awesome. ' + pc.green('⚡'));
+}
+
+function cancelled() {
+  p.cancel('Setup cancelled. Come back anytime!');
+  process.exit(0);
+}

package/src/status.js

@@ -0,0 +1,72 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { checkHealth, getBalance, listConnections } from './api.js';
+import { loadEnv } from './config.js';
+
+export async function runStatus() {
+  const env = loadEnv();
+
+  if (!env.OBOL_GATEWAY_URL || !env.OBOL_AGENT_ID) {
+    console.log();
+    p.log.warn('No agent configured yet.');
+    p.log.info(`Run ${pc.green('npx @obol/cli setup')} to get started.`);
+    console.log();
+    return;
+  }
+
+  console.log();
+  p.intro(pc.bgGreen(pc.black(` ${env.OBOL_AGENT_ID} `)));
+
+  const url = env.OBOL_GATEWAY_URL;
+
+  // Gateway health
+  const s = p.spinner();
+  s.start('Checking gateway...');
+  try {
+    await checkHealth(url);
+    s.stop(pc.green('Gateway is healthy'));
+  } catch (err) {
+    s.stop(pc.red(`Gateway unreachable: ${err.message}`));
+  }
+
+  // Balance
+  if (env.OBOL_JWT_TOKEN) {
+    s.start('Fetching balance...');
+    try {
+      const bal = await getBalance(url, env.OBOL_JWT_TOKEN);
+      const balStr = `$${bal.balance_usdc.toFixed(2)} USDC`;
+      const reserved = bal.reserved_usdc > 0 ? pc.dim(` ($${bal.reserved_usdc.toFixed(2)} reserved)`) : '';
+      s.stop(`${pc.bold('Balance:')} ${pc.green(balStr)}${reserved}`);
+    } catch (err) {
+      s.stop(pc.yellow(`Couldn't fetch balance: ${err.message}`));
+    }
+
+    // Connections
+    s.start('Checking connected services...');
+    try {
+      const data = await listConnections(url, env.OBOL_JWT_TOKEN);
+      const conns = data.connections || data || [];
+      if (conns.length === 0) {
+        s.stop(pc.dim('No services connected yet'));
+        p.log.info(`Add one with ${pc.green('npx @obol/cli connect github')}`);
+      } else {
+        const names = conns.map(c => pc.green(c.provider)).join(', ');
+        s.stop(`${pc.bold('Services:')} ${names} (${conns.length} connected)`);
+      }
+    } catch (err) {
+      s.stop(pc.dim('Couldn\'t fetch connections'));
+    }
+  }
+
+  // Wallet
+  if (env.OBOL_WALLET_ADDRESS) {
+    const addr = env.OBOL_WALLET_ADDRESS;
+    p.log.info(`${pc.bold('Wallet:')} ${pc.cyan(addr.slice(0, 6) + '...' + addr.slice(-4))} ${pc.dim('(USDC micropayments)')}`);
+  } else {
+    p.log.info(`${pc.bold('Wallet:')} ${pc.dim('Not configured')} — add one during setup for automatic micropayments`);
+  }
+
+  p.log.info(`${pc.bold('Gateway:')} ${pc.dim(url)}`);
+
+  p.outro(pc.dim('Looking good!'));
+}