@socialseal/cli 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.1.12 - 2026-06-23
+
+- Expose Asset Studio and video production tool surfaces through CLI discovery/schema output.
+- Add category-filtered tool discovery for users and agents.
+
 ## 0.1.11 - 2026-06-12
 
 - Add ad hoc public video URL analysis parity for queue and extract workflows, including `--url` and `--allow-untracked` support.

package/package.json

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

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -8,6 +9,7 @@ import WebSocket from 'ws';
 
 const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.config', 'socialseal', 'config.json');
 const DEFAULT_API_BASE = 'https://api.socialseal.co';
+const DEFAULT_WEB_BASE = 'https://app.socialseal.co';
 const CLI_KEY_HEADER = 'X-CLI-Key';
 const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 300000;
@@ -146,6 +148,94 @@ const KNOWN_TOOLS = [
     knownLocalDevState: 'enabled',
     notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items and public URL items with allowUntracked=true; videoId means video_uid or platform-native video id, not a tracking item id.',
   },
+  {
+    name: 'vnext-clips-read',
+    category: 'asset-studio',
+    description: 'List workspace clip-library items and optionally sign selected source videos.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clips-create',
+    category: 'asset-studio',
+    description: 'Create signed clip upload targets and finalize uploaded clip metadata.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'finalize'],
+    notes: 'The create action returns signed upload URLs; upload bytes to storage before calling finalize.',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-read',
+    category: 'asset-studio',
+    description: 'Read clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-write',
+    category: 'asset-studio',
+    description: 'Upsert or delete clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['upsert', 'delete'],
+  },
+  {
+    name: 'vnext-generated-assets-read',
+    category: 'asset-studio',
+    description: 'List generated rough cuts for a blueprint or read one generated asset.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'detail'],
+  },
+  {
+    name: 'vnext-generated-asset-create',
+    category: 'asset-studio',
+    description: 'Create a generated rough-cut asset from an edit spec.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-optimize',
+    category: 'asset-studio',
+    description: 'Optimize a generated asset or create a new revision.',
+    objectType: 'generated_asset_revision',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['optimize', 'create-revision'],
+  },
+  {
+    name: 'vnext-generated-asset-export',
+    category: 'asset-studio',
+    description: 'Export a generated rough cut as FCPXML.',
+    objectType: 'generated_asset_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-share',
+    category: 'asset-studio',
+    description: 'Create, read, or revoke generated-asset share links.',
+    objectType: 'generated_asset_share',
+    transport: 'post_edge_function',
+    workspaceScoped: false,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'read', 'revoke'],
+    notes: 'create/revoke require workspaceId in the body; read uses shareToken and does not require workspace scope.',
+  },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   {
     name: 'google-ai-search',
@@ -218,7 +308,34 @@ const KNOWN_TOOLS = [
   { name: 'vnext-blueprints-create', category: 'vnext', description: 'Create a vNext blueprint from grounded evidence.' },
   { name: 'vnext-blueprints-generate', category: 'vnext', description: 'Generate a vNext blueprint from workspace opportunity data.' },
   { name: 'vnext-blueprints-read', category: 'vnext', description: 'Read vNext blueprint history and specific versions.' },
+  {
+    name: 'vnext-blueprints-shots-read',
+    category: 'video-production',
+    description: 'Read shot-lift and pinned shot assets for a blueprint.',
+    objectType: 'blueprint_shot_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-blueprints-shots-refresh',
+    category: 'video-production',
+    description: 'Queue a refresh for blueprint shot assets.',
+    objectType: 'blueprint_shots_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-create', category: 'vnext', description: 'Create a vNext brief record.' },
+  {
+    name: 'vnext-briefs-export',
+    category: 'video-production',
+    description: 'Export a generated vNext brief as markdown.',
+    objectType: 'vnext_brief_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-generate', category: 'vnext', description: 'Generate a vNext brief from a blueprint or opportunity.' },
   { name: 'vnext-briefs-read', category: 'vnext', description: 'Read generated vNext briefs and version history.' },
   { name: 'vnext-intents', category: 'vnext', description: 'List, create, update, or delete vNext intents.' },
@@ -451,6 +568,311 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body \'{"allowUntracked":true,"items":[{"url":"https://www.instagram.com/reel/SHORTCODE/"}]}\'',
     ],
   },
+  'vnext-clips-read': {
+    summary: 'List Asset Studio clip-library items and optionally sign selected video URLs.',
+    operations: [
+      {
+        action: 'list',
+        required: ['workspaceId or --workspace-id'],
+        optional: ['videoClipIds[] to include signed source video URLs'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          videoClipIds: ['11111111-1111-4111-8111-111111111111'],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-read --workspace-id <workspace-uuid> --body \'{"videoClipIds":["<clip-uuid>"]}\'',
+    ],
+  },
+  'vnext-clips-create': {
+    summary: 'Create signed upload targets for clips and finalize uploaded clip metadata.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId or --workspace-id', 'fileName', 'mimeType'],
+        optional: [],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          fileName: 'hero-shot.mp4',
+          mimeType: 'video/mp4',
+        },
+      },
+      {
+        action: 'finalize',
+        required: ['action=finalize', 'workspaceId or --workspace-id', 'clipId', 'fileName', 'storagePath', 'mimeType', 'sizeBytes', 'rightsAttested=true'],
+        optional: ['durationSeconds', 'width', 'height', 'posterPath'],
+        example: {
+          action: 'finalize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          fileName: 'hero-shot.mp4',
+          storagePath: 'workspace-00000000-0000-4000-8000-000000000000/11111111-1111-4111-8111-111111111111.mp4',
+          mimeType: 'video/mp4',
+          sizeBytes: 1048576,
+          rightsAttested: true,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body \'{"action":"create","fileName":"hero-shot.mp4","mimeType":"video/mp4"}\'',
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body @clip-finalize.json',
+    ],
+  },
+  'vnext-clip-shot-mappings-read': {
+    summary: 'Read Asset Studio clip-to-shot mappings for a blueprint.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-clip-shot-mappings-write': {
+    summary: 'Upsert or delete Asset Studio clip-to-shot mappings.',
+    operations: [
+      {
+        action: 'upsert',
+        required: ['action=upsert', 'workspaceId or --workspace-id', 'blueprintId', 'panelId', 'clipId'],
+        optional: ['source (suggested|override)', 'score'],
+        example: {
+          action: 'upsert',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          source: 'override',
+        },
+      },
+      {
+        action: 'delete',
+        required: ['action=delete', 'workspaceId or --workspace-id', 'blueprintId', 'panelId'],
+        optional: [],
+        example: {
+          action: 'delete',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-write --workspace-id <workspace-uuid> --body \'{"action":"upsert","blueprintId":"<blueprint-uuid>","panelId":"panel-1","clipId":"<clip-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-assets-read': {
+    summary: 'List generated rough cuts for a blueprint or read one generated asset.',
+    operations: [
+      {
+        action: 'list',
+        required: ['action=list', 'workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          action: 'list',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+      {
+        action: 'detail',
+        required: ['action=detail', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'detail',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"list","blueprintId":"<blueprint-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"detail","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-create': {
+    summary: 'Create a generated rough cut from an Asset Studio edit spec.',
+    operations: [
+      {
+        action: 'create',
+        required: ['workspaceId or --workspace-id', 'blueprintId', 'title', 'editSpec'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          title: 'Homepage rough cut',
+          editSpec: {
+            version: 1,
+            fps: 30,
+            width: 1080,
+            height: 1920,
+            totalDurationSeconds: 3,
+            shots: [
+              {
+                panelId: 'panel-1',
+                clipId: '11111111-1111-4111-8111-111111111111',
+                title: 'Opening hook',
+                kind: 'hook',
+                shotLabel: 'Hero exterior',
+                sourceStartSeconds: 0,
+                durationSeconds: 3,
+                evidenceIds: [],
+              },
+            ],
+          },
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-create --workspace-id <workspace-uuid> --body @edit-spec.json',
+    ],
+  },
+  'vnext-generated-asset-optimize': {
+    summary: 'Optimize a generated asset or create a new revision.',
+    operations: [
+      {
+        action: 'optimize',
+        required: ['action=optimize', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'optimize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+      {
+        action: 'create-revision',
+        required: ['action=create-revision', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'create-revision',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-optimize --workspace-id <workspace-uuid> --body \'{"action":"optimize","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-export': {
+    summary: 'Export a generated rough cut as FCPXML.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'assetId'],
+        optional: ['format=fcpxml'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          format: 'fcpxml',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-export --workspace-id <workspace-uuid> --body \'{"assetId":"<asset-uuid>","format":"fcpxml"}\'',
+    ],
+  },
+  'vnext-generated-asset-share': {
+    summary: 'Create, read, or revoke generated rough-cut share links.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId', 'assetId'],
+        optional: ['ttlSeconds', 'shareBaseUrl'],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          ttlSeconds: 604800,
+        },
+      },
+      {
+        action: 'read',
+        required: ['action=read', 'shareToken'],
+        optional: [],
+        example: {
+          action: 'read',
+          shareToken: '0123456789abcdef0123456789abcdef',
+        },
+      },
+      {
+        action: 'revoke',
+        required: ['action=revoke', 'workspaceId', 'shareLinkId'],
+        optional: [],
+        example: {
+          action: 'revoke',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          shareLinkId: '44444444-4444-4444-8444-444444444444',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"create","workspaceId":"<workspace-uuid>","assetId":"<asset-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"read","shareToken":"<share-token>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-read': {
+    summary: 'Read blueprint shot-lift rows and pinned shot assets with signed URLs.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: ['signedUrlSeconds'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          signedUrlSeconds: 3600,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-refresh': {
+    summary: 'Queue a refresh for blueprint shot assets.',
+    operations: [
+      {
+        action: 'refresh',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-refresh --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-briefs-export': {
+    summary: 'Export the latest or selected generated vNext brief as markdown.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'opportunityKey'],
+        optional: ['version'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          opportunityKey: 'opportunity-key',
+          version: 1,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-briefs-export --workspace-id <workspace-uuid> --body \'{"opportunityKey":"<opportunity-key>"}\'',
+    ],
+  },
   'group-management': {
     summary: 'Manage single-platform tracking groups and memberships.',
     operations: [
@@ -544,6 +966,18 @@ function buildToolRegistry() {
   });
 }
 
+function filterToolRegistry(tools, category) {
+  const normalizedCategory = trimString(category).toLowerCase();
+  const filtered = normalizedCategory
+    ? tools.filter((tool) => trimString(tool.category).toLowerCase() === normalizedCategory)
+    : tools;
+  return [...filtered].sort((a, b) => {
+    const categoryCompare = trimString(a.category).localeCompare(trimString(b.category));
+    if (categoryCompare !== 0) return categoryCompare;
+    return trimString(a.name).localeCompare(trimString(b.name));
+  });
+}
+
 function getConfigPath() {
   return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
 }
@@ -586,9 +1020,36 @@ function saveConfig(config) {
     Object.entries(config || {}).filter(([, value]) => value !== undefined),
   );
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  fs.writeFileSync(configPath, `${JSON.stringify(normalizedConfig, null, 2)}\n`);
+  fs.writeFileSync(configPath, `${JSON.stringify(normalizedConfig, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  fs.chmodSync(configPath, 0o600);
 }
 
+function assertConfigWritable() {
+  const configPath = getConfigPath();
+  const configDir = path.dirname(configPath);
+  fs.mkdirSync(configDir, { recursive: true });
+  const probePath = path.join(configDir, `.socialseal-write-test-${process.pid}-${Date.now()}`);
+  try {
+    fs.writeFileSync(probePath, '', { mode: 0o600 });
+    fs.unlinkSync(probePath);
+  } catch (error) {
+    try {
+      if (fs.existsSync(probePath)) fs.unlinkSync(probePath);
+    } catch {
+      // best effort cleanup only
+    }
+    throw new CliError(`Cannot write SocialSeal config at ${configPath}.`, {
+      code: 'CONFIG_NOT_WRITABLE',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Set SOCIALSEAL_CONFIG to a writable path, or set SOCIALSEAL_API_KEY manually.',
+      details: error?.message || String(error),
+    });
+  }
+}
+
+
 function resolveApiKey(opts, config) {
   return opts.apiKey || process.env.SOCIALSEAL_API_KEY || config.apiKey;
 }
@@ -605,6 +1066,10 @@ function resolveSupabaseUrl(opts, config) {
   return opts.supabaseUrl || process.env.SOCIALSEAL_SUPABASE_URL || config.supabaseUrl;
 }
 
+function resolveWebBase(opts = {}, config = {}) {
+  return opts.webBase || process.env.SOCIALSEAL_WEB_BASE || config.webBase || DEFAULT_WEB_BASE;
+}
+
 function resolveWorkspaceSelection(opts, config) {
   if (typeof opts.workspaceId === 'string' && opts.workspaceId.trim().length > 0) {
     return { workspaceId: opts.workspaceId.trim(), source: 'flag' };
@@ -1164,6 +1629,23 @@ function resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) {
   return fallbackWorkspaceId || null;
 }
 
+function isGeneratedAssetShareScopedAction(functionName, payload) {
+  if (functionName !== 'vnext-generated-asset-share' || !isJsonObject(payload)) {
+    return false;
+  }
+  const action = trimString(payload.action).toLowerCase();
+  return action === 'create' || action === 'revoke';
+}
+
+function shouldRequireToolWorkspace(functionName, payload) {
+  const tool = getKnownTool(functionName);
+  const category = trimString(tool?.category).toLowerCase();
+  return (
+    Boolean(tool?.workspaceScoped) &&
+      (category === 'asset-studio' || category === 'video-production')
+  ) || isGeneratedAssetShareScopedAction(functionName, payload);
+}
+
 function isUuidLike(value) {
   return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
 }
@@ -2700,7 +3182,9 @@ function buildStatusHint(status, context = {}) {
   switch (status) {
     case 401:
     case 403:
-      return 'Check your CLI key and workspace access.';
+      return 'Authentication failed. Run `socialseal login`, or check your CLI key and workspace access.';
+    case 402:
+      return 'Your free credits or quota may be exhausted. Run `socialseal billing` to open billing and credits options.';
     case 404:
       if (context.functionName) {
         if (isLocallyDisabledByDefaultFunction(context.functionName)) {
@@ -2714,6 +3198,9 @@ function buildStatusHint(status, context = {}) {
     case 422:
       return 'Validation error. Review the JSON payload schema. For tracking/group tools, prefer the CLI action aliases or the documented REST semantics.';
     default:
+      if (context.billingRelated) {
+        return 'Run `socialseal billing` to open billing and credits options.';
+      }
       return null;
   }
 }
@@ -2740,7 +3227,9 @@ async function buildHttpError(res, context = {}) {
 
   const label = context.label || 'Request';
   const statusText = res.statusText ? ` ${res.statusText}` : '';
-  const hint = context.hint || buildStatusHint(status, context);
+  const serializedDetails = typeof details === 'string' ? details : JSON.stringify(details);
+  const billingRelated = /\b(credit|credits|quota|billing|entitlement|payment|plan)\b/i.test(serializedDetails || '');
+  const hint = context.hint || buildStatusHint(status, { ...context, billingRelated });
 
   return new CliError(`${label} failed: ${status}${statusText}`.trim(), {
     code: 'HTTP_ERROR',
@@ -3224,9 +3713,10 @@ function coerceCliError(err, fallbackMessage = 'Command failed') {
 function requireApiKey(opts, config) {
   const apiKey = resolveApiKey(opts, config);
   if (!apiKey) {
-    throw new CliError('Missing API key. Set SOCIALSEAL_API_KEY or --api-key.', {
+    throw new CliError('Missing API key. Run `socialseal login` to connect this CLI.', {
       code: 'MISSING_API_KEY',
-      exitCode: EXIT_CODES.USAGE,
+      exitCode: EXIT_CODES.AUTH,
+      hint: 'Run `socialseal login`, or set SOCIALSEAL_API_KEY if you already have a key.',
     });
   }
   return apiKey;
@@ -3756,6 +4246,26 @@ async function handleToolsCall(opts) {
     });
   }
 
+  const scopedPayload = isJsonObject(translated.normalizedPayload)
+    ? translated.normalizedPayload
+    : (isJsonObject(translated.body) ? translated.body : payload);
+  const hasSpecialWorkspaceHandling = new Set([
+    'group-management',
+    'export_tracking_data',
+    'tracked-video-extract',
+  ]).has(opts.function);
+  if (!hasSpecialWorkspaceHandling && shouldRequireToolWorkspace(opts.function, scopedPayload)) {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: opts.function,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, include workspaceId in the body, or configure a default workspace.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: opts.function,
+    });
+  }
+
   emitTrackingCreateScopeWarning(
     isJsonObject(translated.normalizedPayload) ? trimString(translated.normalizedPayload.action).toLowerCase() : '',
     effectiveWorkspaceId,
@@ -3854,9 +4364,10 @@ async function handleToolsCall(opts) {
 }
 
 function handleToolsList(opts) {
-  const tools = buildToolRegistry();
+  const tools = filterToolRegistry(buildToolRegistry(), opts.category);
   const payload = {
     discovery: 'built_in_registry',
+    category: trimString(opts.category) || null,
     tools,
     note: STATIC_TOOL_REGISTRY_NOTE,
     schemaNote: STATIC_TOOL_SCHEMA_NOTE,
@@ -3868,6 +4379,9 @@ function handleToolsList(opts) {
   }
 
   process.stdout.write('[socialseal] Built-in tool registry\n');
+  if (payload.category) {
+    process.stdout.write(`[socialseal] Category filter: ${payload.category}\n`);
+  }
   process.stdout.write(`[socialseal] ${payload.note}\n`);
   process.stdout.write(`[socialseal] ${payload.schemaNote}\n`);
 
@@ -4756,6 +5270,258 @@ async function handleVideoQueueAnalysis(opts) {
   emitJsonOutput(payload, opts.pretty);
 }
 
+function maskApiKey(apiKey) {
+  const key = typeof apiKey === 'string' ? apiKey.trim() : '';
+  if (!key) return null;
+  return `…${key.slice(-6)}`;
+}
+
+function openBrowser(url, onError) {
+  const platform = process.platform;
+  const command = platform === 'darwin'
+    ? 'open'
+    : platform === 'win32'
+      ? 'cmd'
+      : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.on('error', (error) => {
+    if (typeof onError === 'function') onError(error);
+  });
+  child.unref();
+}
+
+async function callPublicApi({ apiBase, path: requestPath, method = 'POST', body, timeoutMs }) {
+  if (!apiBase) {
+    throw new CliError('Missing API base. Set SOCIALSEAL_API_BASE or --api-base.', {
+      code: 'MISSING_API_BASE',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  const normalizedMethod = normalizeMethod(method);
+  const url = `${apiBase.replace(/\/$/, '')}${requestPath.startsWith('/') ? requestPath : `/${requestPath}`}`;
+  const hasBody = body !== undefined && normalizedMethod !== 'GET' && normalizedMethod !== 'HEAD';
+  return fetchWithTimeout(url, {
+    method: normalizedMethod,
+    headers: {
+      Accept: 'application/json',
+      ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: hasBody ? JSON.stringify(body ?? {}) : undefined,
+  }, timeoutMs ?? DEFAULT_TIMEOUT_MS);
+}
+
+async function readJsonResponse(res, label) {
+  const contentType = res.headers.get('content-type') || '';
+  if (!contentType.includes('application/json')) {
+    throw new CliError(`${label} returned a non-JSON response.`, {
+      code: 'INVALID_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+  return res.json();
+}
+
+async function handleLogin(opts) {
+  const config = loadConfig();
+  const apiBase = resolveApiBase(opts, config) || DEFAULT_API_BASE;
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  assertConfigWritable();
+  const authorizeRes = await callPublicApi({
+    apiBase,
+    path: '/cli/device/authorize',
+    body: {
+      clientId: '@socialseal/cli',
+      clientName: 'SocialSeal CLI',
+      scopes: { cli: true },
+    },
+    timeoutMs,
+  });
+
+  if (!authorizeRes.ok) {
+    throw await buildHttpError(authorizeRes, { label: 'Device authorization start' });
+  }
+
+  const authorizePayload = await readJsonResponse(authorizeRes, 'Device authorization start');
+  const verificationUrl = authorizePayload.verification_uri_complete || authorizePayload.verification_uri;
+  const deviceCode = authorizePayload.device_code;
+  const userCode = authorizePayload.user_code;
+  if (!verificationUrl || !deviceCode || !userCode) {
+    throw new CliError('Device authorization start returned an incomplete response.', {
+      code: 'INVALID_RESPONSE',
+      exitCode: EXIT_CODES.SERVER,
+    });
+  }
+
+  if (!opts.json) {
+    process.stdout.write(`[socialseal] Open this URL to approve login: ${verificationUrl}\n`);
+    process.stdout.write(`[socialseal] Confirm code: ${userCode}\n`);
+  }
+
+  if (opts.open !== false) {
+    openBrowser(String(verificationUrl), (error) => {
+      if (opts.verbose) {
+        process.stderr.write(`[socialseal] Could not open browser automatically: ${error.message || error}\n`);
+      }
+    });
+  }
+
+  const startedAt = Date.now();
+  let intervalMs = Math.max(1000, Number(authorizePayload.interval || 5) * 1000);
+  if (opts.pollInterval) {
+    intervalMs = parseTimeoutMs(opts.pollInterval, { defaultValue: intervalMs, label: 'poll interval' });
+  }
+
+  while (Date.now() - startedAt < timeoutMs) {
+    await sleep(intervalMs);
+    const tokenRes = await callPublicApi({
+      apiBase,
+      path: '/cli/device/token',
+      body: { device_code: deviceCode },
+      timeoutMs: Math.max(1000, timeoutMs - (Date.now() - startedAt)),
+    });
+    const tokenPayload = await readJsonResponse(tokenRes, 'Device token poll');
+
+    if (tokenRes.ok) {
+      const apiKey = typeof tokenPayload.api_key === 'string' ? tokenPayload.api_key : '';
+      if (!apiKey) {
+        throw new CliError('Device token poll returned no API key.', {
+          code: 'INVALID_RESPONSE',
+          exitCode: EXIT_CODES.SERVER,
+        });
+      }
+
+      const workspaceId = typeof tokenPayload.workspace_id === 'string' ? tokenPayload.workspace_id : config.workspaceId;
+      saveConfig({
+        ...config,
+        apiBase,
+        apiKey,
+        workspaceId,
+      });
+
+      const payload = {
+        success: true,
+        apiBase,
+        keySuffix: apiKey.slice(-6),
+        key: maskApiKey(apiKey),
+        workspaceId: workspaceId || null,
+        configPath: getConfigPath(),
+      };
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+        return;
+      }
+
+      process.stdout.write(`[socialseal] Login complete. Stored key ${maskApiKey(apiKey)} in ${getConfigPath()}\n`);
+      if (workspaceId) {
+        process.stdout.write(`[socialseal] Default workspace set to ${workspaceId}\n`);
+      }
+      return;
+    }
+
+    if (tokenPayload?.error === 'authorization_pending') {
+      if (!opts.json) process.stdout.write('[socialseal] Waiting for browser approval…\n');
+      continue;
+    }
+    if (tokenPayload?.error === 'slow_down') {
+      intervalMs = Math.min(intervalMs + 5000, 60000);
+      continue;
+    }
+
+    throw await buildHttpError(new Response(JSON.stringify(tokenPayload), {
+      status: tokenRes.status,
+      statusText: tokenRes.statusText,
+      headers: { 'Content-Type': 'application/json' },
+    }), { label: 'Device token poll' });
+  }
+
+  throw new CliError('Timed out waiting for browser approval.', {
+    code: 'DEVICE_LOGIN_TIMEOUT',
+    exitCode: EXIT_CODES.AUTH,
+    hint: 'Run `socialseal login` again when you are ready to approve in the browser.',
+  });
+}
+
+function handleLogout(opts) {
+  const config = loadConfig();
+  const hadApiKey = Boolean(resolveApiKey({}, config));
+  const nextConfig = { ...config };
+  delete nextConfig.apiKey;
+  saveConfig(nextConfig);
+
+  const payload = {
+    success: true,
+    removedLocalKey: hadApiKey,
+    configPath: getConfigPath(),
+  };
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+  process.stdout.write('[socialseal] Logged out locally. Any server-side key remains revocable from SocialSeal settings.\n');
+}
+
+async function handleWhoami(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 workspace = selection.workspaceId
+    ? workspaces.find((entry) => entry.id === selection.workspaceId) || null
+    : null;
+  const payload = {
+    authenticated: true,
+    apiBase: resolvedApiBase,
+    key: maskApiKey(apiKey),
+    keySuffix: apiKey.slice(-6),
+    effectiveWorkspaceId: selection.workspaceId,
+    effectiveWorkspaceSource: selection.source,
+    workspace,
+    workspaceCount: workspaces.length,
+  };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write(`[socialseal] Authenticated with key ${maskApiKey(apiKey)}\n`);
+  if (workspace) {
+    process.stdout.write(`[socialseal] Workspace: ${workspace.name} (${workspace.id})\n`);
+  } else if (directory.defaultWorkspaceId) {
+    process.stdout.write(`[socialseal] Suggested workspace: ${directory.defaultWorkspaceId}\n`);
+  }
+}
+
+function handleBilling(opts) {
+  const config = loadConfig();
+  const webBase = resolveWebBase(opts, config);
+  const billingUrl = `${webBase.replace(/\/$/, '')}/settings/billing`;
+  const payload = {
+    billingUrl,
+    note: 'SocialSeal starts on the free tier. Use billing only when credits or quotas are exhausted.',
+  };
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(payload, null, opts.pretty ? 2 : 0) + '\n');
+    return;
+  }
+
+  process.stdout.write(`[socialseal] Billing and credits: ${billingUrl}\n`);
+  process.stdout.write('[socialseal] SocialSeal starts on the free tier. Add billing only when you need more capacity.\n');
+}
+
 async function handleWorkspaceList(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -4915,7 +5681,47 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-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 schema --function search-journey-run\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools status 6809 --kind google_ai_run\n  socialseal tools status <run-uuid> --kind journey_run --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-options\n  socialseal data export-tracking --group-id 123 --time-period 30d\n  socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv\n  socialseal data export-group-evidence --group-id 123 --workspace-id <uuid> --out evidence.csv\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal login\n  socialseal whoami\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message "ping"\n  socialseal tools list\n  socialseal tools schema --function search-journey-run\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools status 6809 --kind google_ai_run\n  socialseal tools status <run-uuid> --kind journey_run --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-options\n  socialseal data export-tracking --group-id 123 --time-period 30d\n  socialseal data export-search-results --group-ids 123,124 --workspace-id <uuid> --out ranked.csv\n  socialseal data export-group-evidence --group-id 123 --workspace-id <uuid> --out evidence.csv\n`);
+
+program
+  .command('login')
+  .description('Start browser-based device login and store a local CLI key')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--no-open', 'Print the approval URL without opening a browser')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--timeout <ms>', 'Overall login timeout in milliseconds')
+  .option('--poll-interval <ms>', 'Polling interval in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleLogin, opts));
+
+program
+  .command('logout')
+  .description('Remove the locally stored SocialSeal CLI key')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleLogout, opts));
+
+program
+  .command('whoami')
+  .description('Show the current SocialSeal CLI authentication and 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(handleWhoami, opts));
+
+program
+  .command('billing')
+  .description('Show where to manage SocialSeal billing and credits')
+  .option('--web-base <url>', 'Web app base URL')
+  .option('--json', 'Emit machine-readable output')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleBilling, opts));
 
 program
   .command('agent')
@@ -4983,6 +5789,7 @@ const tools = program.command('tools').description('Call edge functions directly
 tools
   .command('list')
   .description('List built-in tool registry entries')
+  .option('--category <name>', 'Filter tools by category')
   .option('--json', 'Emit machine-readable output')
   .option('--pretty', 'Pretty-print JSON')
   .option('--verbose', 'Show error details')