@gopherhole/cli 0.1.23 → 0.2.0

package/src/index.ts

@@ -5,6 +5,7 @@ import Conf from 'conf';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import open from 'open';
+import { A2AClient, GopherHole } from '@gopherhole/sdk';
 
 const config = new Conf({ projectName: 'gopherhole' });
 const API_URL = 'https://gopherhole.ai/api';
@@ -18,7 +19,102 @@ const brand = {
 };
 
 // Version
-const VERSION = '0.1.23';
+const VERSION = '0.2.0';
+
+// ========== API KEY RESOLUTION ==========
+// Precedence: --api-key flag > GOPHERHOLE_API_KEY env var > .env file in cwd
+
+async function resolveApiKey(flagValue?: string): Promise<string | null> {
+  if (flagValue) return flagValue;
+  if (process.env.GOPHERHOLE_API_KEY) return process.env.GOPHERHOLE_API_KEY;
+
+  try {
+    const fs = await import('fs');
+    const path = await import('path');
+    const envPath = path.join(process.cwd(), '.env');
+    if (fs.existsSync(envPath)) {
+      const content = fs.readFileSync(envPath, 'utf-8');
+      const match = content.match(/^GOPHERHOLE_API_KEY=(.+)$/m);
+      if (match) return match[1].trim().replace(/^["']|["']$/g, '');
+    }
+  } catch { /* ignore */ }
+
+  return null;
+}
+
+/** HTTP client for sending A2A messages */
+async function resolveAgentId(flagValue?: string): Promise<string | null> {
+  if (flagValue) return flagValue;
+  if (process.env.GOPHERHOLE_AGENT_ID) return process.env.GOPHERHOLE_AGENT_ID;
+
+  try {
+    const fs = await import('fs');
+    const path = await import('path');
+    const envPath = path.join(process.cwd(), '.env');
+    if (fs.existsSync(envPath)) {
+      const content = fs.readFileSync(envPath, 'utf-8');
+      const match = content.match(/^GOPHERHOLE_AGENT_ID=(.+)$/m);
+      if (match) return match[1].trim().replace(/^["']|["']$/g, '');
+    }
+  } catch { /* ignore */ }
+
+  return null;
+}
+
+function makeAgentClient(apiKey: string): A2AClient {
+  return new A2AClient({
+    apiKey,
+    baseUrl: (process.env.GOPHERHOLE_API_URL || 'https://hub.gopherhole.ai') + '/a2a',
+  });
+}
+
+/** Hub client for workspace/discovery operations (does not connect WebSocket) */
+function makeHubClient(apiKey: string): GopherHole {
+  const apiUrl = process.env.GOPHERHOLE_API_URL || 'https://hub.gopherhole.ai';
+  const hubUrl = apiUrl.replace('https://', 'wss://').replace('http://', 'ws://') + '/ws';
+  return new GopherHole({ apiKey, hubUrl, autoReconnect: false });
+}
+
+/** Send a message and poll until terminal state, return response text.
+ *  Matches the MCP client pattern: sendText → poll getTask. */
+async function askAgent(client: A2AClient, agentId: string, text: string): Promise<string> {
+  const task = await client.sendText(agentId, text);
+
+  const terminalStates = ['completed', 'failed', 'canceled', 'rejected'];
+  let current = task;
+  const start = Date.now();
+  const maxWait = 60_000;
+  const poll = 1_000;
+
+  while (!terminalStates.includes(current.status.state)) {
+    if (current.status.state === 'input-required') {
+      throw new Error('Agent requires additional input (not supported in CLI mode)');
+    }
+    if (current.status.state === 'auth-required') {
+      throw new Error('Agent requires authentication — check your API key or request access');
+    }
+    if (Date.now() - start > maxWait) throw new Error('Timed out waiting for agent response');
+    await new Promise(r => setTimeout(r, poll));
+    current = await client.getTask(current.id);
+  }
+
+  if (current.status.state === 'failed') {
+    const msg = current.status.message?.parts?.[0];
+    throw new Error((msg && 'text' in msg ? msg.text : null) || 'Agent task failed');
+  }
+
+  // Extract text from artifacts first, then history
+  if (current.artifacts?.length) {
+    const texts = current.artifacts.flatMap(a => a.parts.filter(p => 'text' in p && p.text).map(p => (p as { text: string }).text));
+    if (texts.length) return texts.join('\n');
+  }
+  if (current.history?.length) {
+    const last = current.history[current.history.length - 1];
+    const texts = last.parts.filter(p => 'text' in p && p.text).map(p => (p as { text: string }).text);
+    if (texts.length) return texts.join('\n');
+  }
+  return '';
+}
 
 // ASCII art banner
 function showBanner(context?: string) {
@@ -78,7 +174,7 @@ ${chalk.bold('Examples:')}
 ${chalk.bold('Documentation:')}
   https://docs.gopherhole.ai
 `)
-  .version('0.1.0')
+  .version(VERSION)
   .option('-v, --verbose', 'Enable verbose output for debugging')
   .hook('preAction', (thisCommand) => {
     verbose = thisCommand.opts().verbose || false;
@@ -1078,13 +1174,23 @@ ${chalk.bold('Example:')}
     const data = await res.json();
     spinner.succeed('Agent created!');
 
-    // Write .env file
+    // Write .env file (never overwrite existing)
     const fs = await import('fs');
-    fs.writeFileSync('.env', `# GopherHole Configuration
-GOPHERHOLE_API_KEY=${data.apiKey}
-GOPHERHOLE_AGENT_ID=${data.agent.id}
-`);
-    console.log(brand.green('✓ Created .env'));
+    const envLines = `GOPHERHOLE_API_KEY=${data.apiKey}\nGOPHERHOLE_AGENT_ID=${data.agent.id}`;
+
+    if (fs.existsSync('.env')) {
+      const existing = fs.readFileSync('.env', 'utf-8');
+      if (existing.includes('GOPHERHOLE_API_KEY')) {
+        console.log(chalk.gray('↳ .env already has GOPHERHOLE_API_KEY, skipping'));
+        console.log(chalk.gray(`  Your new key: ${data.apiKey}`));
+      } else {
+        fs.appendFileSync('.env', `\n# GopherHole Configuration\n${envLines}\n`);
+        console.log(brand.green('✓ Updated .env (appended GopherHole keys)'));
+      }
+    } else {
+      fs.writeFileSync('.env', `# GopherHole Configuration\n${envLines}\n`);
+      console.log(brand.green('✓ Created .env'));
+    }
 
     // Write example code
     const exampleCode = `import { GopherHole } from '@gopherhole/sdk';
@@ -1114,8 +1220,12 @@ async function main() {
 
 main().catch(console.error);
 `;
-    fs.writeFileSync('agent.ts', exampleCode);
-    console.log(brand.green('✓ Created agent.ts'));
+    if (!fs.existsSync('agent.ts')) {
+      fs.writeFileSync('agent.ts', exampleCode);
+      console.log(brand.green('✓ Created agent.ts'));
+    } else {
+      console.log(chalk.gray('↳ agent.ts already exists, skipping'));
+    }
 
     // Create package.json if it doesn't exist
     if (!fs.existsSync('package.json')) {
@@ -1140,6 +1250,73 @@ main().catch(console.error);
       console.log(brand.green('✓ Created package.json'));
     }
 
+    // Append GopherHole section to AGENTS.md (idempotent)
+    const agentsMdPath = 'AGENTS.md';
+    const gopherSection = `
+## GopherHole
+
+This project is connected to the GopherHole agent hub.
+
+### Auth
+
+The \`gopher\` CLI resolves your API key in this order:
+1. \`--api-key <key>\` flag on any command
+2. \`GOPHERHOLE_API_KEY\` environment variable
+3. \`GOPHERHOLE_API_KEY\` in a \`.env\` file in the current directory
+
+Never hard-code API keys. Use the env var or \`--api-key\` flag.
+
+### Agent identity
+
+- Agent ID: \`${data.agent.id}\`
+- Name: ${agentName}
+
+### Commands
+
+\`\`\`
+# Send a message to an agent
+gopher message <agent-id> "<text>"
+gopher message <agent-id> "<text>" --api-key <key>
+
+# Agent memory (via memory agent)
+gopher memory recall "<query>"
+gopher memory store "<content>" [--tags tag1,tag2]
+gopher memory list [--limit 20]
+gopher memory forget "<query>" --confirm
+
+# Shared workspaces
+gopher workspace list
+gopher workspace create <name>
+gopher workspace query <workspace-id> "<query>"
+gopher workspace store <workspace-id> "<content>" [--type fact|decision|preference|todo|context|reference]
+gopher workspace memories <workspace-id>
+gopher workspace forget <workspace-id> --id <memory-id>
+gopher workspace forget <workspace-id> --query "<query>"
+gopher workspace members list <workspace-id>
+gopher workspace members add <workspace-id> <agent-id> [--role read|write|admin]
+
+# Discover agents (--api-key enables agent-mode auth)
+gopher discover search "<query>" --api-key <key>
+gopher discover search --category <category> --tag <tag>
+gopher discover nearby --lat <lat> --lng <lng> [--radius 10]
+gopher discover info <agent-id>
+gopher discover info <agent-id>
+
+# Auth check
+gopher whoami
+\`\`\`
+`;
+
+    const agentsMdExists = fs.existsSync(agentsMdPath);
+    const existingContent = agentsMdExists ? fs.readFileSync(agentsMdPath, 'utf-8') : '';
+
+    if (existingContent.includes('## GopherHole')) {
+      console.log(chalk.gray('↳ AGENTS.md already has GopherHole section, skipping'));
+    } else {
+      fs.writeFileSync(agentsMdPath, existingContent + gopherSection);
+      console.log(brand.green(agentsMdExists ? '✓ Updated AGENTS.md' : '✓ Created AGENTS.md'));
+    }
+
     console.log(chalk.bold('\n🎉 Project initialized!\n'));
     console.log(chalk.bold('Next steps:'));
     console.log(chalk.cyan('  npm install'));
@@ -1248,6 +1425,7 @@ ${chalk.bold('Examples:')}
   .option('-l, --limit <limit>', 'Number of results (max 50)', '10')
   .option('-o, --offset <offset>', 'Pagination offset')
   .option('--scope <scope>', 'Scope: tenant (same-tenant agents only)')
+  .option('--api-key <key>', 'API key for agent-mode discovery (overrides session)')
   .action(async (query, options) => {
     const spinner = ora('Searching agents...').start();
 
@@ -1267,9 +1445,14 @@ ${chalk.bold('Examples:')}
       if (options.scope) params.set('scope', options.scope);
 
       log('GET /discover/agents?' + params.toString());
+      const apiKey = await resolveApiKey(options.apiKey);
       const sessionId = config.get('sessionId') as string | undefined;
       const headers: Record<string, string> = {};
-      if (sessionId) headers['X-Session-ID'] = sessionId;
+      if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+      } else if (sessionId) {
+        headers['X-Session-ID'] = sessionId;
+      }
       const res = await fetch(`${API_URL}/discover/agents?${params}`, { headers });
       const data = await res.json();
       spinner.stop();
@@ -1391,10 +1574,12 @@ ${chalk.bold('Examples:')}
   .option('-t, --tag <tag>', 'Filter by tag')
   .option('-c, --category <category>', 'Filter by category')
   .option('-l, --limit <limit>', 'Number of results (max 50)', '20')
+  .option('--api-key <key>', 'API key for agent-mode discovery (overrides session)')
   .action(async (options) => {
     const spinner = ora('Searching nearby agents...').start();
 
     try {
+      const apiKey = await resolveApiKey(options.apiKey);
       const sessionId = config.get('sessionId') as string;
       const params = new URLSearchParams();
       params.set('lat', options.lat);
@@ -1406,7 +1591,9 @@ ${chalk.bold('Examples:')}
 
       log('GET /discover/agents/nearby?' + params.toString());
       const headers: Record<string, string> = {};
-      if (sessionId) {
+      if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+      } else if (sessionId) {
         headers['X-Session-ID'] = sessionId;
       }
       const res = await fetch(`${API_URL}/discover/agents/nearby?${params}`, { headers });
@@ -1447,14 +1634,20 @@ discover
 ${chalk.bold('Example:')}
   $ gopherhole discover info agent-abc123
 `)
-  .action(async (agentId) => {
+  .option('--api-key <key>', 'API key for agent-mode discovery (overrides session)')
+  .action(async (agentId, options) => {
     const spinner = ora('Fetching agent info...').start();
 
     try {
       log('GET /discover/agents/' + agentId);
+      const apiKey = await resolveApiKey(options.apiKey);
       const sessionId = config.get('sessionId') as string | undefined;
       const headers: Record<string, string> = {};
-      if (sessionId) headers['X-Session-ID'] = sessionId;
+      if (apiKey) {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+      } else if (sessionId) {
+        headers['X-Session-ID'] = sessionId;
+      }
       const res = await fetch(`${API_URL}/discover/agents/${agentId}`, { headers });
       if (!res.ok) {
         throw new Error('Agent not found');
@@ -2332,5 +2525,394 @@ program
     console.log('');
   });
 
+// ========== MESSAGE COMMAND (agent-to-agent, Bearer auth) ==========
+
+program
+  .command('message <agentId> <text>')
+  .description(`Send a message to an agent using your API key (agent-to-agent)
+
+${chalk.bold('Auth (in order of precedence):')}
+  --api-key <key>     > GOPHERHOLE_API_KEY env > .env file
+  --agent-id <id>     > GOPHERHOLE_AGENT_ID env > .env file
+
+${chalk.bold('Examples:')}
+  $ gopher message agent-memory-official "What do you remember about me?"
+  $ gopher message echo-agent "Hello!" --api-key gph_xxx
+  $ GOPHERHOLE_API_KEY=gph_xxx gopher message search-agent "latest AI news"
+`)
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .action(async (agentId, text, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.'));
+      console.error(chalk.gray('Set GOPHERHOLE_API_KEY, pass --api-key, or run gopher init to create a .env'));
+      process.exit(1);
+    }
+
+    const spinner = ora(`Messaging ${agentId}...`).start();
+    try {
+      const client = makeAgentClient(apiKey);
+      const response = await askAgent(client, agentId, text);
+      spinner.stop();
+      console.log(response || chalk.gray('(no response)'));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message));
+      process.exit(1);
+    }
+  });
+
+// ========== MEMORY COMMANDS (agent-to-agent via memory agent) ==========
+
+const MEMORY_AGENT = process.env.GOPHERHOLE_MEMORY_AGENT || 'agent-memory-official';
+
+const memory = program
+  .command('memory')
+  .description(`Manage agent memory via the GopherHole memory agent
+
+${chalk.bold('Auth (in order of precedence):')}
+  --api-key <key>     > GOPHERHOLE_API_KEY env > .env file
+  --agent-id <id>     > GOPHERHOLE_AGENT_ID env > .env file
+`);
+
+memory
+  .command('recall <query>')
+  .description('Search your agent memories semantically')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--limit <n>', 'Max results', '10')
+  .action(async (query, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Recalling...').start();
+    try {
+      const client = makeAgentClient(apiKey);
+      const msg = `Search memories for: ${query} (limit: ${options.limit})`;
+      const response = await askAgent(client, MEMORY_AGENT, msg);
+      spinner.stop();
+      console.log(response || chalk.gray('No memories found'));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+memory
+  .command('store <content>')
+  .description('Store a new memory')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--tags <tags>', 'Comma-separated tags')
+  .action(async (content, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Storing memory...').start();
+    try {
+      const client = makeAgentClient(apiKey);
+      const tags = options.tags ? `\n\nTags: ${options.tags}` : '';
+      const response = await askAgent(client, MEMORY_AGENT, `Remember this:\n\n${content}${tags}`);
+      spinner.stop();
+      console.log(response || chalk.green('Memory stored'));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+memory
+  .command('forget <query>')
+  .description('Delete memories matching a query')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--confirm', 'Required to confirm deletion')
+  .action(async (query, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    if (!options.confirm) {
+      console.error(chalk.yellow('Add --confirm to delete memories'));
+      process.exit(1);
+    }
+    const spinner = ora('Forgetting...').start();
+    try {
+      const client = makeAgentClient(apiKey);
+      const response = await askAgent(client, MEMORY_AGENT, `Forget memories matching: ${query}`);
+      spinner.stop();
+      console.log(response || chalk.green('Done'));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+memory
+  .command('list')
+  .description('List recent memories')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--limit <n>', 'Max results', '20')
+  .option('--offset <n>', 'Pagination offset', '0')
+  .action(async (options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Listing memories...').start();
+    try {
+      const client = makeAgentClient(apiKey);
+      const msg = `List my recent memories (limit: ${options.limit}, offset: ${options.offset})`;
+      const response = await askAgent(client, MEMORY_AGENT, msg);
+      spinner.stop();
+      console.log(response || chalk.gray('No memories found'));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+// ========== WORKSPACE COMMANDS (direct RPC, Bearer auth) ==========
+
+const ws = program
+  .command('workspace')
+  .alias('ws')
+  .description(`Manage shared workspaces for multi-agent collaboration
+
+${chalk.bold('Auth (in order of precedence):')}
+  --api-key <key>     > GOPHERHOLE_API_KEY env > .env file
+  --agent-id <id>     > GOPHERHOLE_AGENT_ID env > .env file
+`);
+
+ws
+  .command('list')
+  .description('List workspaces you are a member of')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .action(async (options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Loading workspaces...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceList();
+      spinner.stop();
+      if (!result.workspaces.length) {
+        console.log(chalk.gray('No workspaces yet. Create one with: gopher workspace create <name>'));
+        return;
+      }
+      result.workspaces.forEach(w => {
+        console.log(`\n${chalk.bold(w.name)} ${chalk.gray(`(${w.id})`)}`);
+        if (w.description) console.log(chalk.gray(`  ${w.description}`));
+        console.log(chalk.gray(`  Role: ${w.my_role || '?'} | Members: ${w.member_count || '?'} | Memories: ${w.memory_count || '?'}`));
+      });
+      console.log('');
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+ws
+  .command('create <name>')
+  .description('Create a new workspace')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--description <text>', 'Workspace description')
+  .action(async (name, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Creating workspace...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceCreate(name, options.description);
+      spinner.succeed(`Workspace created: ${chalk.bold(result.workspace.name)}`);
+      console.log(chalk.gray(`  ID: ${result.workspace.id}`));
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+ws
+  .command('query <workspaceId> <query>')
+  .description('Search workspace memories semantically')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--type <type>', 'Filter by memory type (fact|decision|preference|todo|context|reference)')
+  .option('--limit <n>', 'Max results', '10')
+  .action(async (workspaceId, query, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Searching...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceQuery({
+        workspace_id: workspaceId,
+        query,
+        type: options.type,
+        limit: options.limit ? parseInt(options.limit) : undefined,
+      });
+      spinner.stop();
+      if (!result.memories.length) {
+        console.log(chalk.gray('No memories found matching your query.'));
+        return;
+      }
+      console.log(chalk.gray(`Found ${result.count} memories:\n`));
+      result.memories.forEach(m => {
+        const sim = m.similarity ? ` ${chalk.gray(`${(m.similarity * 100).toFixed(0)}%`)}` : '';
+        console.log(`${chalk.bold(`[${m.type}]`)}${sim} ${m.content.substring(0, 200)}${m.content.length > 200 ? '…' : ''}`);
+        if (m.tags.length) console.log(chalk.gray(`  Tags: ${m.tags.join(', ')}`));
+        console.log('');
+      });
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+ws
+  .command('store <workspaceId> <content>')
+  .description('Store a memory in a workspace')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--type <type>', 'Memory type (fact|decision|preference|todo|context|reference)', 'fact')
+  .option('--tags <tags>', 'Comma-separated tags')
+  .action(async (workspaceId, content, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Storing...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceStore({
+        workspace_id: workspaceId,
+        content,
+        type: options.type,
+        tags: options.tags ? options.tags.split(',').map((t: string) => t.trim()) : undefined,
+      });
+      spinner.succeed(`Memory stored (${result.memory.id})`);
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+ws
+  .command('memories <workspaceId>')
+  .description('List all memories in a workspace (browse, non-semantic)')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--limit <n>', 'Max results', '20')
+  .option('--offset <n>', 'Pagination offset', '0')
+  .action(async (workspaceId, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Loading memories...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceMemories({
+        workspace_id: workspaceId,
+        limit: parseInt(options.limit),
+        offset: parseInt(options.offset),
+      });
+      spinner.stop();
+      if (!result.memories.length) {
+        console.log(chalk.gray('No memories in this workspace.'));
+        return;
+      }
+      console.log(chalk.gray(`Showing ${result.count} of ${result.total} memories:\n`));
+      result.memories.forEach(m => {
+        console.log(`${chalk.bold(`[${m.type}]`)} ${m.content.substring(0, 150)}${m.content.length > 150 ? '…' : ''}`);
+        if (m.tags.length) console.log(chalk.gray(`  Tags: ${m.tags.join(', ')}`));
+      });
+      console.log('');
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+ws
+  .command('forget <workspaceId>')
+  .description('Delete memories from a workspace by ID or semantic query')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--id <memoryId>', 'Delete a specific memory by ID')
+  .option('--query <query>', 'Delete memories matching this query')
+  .action(async (workspaceId, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    if (!options.id && !options.query) {
+      console.error(chalk.yellow('Provide --id <memoryId> or --query <query>'));
+      process.exit(1);
+    }
+    const spinner = ora('Deleting...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceForget({
+        workspace_id: workspaceId,
+        id: options.id,
+        query: options.query,
+      });
+      spinner.succeed(`Deleted ${result.deleted} memory/memories`);
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+const wsMembers = ws
+  .command('members')
+  .description('Manage workspace members');
+
+wsMembers
+  .command('list <workspaceId>')
+  .description('List workspace members')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .action(async (workspaceId, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Loading members...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      const result = await client.workspaceMembersList(workspaceId);
+      spinner.stop();
+      result.members.forEach(m => {
+        console.log(`  ${m.agent_name || m.agent_id} ${chalk.gray(`(${m.role})`)}`);
+      });
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
+wsMembers
+  .command('add <workspaceId> <agentId>')
+  .description('Add an agent to a workspace')
+  .option('--api-key <key>', 'API key (overrides env / .env)')
+  .option('--agent-id <id>', 'Your agent ID (overrides env / .env)')
+  .option('--role <role>', 'Role: read | write | admin', 'write')
+  .action(async (workspaceId, agentId, options) => {
+    const apiKey = await resolveApiKey(options.apiKey);
+    if (!apiKey) {
+      console.error(chalk.red('No API key found.')); process.exit(1);
+    }
+    const spinner = ora('Adding member...').start();
+    try {
+      const client = makeHubClient(apiKey);
+      await client.workspaceMembersAdd(workspaceId, agentId, options.role);
+      spinner.succeed(`Added ${agentId} with role: ${options.role}`);
+    } catch (err) {
+      spinner.fail(chalk.red((err as Error).message)); process.exit(1);
+    }
+  });
+
 // Parse and run
 program.parse();