@socialseal/cli 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.1.2 - 2026-03-18
+- Add `search-journey-run` async CLI ergonomics: `--async` starts the backend async mode, polling is on by default, and `--no-poll` returns the initial `runId` immediately.
+- Add `--poll-interval <ms>` for async `search-journey-run` status polling.
+- Treat terminal async `search-journey-run` failures as non-zero CLI exits instead of silent `200` JSON output.
+
 ## 0.1.1 - 2026-03-13
 - Document public base URL and CLI error output.
 - Add request timeouts, verbose error output, and OSS-safe tool discovery behavior.

package/README.md

@@ -9,6 +9,7 @@
 Environment variables:
 - `SOCIALSEAL_API_KEY`
 - `SOCIALSEAL_API_BASE` (default `https://api.socialseal.co`)
+- `SOCIALSEAL_WORKSPACE_ID` (optional workspace override; takes precedence over config)
 - `SOCIALSEAL_TIMEOUT_MS` (optional request timeout override)
 - `SOCIALSEAL_AGENT_IDLE_TIMEOUT_MS` (optional agent WebSocket inactivity timeout override; default 300000)
 
@@ -19,14 +20,22 @@ Optional config file:
 {
   "apiKey": "ss_cli_...",
   "apiBase": "https://api.socialseal.co",
+  "workspaceId": "00000000-0000-0000-0000-000000000000",
   "timeoutMs": 30000,
   "agentIdleTimeoutMs": 300000
 }
 ```
 
 ## Commands
+- Workspace discovery/defaults:
+  - `socialseal workspace list`
+  - `socialseal workspace current`
+  - `socialseal workspace use <workspace-id|slug|exact-name>`
+  - `socialseal workspace clear`
+
 - Agent (non-interactive, streaming):
   - `socialseal agent run --message "..." --api-base https://api.socialseal.co --api-key <key> [--workspace-id <uuid>]`
+  - `socialseal agent run --message "..." --continue <token>`
   - `socialseal agent run --message "..." --timeout 60000`
   - `socialseal agent run --message "..." --idle-timeout 300000 --verbose`
 
@@ -37,6 +46,8 @@ Optional config file:
 - Tools (direct edge function call):
   - `socialseal tools call --function <tool> --body @payload.json --api-base https://api.socialseal.co --api-key <key>`
   - `socialseal tools call --function <tool> --body @payload.json --json`
+  - `socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>`
+  - `socialseal tools call --function search-journey-run --body @payload.json --async --no-poll --workspace-id <uuid>`
 
 - Data exports (provisional):
   - `socialseal data export-tracking --group-id 123 --time-period 30d --out out.csv`
@@ -46,12 +57,28 @@ Optional config file:
 - `export-report` and `export_tracking_data` are provisional until CLI export specs are finalized.
 - `tools list` ships a stable built-in registry of supported direct-call function targets. It is not live backend enumeration.
 - `--timeout <ms>` controls HTTP request timeouts. Agent runs default to a 5-minute WebSocket inactivity timeout unless you set `--idle-timeout <ms>` (or the matching env/config value).
+- `search-journey-run` supports CLI-managed async polling: `--async` starts backend async mode, polling is on by default, `--no-poll` returns the initial `runId`, and `--poll-interval <ms>` controls the status polling cadence.
+- `socialseal agent run` now defaults to a fresh conversation. The CLI prints a continuation token to `stderr`; pass it back with `--continue <token>` to resume the same agent conversation explicitly.
+- Effective workspace precedence is: `--workspace-id` → `SOCIALSEAL_WORKSPACE_ID` → config `workspaceId` → backend personal-workspace fallback.
+- `socialseal workspace use ...` writes a local default workspace into `~/.config/socialseal/config.json`, which the CLI reuses for `agent`, `tools`, and `data` commands.
+- `socialseal workspace list` discovers the workspaces accessible to the current CLI key and marks the active/suggested default.
+- If a scoped CLI key cannot safely infer a workspace, `agent run` now fails closed and tells you to set `--workspace-id` or configure a local default first.
 
 ## Errors and exit codes
 - Exit codes: `2` (usage), `3` (auth), `4` (not found), `5` (server), `1` (unknown)
 - Add `--json` to `tools call` or `data` commands to emit machine-readable errors.
 - Add `--verbose` to print error details plus agent session/tool progress diagnostics.
 
+## Troubleshooting
+- `SUPABASE_ANON_KEY not configured`
+  - This comes from the CLI gateway, not the local CLI install.
+  - The deployed gateway is missing its `SUPABASE_ANON_KEY` secret, so `/cli/tools/*` cannot proxy to Supabase Edge Functions.
+  - Fix on the server side with `wrangler secret put SUPABASE_ANON_KEY --env <staging|production>` for the gateway Worker, then re-run a `socialseal tools call ...` smoke test.
+- `AI_UNSUPPORTED_LOCATION` or `The live agent is unavailable in this region right now.`
+  - This is raised when the upstream Gemini API rejects the worker egress location.
+  - The agent worker currently uses Google Gemini directly from Cloudflare Workers; there is no SocialSeal-side region allowlist in the CLI.
+  - If this reproduces from a supported Google AI region, treat it as an infrastructure/runtime issue. Practical workarounds are to run the agent from a worker placement/egress region that Google accepts, or switch the agent runtime to Vertex AI for server-side calls.
+
 ## Smoke Test (manual)
 1. `SOCIALSEAL_API_KEY=... socialseal agent run --message "ping"`
 2. `SOCIALSEAL_API_KEY=... socialseal tools call --function <tool> --body @payload.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -12,6 +12,7 @@ const CLI_KEY_HEADER = 'X-CLI-Key';
 const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
 const EXIT_CODES = {
@@ -58,8 +59,12 @@ const KNOWN_TOOLS = [
   { name: 'vnext-topics-auto-tag', category: 'vnext', description: 'Auto-tag keyword and topic assignments with Gemini-assisted review.' },
 ];
 
+function getConfigPath() {
+  return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
+}
+
 function loadConfig() {
-  const configPath = process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
+  const configPath = getConfigPath();
   try {
     if (!fs.existsSync(configPath)) return {};
     const raw = fs.readFileSync(configPath, 'utf8');
@@ -70,6 +75,15 @@ function loadConfig() {
   }
 }
 
+function saveConfig(config) {
+  const configPath = getConfigPath();
+  const normalizedConfig = Object.fromEntries(
+    Object.entries(config || {}).filter(([, value]) => value !== undefined),
+  );
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(normalizedConfig, null, 2)}\n`);
+}
+
 function resolveApiKey(opts, config) {
   return opts.apiKey || process.env.SOCIALSEAL_API_KEY || config.apiKey;
 }
@@ -86,6 +100,19 @@ function resolveSupabaseUrl(opts, config) {
   return opts.supabaseUrl || process.env.SOCIALSEAL_SUPABASE_URL || config.supabaseUrl;
 }
 
+function resolveWorkspaceSelection(opts, config) {
+  if (typeof opts.workspaceId === 'string' && opts.workspaceId.trim().length > 0) {
+    return { workspaceId: opts.workspaceId.trim(), source: 'flag' };
+  }
+  if (typeof process.env.SOCIALSEAL_WORKSPACE_ID === 'string' && process.env.SOCIALSEAL_WORKSPACE_ID.trim().length > 0) {
+    return { workspaceId: process.env.SOCIALSEAL_WORKSPACE_ID.trim(), source: 'env' };
+  }
+  if (typeof config.workspaceId === 'string' && config.workspaceId.trim().length > 0) {
+    return { workspaceId: config.workspaceId.trim(), source: 'config' };
+  }
+  return { workspaceId: null, source: null };
+}
+
 class CliError extends Error {
   constructor(message, { code = 'CLI_ERROR', exitCode = EXIT_CODES.UNKNOWN, status, hint, details } = {}) {
     super(message);
@@ -252,6 +279,150 @@ function ensureJsonObject(value, label) {
   return value;
 }
 
+function mergeWorkspaceIdIntoPayload(payload, workspaceId) {
+  if (!workspaceId) return payload;
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return payload;
+  }
+  if (typeof payload.workspaceId === 'string' && payload.workspaceId.trim().length > 0) {
+    return payload;
+  }
+  return { ...payload, workspaceId };
+}
+
+function isJsonObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function resolvePollIntervalMs(opts) {
+  const raw = opts.pollInterval ?? process.env.SOCIALSEAL_POLL_INTERVAL_MS;
+  return parseTimeoutMs(raw, { defaultValue: DEFAULT_POLL_INTERVAL_MS, label: 'poll interval' });
+}
+
+function shouldHandleSearchJourneyRunAsync(functionName, method, payload, opts) {
+  if (String(functionName || '').trim() !== 'search-journey-run') return false;
+  if (method !== 'POST') return false;
+  if (!isJsonObject(payload)) return false;
+  if (payload.action === 'status') return false;
+  return opts.async === true || payload.executionMode === 'async';
+}
+
+function applySearchJourneyRunAsyncStart(payload, opts) {
+  if (!shouldHandleSearchJourneyRunAsync(opts.function, normalizeMethod(opts.method), payload, opts)) {
+    return payload;
+  }
+  return {
+    ...payload,
+    executionMode: 'async',
+  };
+}
+
+function formatJsonOutput(value, pretty) {
+  return JSON.stringify(value, null, pretty ? 2 : 0);
+}
+
+function emitJsonOutput(value, pretty) {
+  process.stdout.write(formatJsonOutput(value, pretty) + '\n');
+}
+
+function buildSearchJourneyRunFailure(data) {
+  const message = isJsonObject(data) && typeof data.error === 'string' && data.error.trim().length > 0
+    ? data.error
+    : 'search-journey-run failed';
+  return new CliError(message, {
+    code: 'ASYNC_RUN_FAILED',
+    exitCode: EXIT_CODES.SERVER,
+    details: truncateDetails(data),
+  });
+}
+
+async function pollSearchJourneyRun({
+  apiBase,
+  apiKey,
+  path,
+  workspaceId,
+  timeoutMs,
+  pollIntervalMs,
+  runId,
+  opts,
+}) {
+  if (!workspaceId) {
+    throw new CliError('Async search-journey-run polling requires a workspace id.', {
+      code: 'WORKSPACE_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = null;
+
+  for (;;) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      throw new CliError('Timed out waiting for search-journey-run async completion.', {
+        code: 'ASYNC_WAIT_TIMEOUT',
+        exitCode: EXIT_CODES.SERVER,
+        hint: 'Increase --timeout <ms> or use --no-poll to return the run id immediately.',
+        details: truncateDetails({ runId, workspaceId, lastStatus }),
+      });
+    }
+
+    await sleep(Math.min(pollIntervalMs, remainingMs));
+
+    const res = await callApi({
+      apiBase,
+      apiKey,
+      path,
+      method: 'POST',
+      body: {
+        action: 'status',
+        workspaceId,
+        runId,
+      },
+      workspaceId,
+      timeoutMs: remainingMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tool status poll',
+        functionName: 'search-journey-run',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('search-journey-run status poll returned a non-JSON response.', {
+        code: 'INVALID_STATUS_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    const data = await res.json();
+    const status = isJsonObject(data) && typeof data.status === 'string' ? data.status : null;
+    if (status && status !== lastStatus) {
+      emitInfo(opts, `search-journey-run status: ${status}`);
+      lastStatus = status;
+    }
+
+    if (status === 'completed') return data;
+    if (status === 'failed') throw buildSearchJourneyRunFailure(data);
+    if (status === 'pending' || status === 'processing') continue;
+
+    throw new CliError('search-journey-run status poll returned an unexpected payload.', {
+      code: 'INVALID_STATUS_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+      details: truncateDetails(data),
+    });
+  }
+}
+
 function mapStatusToExitCode(status) {
   if (status === 401 || status === 403) return EXIT_CODES.AUTH;
   if (status === 404) return EXIT_CODES.NOT_FOUND;
@@ -437,6 +608,68 @@ async function callApi({ apiBase, apiKey, path, method = 'POST', body, workspace
   return res;
 }
 
+async function fetchWorkspaceDirectory({ apiBase, apiKey, timeoutMs }) {
+  const res = await callApi({
+    apiBase,
+    apiKey,
+    path: '/cli/workspaces',
+    method: 'GET',
+    timeoutMs,
+  });
+  if (!res.ok) {
+    throw await buildHttpError(res, { label: 'Workspace discovery' });
+  }
+  const payload = await res.json();
+  return payload?.data || {};
+}
+
+function matchWorkspaceIdentifier(workspaces, identifier) {
+  const normalized = String(identifier || '').trim();
+  if (!normalized) {
+    throw new CliError('Missing workspace identifier.', {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use a workspace id, slug, or exact name from `socialseal workspace list`.',
+    });
+  }
+
+  const exactId = workspaces.find((workspace) => workspace.id === normalized);
+  if (exactId) return exactId;
+
+  const exactSlug = workspaces.find((workspace) => workspace.slug === normalized);
+  if (exactSlug) return exactSlug;
+
+  const exactNameMatches = workspaces.filter(
+    (workspace) => typeof workspace.name === 'string' && workspace.name.trim().toLowerCase() === normalized.toLowerCase(),
+  );
+  if (exactNameMatches.length === 1) {
+    return exactNameMatches[0];
+  }
+  if (exactNameMatches.length > 1) {
+    throw new CliError(`Workspace name "${normalized}" is ambiguous.`, {
+      code: 'AMBIGUOUS_WORKSPACE',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use the workspace id or slug from `socialseal workspace list`.',
+    });
+  }
+
+  throw new CliError(`Workspace "${normalized}" was not found.`, {
+    code: 'WORKSPACE_NOT_FOUND',
+    exitCode: EXIT_CODES.NOT_FOUND,
+    hint: 'Run `socialseal workspace list` to discover available workspaces.',
+  });
+}
+
+function formatWorkspaceLine(workspace, { isEffective = false, source = null, isSuggested = false } = {}) {
+  const tags = [];
+  if (workspace.isPersonalWorkspace) tags.push('personal');
+  if (isEffective) tags.push(source === 'config' ? 'default' : `active:${source}`);
+  if (isSuggested) tags.push('suggested');
+  const tagText = tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+  const slugText = workspace.slug ? ` slug=${workspace.slug}` : '';
+  return `- ${workspace.name} (${workspace.id}) role=${workspace.role}${slugText}${tagText}`;
+}
+
 async function handleAgentRun(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -445,12 +678,33 @@ async function handleAgentRun(opts) {
   const { resolvedApiBase, legacyUrl } = resolveApiTarget({ apiBase, legacyUrl: agentUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
   const idleTimeoutMs = resolveAgentIdleTimeoutMs(opts, config, timeoutMs);
+  const continuationToken = typeof opts.continue === 'string' ? opts.continue.trim() : '';
+  const { workspaceId: resolvedWorkspaceIdInput } = resolveWorkspaceSelection(opts, config);
+
+  if (continuationToken && opts.conversationId) {
+    throw new CliError('Use either --continue or --conversation-id, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (continuationToken && opts.createNew) {
+    throw new CliError('Use either --continue or --create-new, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (opts.conversationId && opts.createNew) {
+    throw new CliError('Use either --conversation-id or --create-new, not both.', {
+      code: 'INVALID_ARGUMENTS',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
 
   const headers = {
     'Content-Type': 'application/json',
     [CLI_KEY_HEADER]: apiKey,
   };
-  if (opts.workspaceId) headers[WORKSPACE_HEADER] = opts.workspaceId;
+  if (resolvedWorkspaceIdInput) headers[WORKSPACE_HEADER] = resolvedWorkspaceIdInput;
 
   const sessionUrl = resolvedApiBase
     ? `${resolvedApiBase.replace(/\/$/, '')}/cli/agent/session`
@@ -460,8 +714,9 @@ async function handleAgentRun(opts) {
     method: 'POST',
     headers,
     body: JSON.stringify({
-      conversationId: opts.conversationId || undefined,
-      createNew: !!opts.createNew,
+      continuationToken: continuationToken || undefined,
+      conversationId: continuationToken ? undefined : (opts.conversationId || undefined),
+      createNew: continuationToken || opts.conversationId ? undefined : true,
     }),
   }, timeoutMs);
 
@@ -472,6 +727,8 @@ async function handleAgentRun(opts) {
   const sessionData = await sessionRes.json();
   const sessionId = sessionData?.data?.sessionId || null;
   const initialConversationId = sessionData?.data?.activeConversationId || opts.conversationId || null;
+  const resolvedWorkspaceId = sessionData?.data?.workspaceId || resolvedWorkspaceIdInput || null;
+  const nextContinuationToken = sessionData?.data?.continuationToken || null;
   const wsUrl = sessionData?.data?.websocketUrl;
   if (!wsUrl) {
     throw new CliError('Missing websocketUrl in session response.', {
@@ -483,6 +740,19 @@ async function handleAgentRun(opts) {
     opts,
     `Agent session created${sessionId ? ` (session ${sessionId})` : ''}${initialConversationId ? ` for conversation ${initialConversationId}` : ''}.`,
   );
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      type: 'session_bootstrap',
+      payload: {
+        sessionId,
+        conversationId: initialConversationId,
+        workspaceId: resolvedWorkspaceId,
+        continuationToken: nextContinuationToken,
+      },
+    }) + '\n');
+  } else if (nextContinuationToken) {
+    process.stderr.write(`[socialseal] Continuation token: ${nextContinuationToken}\n`);
+  }
 
   const context = parseJsonInput(opts.context, { label: 'context', allowString: true });
   const message = opts.message;
@@ -721,16 +991,19 @@ async function handleToolsCall(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId } = resolveWorkspaceSelection(opts, config);
 
-  const payload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
+  const parsedPayload = parseJsonInput(opts.body, { label: 'body' }) ?? {};
+  const mergedPayload = mergeWorkspaceIdIntoPayload(parsedPayload, resolvedWorkspaceId);
   const method = normalizeMethod(opts.method);
+  const payload = applySearchJourneyRunAsyncStart(mergedPayload, { ...opts, method });
   const res = await callApi({
     apiBase: useGateway ? resolvedApiBase : legacyUrl,
     apiKey,
     path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
     method,
     body: payload,
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -745,7 +1018,45 @@ async function handleToolsCall(opts) {
   const contentType = res.headers.get('content-type') || '';
   if (contentType.includes('application/json')) {
     const data = await res.json();
-    process.stdout.write(JSON.stringify(data, null, opts.pretty ? 2 : 0) + '\n');
+    const shouldPoll = shouldHandleSearchJourneyRunAsync(opts.function, method, payload, opts) && opts.poll !== false;
+    if (!shouldPoll) {
+      emitJsonOutput(data, opts.pretty);
+      return;
+    }
+
+    const startStatus = isJsonObject(data) && typeof data.status === 'string' ? data.status : null;
+    if (startStatus === 'failed') {
+      throw buildSearchJourneyRunFailure(data);
+    }
+    if (startStatus === 'completed') {
+      emitJsonOutput(data, opts.pretty);
+      return;
+    }
+
+    const runId = isJsonObject(data) && typeof data.runId === 'string' ? data.runId : null;
+    if (!runId) {
+      throw new CliError('Async search-journey-run start response did not include a runId.', {
+        code: 'INVALID_START_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+        details: truncateDetails(data),
+      });
+    }
+
+    emitInfo(opts, `search-journey-run async run started: ${runId}`);
+    const finalData = await pollSearchJourneyRun({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path: useGateway ? `/cli/tools/${opts.function}` : `/functions/v1/${opts.function}`,
+      workspaceId: isJsonObject(payload) && typeof payload.workspaceId === 'string'
+        ? payload.workspaceId
+        : resolvedWorkspaceId,
+      timeoutMs,
+      pollIntervalMs: resolvePollIntervalMs(opts),
+      runId,
+      opts,
+    });
+
+    emitJsonOutput(finalData, opts.pretty);
     return;
   }
 
@@ -787,6 +1098,7 @@ async function handleDataExportTracking(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId } = resolveWorkspaceSelection(opts, config);
 
   if (!opts.groupId && !opts.itemId) {
     throw new CliError('Provide --group-id or --item-id.', {
@@ -807,7 +1119,7 @@ async function handleDataExportTracking(opts) {
     path: useGateway ? '/cli/tools/export_tracking_data' : '/functions/v1/export_tracking_data',
     method: 'POST',
     body: payload,
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -838,6 +1150,7 @@ async function handleDataExportReport(opts) {
   const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
   const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
   const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId } = resolveWorkspaceSelection(opts, config);
 
   const payload = ensureJsonObject(parseJsonInput(opts.payload, { label: 'payload' }), 'payload');
 
@@ -851,7 +1164,7 @@ async function handleDataExportReport(opts) {
       format: opts.format,
       payload,
     },
-    workspaceId: opts.workspaceId,
+    workspaceId: resolvedWorkspaceId,
     timeoutMs,
   });
 
@@ -893,6 +1206,150 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
+async function handleWorkspaceList(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const selection = resolveWorkspaceSelection({}, config);
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const payload = {
+    ...directory,
+    effectiveWorkspaceId: selection.workspaceId,
+    effectiveWorkspaceSource: selection.source,
+  };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write('[socialseal] Available workspaces\n');
+  if (workspaces.length === 0) {
+    process.stdout.write('[socialseal] No accessible workspaces were returned for this key.\n');
+    return;
+  }
+
+  for (const workspace of workspaces) {
+    const isEffective = selection.workspaceId === workspace.id;
+    const isSuggested = !selection.workspaceId && directory.defaultWorkspaceId === workspace.id;
+    process.stdout.write(`${formatWorkspaceLine(workspace, { isEffective, source: selection.source, isSuggested })}\n`);
+  }
+
+  if (!selection.workspaceId && directory.defaultWorkspaceId) {
+    process.stdout.write('\n[socialseal] No local default is configured. Set one with: socialseal workspace use <id>\n');
+  }
+}
+
+async function handleWorkspaceCurrent(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const selection = resolveWorkspaceSelection({}, config);
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const effectiveWorkspace = selection.workspaceId
+    ? workspaces.find((workspace) => workspace.id === selection.workspaceId) || null
+    : null;
+
+  if (selection.workspaceId && !effectiveWorkspace) {
+    throw new CliError(`Configured workspace "${selection.workspaceId}" is not accessible with this CLI key.`, {
+      code: 'WORKSPACE_NOT_ACCESSIBLE',
+      exitCode: EXIT_CODES.NOT_FOUND,
+      hint: 'Run `socialseal workspace list` to pick a valid workspace or `socialseal workspace clear` to unset the default.',
+    });
+  }
+
+  const payload = {
+    effectiveWorkspaceId: selection.workspaceId,
+    effectiveWorkspaceSource: selection.source,
+    workspace: effectiveWorkspace,
+    defaultWorkspaceId: directory.defaultWorkspaceId || null,
+    personalWorkspaceId: directory.personalWorkspaceId || null,
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  if (effectiveWorkspace) {
+    process.stdout.write(`[socialseal] Effective workspace: ${effectiveWorkspace.name} (${effectiveWorkspace.id}) via ${selection.source}\n`);
+    return;
+  }
+
+  if (directory.defaultWorkspaceId) {
+    const suggestedWorkspace = workspaces.find((workspace) => workspace.id === directory.defaultWorkspaceId) || null;
+    if (suggestedWorkspace) {
+      process.stdout.write(`[socialseal] No local default workspace is configured. Suggested workspace: ${suggestedWorkspace.name} (${suggestedWorkspace.id})\n`);
+      return;
+    }
+  }
+
+  process.stdout.write('[socialseal] No default workspace is configured and no accessible workspace suggestion is available.\n');
+}
+
+async function handleWorkspaceUse(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const { resolvedApiBase } = resolveApiTarget({ apiBase, legacyUrl: null });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const directory = await fetchWorkspaceDirectory({
+    apiBase: resolvedApiBase,
+    apiKey,
+    timeoutMs,
+  });
+  const workspaces = Array.isArray(directory.workspaces) ? directory.workspaces : [];
+  const workspace = matchWorkspaceIdentifier(workspaces, opts.identifier);
+  saveConfig({
+    ...config,
+    workspaceId: workspace.id,
+  });
+
+  const payload = {
+    success: true,
+    workspaceId: workspace.id,
+    workspace,
+    configPath: getConfigPath(),
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write(`[socialseal] Default workspace set to ${workspace.name} (${workspace.id})\n`);
+}
+
+function handleWorkspaceClear(opts) {
+  const config = loadConfig();
+  const nextConfig = { ...config };
+  delete nextConfig.workspaceId;
+  saveConfig(nextConfig);
+
+  const payload = {
+    success: true,
+    configPath: getConfigPath(),
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write('[socialseal] Default workspace cleared.\n');
+}
+
 const program = new Command();
 program
   .name('socialseal')
@@ -905,7 +1362,7 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-program.addHelpText('after', `\nExamples:\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
 
 program
   .command('agent')
@@ -916,6 +1373,7 @@ program
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
   .option('--api-key <key>', 'CLI API key')
   .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--continue <token>', 'Continuation token from a previous agent run')
   .option('--conversation-id <id>', 'Conversation id to resume')
   .option('--create-new', 'Create a new conversation')
   .option('--json', 'Emit NDJSON events')
@@ -924,6 +1382,49 @@ program
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleAgentRun, opts));
 
+const workspace = program.command('workspace').description('Discover and manage the default workspace');
+
+workspace
+  .command('list')
+  .description('List accessible workspaces for this CLI key')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceList, opts));
+
+workspace
+  .command('current')
+  .description('Show the effective default workspace')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceCurrent, opts));
+
+workspace
+  .command('use <identifier>')
+  .description('Persist a default workspace by id, slug, or exact name')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((identifier, opts) => runCommand(handleWorkspaceUse, { ...opts, identifier }));
+
+workspace
+  .command('clear')
+  .description('Clear the locally configured default workspace')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleWorkspaceClear, opts));
+
 const tools = program.command('tools').description('Call edge functions directly (tool backends)');
 
 tools
@@ -939,6 +1440,9 @@ tools
   .requiredOption('--function <name>', 'Tool name (see official docs)')
   .option('--method <method>', 'HTTP method', 'POST')
   .option('--body <jsonOrFile>', 'JSON body or @file.json')
+  .option('--async', 'Request async execution for supported tool backends')
+  .option('--no-poll', 'Return immediately after async start instead of polling to completion')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds for supported async tool calls')
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
   .option('--api-key <key>', 'CLI API key')
   .option('--workspace-id <id>', 'Workspace id (for scoped keys)')