@gopherhole/cli 0.1.23 → 0.2.0

package/dist/index.js

@@ -9,6 +9,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const conf_1 = __importDefault(require("conf"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const ora_1 = __importDefault(require("ora"));
+const sdk_1 = require("@gopherhole/sdk");
 const config = new conf_1.default({ projectName: 'gopherhole' });
 const API_URL = 'https://gopherhole.ai/api';
 const WS_URL = 'wss://gopherhole.helixdata.workers.dev/ws';
@@ -19,7 +20,99 @@ const brand = {
     greenDark: chalk_1.default.hex('#16a34a'), // gopher-600 - emphasis
 };
 // 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) {
+    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) {
+    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) {
+    return new sdk_1.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) {
+    const apiUrl = process.env.GOPHERHOLE_API_URL || 'https://hub.gopherhole.ai';
+    const hubUrl = apiUrl.replace('https://', 'wss://').replace('http://', 'ws://') + '/ws';
+    return new sdk_1.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, agentId, text) {
+    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.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.text);
+        if (texts.length)
+            return texts.join('\n');
+    }
+    return '';
+}
 // ASCII art banner
 function showBanner(context) {
     const gopher = [
@@ -71,7 +164,7 @@ ${chalk_1.default.bold('Examples:')}
 ${chalk_1.default.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;
@@ -957,13 +1050,24 @@ ${chalk_1.default.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_1.default.gray('↳ .env already has GOPHERHOLE_API_KEY, skipping'));
+            console.log(chalk_1.default.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';
 import 'dotenv/config';
@@ -992,8 +1096,13 @@ 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_1.default.gray('↳ agent.ts already exists, skipping'));
+    }
     // Create package.json if it doesn't exist
     if (!fs.existsSync('package.json')) {
         const pkg = {
@@ -1016,6 +1125,71 @@ main().catch(console.error);
         fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
         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_1.default.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_1.default.bold('\n🎉 Project initialized!\n'));
     console.log(chalk_1.default.bold('Next steps:'));
     console.log(chalk_1.default.cyan('  npm install'));
@@ -1113,6 +1287,7 @@ ${chalk_1.default.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 = (0, ora_1.default)('Searching agents...').start();
     try {
@@ -1142,10 +1317,15 @@ ${chalk_1.default.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');
         const headers = {};
-        if (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();
@@ -1260,9 +1440,11 @@ ${chalk_1.default.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 = (0, ora_1.default)('Searching nearby agents...').start();
     try {
+        const apiKey = await resolveApiKey(options.apiKey);
         const sessionId = config.get('sessionId');
         const params = new URLSearchParams();
         params.set('lat', options.lat);
@@ -1275,7 +1457,10 @@ ${chalk_1.default.bold('Examples:')}
         params.set('limit', options.limit);
         log('GET /discover/agents/nearby?' + params.toString());
         const headers = {};
-        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 });
@@ -1311,14 +1496,20 @@ discover
 ${chalk_1.default.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 = (0, ora_1.default)('Fetching agent info...').start();
     try {
         log('GET /discover/agents/' + agentId);
+        const apiKey = await resolveApiKey(options.apiKey);
         const sessionId = config.get('sessionId');
         const headers = {};
-        if (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');
@@ -2102,5 +2293,413 @@ program
     console.log(chalk_1.default.gray('  Status:    https://status.gopherhole.ai'));
     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_1.default.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_1.default.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_1.default.red('No API key found.'));
+        console.error(chalk_1.default.gray('Set GOPHERHOLE_API_KEY, pass --api-key, or run gopher init to create a .env'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)(`Messaging ${agentId}...`).start();
+    try {
+        const client = makeAgentClient(apiKey);
+        const response = await askAgent(client, agentId, text);
+        spinner.stop();
+        console.log(response || chalk_1.default.gray('(no response)'));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.gray('No memories found'));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.green('Memory stored'));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    if (!options.confirm) {
+        console.error(chalk_1.default.yellow('Add --confirm to delete memories'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('Forgetting...').start();
+    try {
+        const client = makeAgentClient(apiKey);
+        const response = await askAgent(client, MEMORY_AGENT, `Forget memories matching: ${query}`);
+        spinner.stop();
+        console.log(response || chalk_1.default.green('Done'));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.gray('No memories found'));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('Loading workspaces...').start();
+    try {
+        const client = makeHubClient(apiKey);
+        const result = await client.workspaceList();
+        spinner.stop();
+        if (!result.workspaces.length) {
+            console.log(chalk_1.default.gray('No workspaces yet. Create one with: gopher workspace create <name>'));
+            return;
+        }
+        result.workspaces.forEach(w => {
+            console.log(`\n${chalk_1.default.bold(w.name)} ${chalk_1.default.gray(`(${w.id})`)}`);
+            if (w.description)
+                console.log(chalk_1.default.gray(`  ${w.description}`));
+            console.log(chalk_1.default.gray(`  Role: ${w.my_role || '?'} | Members: ${w.member_count || '?'} | Memories: ${w.memory_count || '?'}`));
+        });
+        console.log('');
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('Creating workspace...').start();
+    try {
+        const client = makeHubClient(apiKey);
+        const result = await client.workspaceCreate(name, options.description);
+        spinner.succeed(`Workspace created: ${chalk_1.default.bold(result.workspace.name)}`);
+        console.log(chalk_1.default.gray(`  ID: ${result.workspace.id}`));
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.gray('No memories found matching your query.'));
+            return;
+        }
+        console.log(chalk_1.default.gray(`Found ${result.count} memories:\n`));
+        result.memories.forEach(m => {
+            const sim = m.similarity ? ` ${chalk_1.default.gray(`${(m.similarity * 100).toFixed(0)}%`)}` : '';
+            console.log(`${chalk_1.default.bold(`[${m.type}]`)}${sim} ${m.content.substring(0, 200)}${m.content.length > 200 ? '…' : ''}`);
+            if (m.tags.length)
+                console.log(chalk_1.default.gray(`  Tags: ${m.tags.join(', ')}`));
+            console.log('');
+        });
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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) => t.trim()) : undefined,
+        });
+        spinner.succeed(`Memory stored (${result.memory.id})`);
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.gray('No memories in this workspace.'));
+            return;
+        }
+        console.log(chalk_1.default.gray(`Showing ${result.count} of ${result.total} memories:\n`));
+        result.memories.forEach(m => {
+            console.log(`${chalk_1.default.bold(`[${m.type}]`)} ${m.content.substring(0, 150)}${m.content.length > 150 ? '…' : ''}`);
+            if (m.tags.length)
+                console.log(chalk_1.default.gray(`  Tags: ${m.tags.join(', ')}`));
+        });
+        console.log('');
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    if (!options.id && !options.query) {
+        console.error(chalk_1.default.yellow('Provide --id <memoryId> or --query <query>'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.gray(`(${m.role})`)}`);
+        });
+    }
+    catch (err) {
+        spinner.fail(chalk_1.default.red(err.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_1.default.red('No API key found.'));
+        process.exit(1);
+    }
+    const spinner = (0, ora_1.default)('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_1.default.red(err.message));
+        process.exit(1);
+    }
+});
 // Parse and run
 program.parse();