quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/tg.js

@@ -0,0 +1,240 @@
+/**
+ * Telegram Pro commands (QTG-PRO P0 CLI parity): onboarding status, owner
+ * binding, session leases, and webhook admin.
+ *
+ * quox tg status [--bot <botId>]
+ * quox tg bind-owner <tg_chat_id> [--bot <botId>]
+ * quox tg leases
+ * quox tg webhook-info [--bot <botId>]
+ * quox tg setup <webhook_url> [--bot <botId>]
+ *
+ * Backend: services/collector/server.js (QTG-PRO P0 sections) — every route
+ * is collector-direct (no org segment in the URL), requireServiceOrUserAuth()
+ * gated. Onboarding handler bodies live in
+ * services/collector/lib/telegramPro/onboardingService.js (getOnboardingStatus,
+ * bindOwner); session leases in services/collector/lib/telegramPro/sessionLeaseStore.js;
+ * webhook admin reuses the existing /webhook/telegram/* routes shared with
+ * the original Telegram integration setup flow.
+ *
+ * bind-owner 409s when a primary owner binding already exists for the
+ * bot/chat/thread — mirrored on the quoxchat `reply` 409 convention
+ * (cli/lib/commands/quoxchat.js): catch, surface a plain-language error, and
+ * point the caller at `quox tg status` rather than trying to unpack response
+ * detail the generic client error path doesn't forward (QuoxApiError only
+ * carries `detail`/`details`, not arbitrary body fields like `binding`).
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}
+
+function isoOrDash(value) {
+  if (value === null || value === undefined) return '-';
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? String(value) : d.toISOString();
+}
+
+function renderStatus(data, botId) {
+  const lines = [];
+  lines.push('');
+  lines.push(`Bot: ${botId || 'default'}`);
+  if (data.bot) {
+    lines.push(`  Username        ${data.bot.username || '-'}`);
+    lines.push(`  Name            ${data.bot.name || '-'}`);
+  } else {
+    lines.push('  (no bot token configured)');
+  }
+  lines.push(`  Webhook URL     ${data.webhook?.url || '-'}`);
+  lines.push(`  Webhook active  ${yesNo(!!data.webhook?.active)}`);
+  if (data.webhook?.last_error_message) {
+    lines.push(`  Last error      ${data.webhook.last_error_message}`);
+  }
+  if (data.owner_binding) {
+    lines.push(`  Owner chat      ${data.owner_binding.tg_chat_id}${data.owner_binding.title ? ` (${data.owner_binding.title})` : ''}`);
+  } else {
+    lines.push('  Owner chat      not bound');
+  }
+  return lines.join('\n');
+}
+
+export function registerTgCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const tg = program
+    .command('tg')
+    .description('Manage Telegram Pro: onboarding status, owner binding, session leases, webhook admin');
+
+  // ── status ───────────────────────────────────────────────────────────────
+
+  tg
+    .command('status')
+    .description('Show Telegram Pro onboarding status: bot, webhook, seen chats, owner binding')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.bot) query.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.status');
+      const data = await client.get(ep.path, { service: ep.service, query });
+
+      const format = program.opts().output;
+      if (format === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      if (format === 'quiet') {
+        console.log(data.bot?.username || '');
+        return;
+      }
+
+      console.log(renderStatus(data, options.bot));
+
+      formatOutput({
+        columns: ['tg_chat_id', 'title', 'is_forum', 'seen_at'],
+        headers: ['Chat ID', 'Title', 'Forum', 'Seen'],
+        rows: (data.chats_seen || []).map((c) => ({
+          tg_chat_id: c.tg_chat_id,
+          title: c.title || '-',
+          is_forum: yesNo(c.is_forum),
+          seen_at: c.seen_at || '-',
+        })),
+      }, { format, emptyMessage: 'No chats seen yet — message the bot from a chat first.' });
+
+      if (data.bots && data.bots.length) {
+        console.log('\nBots');
+        formatOutput({
+          columns: ['bot_id', 'username', 'kind', 'webhook_active', 'chats_bound'],
+          headers: ['Bot ID', 'Username', 'Kind', 'Webhook', 'Chats'],
+          rows: data.bots.map((b) => ({
+            bot_id: b.bot_id,
+            username: b.username || '-',
+            kind: b.kind,
+            webhook_active: yesNo(b.webhook_active),
+            chats_bound: b.chats_bound,
+          })),
+        }, { format, emptyMessage: 'No bots configured.' });
+      }
+    });
+
+  // ── bind-owner ───────────────────────────────────────────────────────────
+
+  tg
+    .command('bind-owner')
+    .description('Bind a Telegram chat as the owner target (the chat must have messaged the bot first)')
+    .argument('<tg_chat_id>', 'Telegram chat ID that has already messaged the bot')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (tgChatId, options) => {
+      auth.requireAuth();
+      const body = { tg_chat_id: tgChatId };
+      if (options.bot) body.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.bindOwner');
+      try {
+        const data = await client.post(ep.path, { service: ep.service, body });
+        if (program.opts().output === 'json') {
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+        printSuccess(`Owner bound to chat ${tgChatId}.`);
+        if (data.binding) {
+          formatDetail(data.binding, {
+            format: program.opts().output,
+            title: 'Owner Binding',
+          });
+        }
+      } catch (err) {
+        if (err.status === 409) {
+          throw new Error(
+            `A primary owner binding already exists for this bot. Run \`quox tg status${options.bot ? ` --bot ${options.bot}` : ''}\` to see the current owner binding before rebinding.`
+          );
+        }
+        throw err;
+      }
+    });
+
+  // ── leases ───────────────────────────────────────────────────────────────
+
+  tg
+    .command('leases')
+    .description('List session leases for parallel terminal identities (T1-T8)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('tg.leases.list');
+      const data = await client.get(ep.path, { service: ep.service });
+
+      formatOutput({
+        columns: ['terminal', 'session_id', 'stream', 'alive', 'expires_at'],
+        headers: ['Terminal', 'Session ID', 'Stream', 'Alive', 'Expires'],
+        rows: (data.leases || []).map((l) => ({
+          terminal: l.terminal,
+          session_id: l.session_id,
+          stream: l.stream || '-',
+          alive: yesNo(l.alive),
+          expires_at: isoOrDash(l.expires_at),
+        })),
+      }, { format: program.opts().output, emptyMessage: 'No active session leases.' });
+    });
+
+  // ── webhook-info ─────────────────────────────────────────────────────────
+
+  tg
+    .command('webhook-info')
+    .description('Show current Telegram webhook status (per-bot info is pending backend support; --bot is a no-op today)')
+    .option('--bot <botId>', 'target a specific bot ID (not yet honored server-side)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.bot) query.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.webhook.info');
+      const data = await client.get(ep.path, { service: ep.service, query });
+
+      formatDetail({
+        active: data.active,
+        has_token: data.has_token,
+        bot_username: data.bot_username,
+        webhook_url: data.webhook_url,
+        pending_update_count: data.pending_update_count,
+        last_error_date: data.last_error_date,
+        last_error_message: data.last_error_message,
+      }, {
+        format: program.opts().output,
+        title: 'Telegram Webhook Info',
+        labels: {
+          active: 'Active',
+          has_token: 'Has token',
+          bot_username: 'Bot username',
+          webhook_url: 'Webhook URL',
+          pending_update_count: 'Pending updates',
+          last_error_date: 'Last error date',
+          last_error_message: 'Last error message',
+        },
+      });
+    });
+
+  // ── setup ────────────────────────────────────────────────────────────────
+
+  tg
+    .command('setup')
+    .description('Register the Telegram webhook URL for the bot')
+    .argument('<webhook_url>', 'HTTPS URL Telegram should POST updates to')
+    .option('--bot <botId>', 'target a specific bot ID instead of the default gateway bot')
+    .action(async (webhookUrl, options) => {
+      auth.requireAuth();
+      const body = { webhook_url: webhookUrl };
+      if (options.bot) body.bot_id = options.bot;
+
+      const ep = resolveEndpoint('tg.webhook.setup');
+      const data = await client.post(ep.path, { service: ep.service, body });
+
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      printSuccess(`Webhook registered: ${data.webhook_url} (bot: ${data.bot_username || 'unknown'}).`);
+    });
+}

package/lib/commands/tiktok.js

@@ -0,0 +1,218 @@
+/**
+ * `quox tiktok` — TikTok plugin verbs, TT-4 (instagram CLI parity).
+ *
+ * quox tiktok publish "<title>" --file <path-in-media-root> [--privacy SELF_ONLY|MUTUAL_FOLLOW_FRIENDS|PUBLIC_TO_EVERYONE] [--no-duet] [--no-comment] [--no-stitch]
+ * quox tiktok draft "<title>" --file <path-in-media-root>
+ * quox tiktok profile
+ * quox tiktok videos [--limit <n>]
+ * quox tiktok stats --ids <id,id,...>
+ * quox tiktok status --publish-id <id>
+ *
+ * The write verbs (publish, draft) execute the tiktok connector tool through
+ * the governed collector endpoint (POST /api/v1/tools/execute -> connector
+ * bridge). The bridge gates both on requiresApproval: it files an owner
+ * approval card and returns immediately with { pending:true,
+ * status:'awaiting_approval', approvalId, inbox_item_id }. The actual TikTok
+ * API write (video/init -> upload -> publish, or the inbox/draft init ->
+ * upload) only happens once the owner approves via the dashboard inbox or
+ * `quox inbox respond <id> --action approve`.
+ *
+ * TikTok has its OWN dedicated vaulted credential; there is no shared
+ * credential with any other plugin. Two hard truths this CLI states
+ * honestly: an unaudited TikTok app is restricted to posting private
+ * (SELF_ONLY) content regardless of the privacy level requested, until
+ * TikTok approves the app audit; and access tokens live 24 hours with no
+ * automatic refresh built yet.
+ */
+
+import { formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const PRIVACY_LEVELS = ['SELF_ONLY', 'MUTUAL_FOLLOW_FRIENDS', 'PUBLIC_TO_EVERYONE'];
+
+/**
+ * Execute one tiktok connector tool via the governed collector endpoint.
+ * A pending-approval response is a SUCCESS shape here (the card was filed);
+ * only a non-pending success:false is an error.
+ */
+async function executeTikTokTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing publishes until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerTikTokCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const tiktok = program
+    .command('tiktok')
+    .description('TikTok video publishing and draft uploads: governed, HITL-approved via HITL Inbox, on your own dedicated TikTok credential');
+
+  // ── tiktok publish ────────────────────────────────────────────────────
+
+  tiktok
+    .command('publish')
+    .description('Publish a video from a file under the org TikTok media root. Files an owner approval card and returns immediately; never publishes directly.')
+    .argument('<title>', 'video title/caption')
+    .requiredOption('--file <path>', 'video file path, relative to the org TikTok media root')
+    .option('--privacy <level>', `privacy level: ${PRIVACY_LEVELS.join('|')} (default SELF_ONLY)`, 'SELF_ONLY')
+    .option('--no-duet', 'disable duets on this video')
+    .option('--no-comment', 'disable comments on this video')
+    .option('--no-stitch', 'disable stitching on this video')
+    .action(async (title, options) => {
+      const privacy = options.privacy || 'SELF_ONLY';
+      if (!PRIVACY_LEVELS.includes(privacy)) {
+        throw new Error(`--privacy must be one of ${PRIVACY_LEVELS.join(', ')} (got ${privacy})`);
+      }
+
+      const input = {
+        title,
+        video_path: options.file,
+        privacy_level: privacy,
+        disable_duet: !options.duet,
+        disable_comment: !options.comment,
+        disable_stitch: !options.stitch,
+      };
+
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_publish_video', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Publish', data);
+      if (privacy !== 'SELF_ONLY') {
+        printWarning(`Requested privacy_level=${privacy} is sent to TikTok exactly as asked, but an unaudited TikTok app is restricted to private (SELF_ONLY) viewing until TikTok approves the app audit. Check the outcome with: quox tiktok status --publish-id <id>`);
+      }
+    });
+
+  // ── tiktok draft ──────────────────────────────────────────────────────
+
+  tiktok
+    .command('draft')
+    .description('Upload a video to the account\'s TikTok inbox as a draft, finished manually in the TikTok app. Files an owner approval card and returns immediately; never uploads directly.')
+    .argument('<title>', 'working title for the draft (display only)')
+    .requiredOption('--file <path>', 'video file path, relative to the org TikTok media root')
+    .action(async (title, options) => {
+      const input = { title, video_path: options.file };
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_upload_draft', input);
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      printAwaitingApproval('Draft upload', data);
+    });
+
+  // ── tiktok profile (read; cheapest live credential check) ──────────────
+
+  tiktok
+    .command('profile')
+    .description('Show the connected TikTok profile (also the cheapest live credential check).')
+    .action(async () => {
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_profile', {});
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (!result.open_id && !result.display_name) {
+        printInfo('No profile returned.');
+        return;
+      }
+      console.log(`${result.display_name || 'unknown'}  (${result.open_id || 'unknown'})`);
+      console.log(`  followers: ${result.followers ?? 'unknown'}  following: ${result.following ?? 'unknown'}  likes: ${result.likes ?? 'unknown'}  videos: ${result.videos ?? 'unknown'}`);
+    });
+
+  // ── tiktok videos (read) ────────────────────────────────────────────────
+
+  tiktok
+    .command('videos')
+    .description('List the connected account\'s recent videos (read-only, no approval needed).')
+    .option('--limit <n>', 'max videos to return (max 20)', '10')
+    .action(async (options) => {
+      const maxCount = Math.min(parseInt(options.limit, 10) || 10, 20);
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_list_videos', { max_count: maxCount });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const videos = data.result?.videos || [];
+      if (videos.length === 0) {
+        printInfo('No videos returned.');
+        return;
+      }
+      for (const v of videos) {
+        console.log(`${v.id}  ${v.title || '(no title)'}`);
+        console.log(`  views: ${v.views ?? 0}  likes: ${v.likes ?? 0}  comments: ${v.comments ?? 0}  shares: ${v.shares ?? 0}`);
+      }
+    });
+
+  // ── tiktok stats (read) ──────────────────────────────────────────────────
+
+  tiktok
+    .command('stats')
+    .description('Show engagement stats for specific videos by id.')
+    .requiredOption('--ids <ids>', 'comma-separated TikTok video IDs')
+    .action(async (options) => {
+      const videoIds = options.ids.split(',').map((s) => s.trim()).filter(Boolean);
+      if (videoIds.length === 0) {
+        throw new Error('tiktok stats requires at least one id in --ids');
+      }
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_video_stats', { video_ids: videoIds });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const videos = data.result || [];
+      if (videos.length === 0) {
+        printInfo('No stats returned.');
+        return;
+      }
+      for (const v of videos) {
+        console.log(`${v.id}  ${v.title || '(no title)'}`);
+        console.log(`  views: ${v.views ?? 0}  likes: ${v.likes ?? 0}  comments: ${v.comments ?? 0}  shares: ${v.shares ?? 0}`);
+      }
+    });
+
+  // ── tiktok status (read) ─────────────────────────────────────────────────
+
+  tiktok
+    .command('status')
+    .description('Check the status of a video publish or draft upload by publish_id.')
+    .requiredOption('--publish-id <id>', 'the publish_id returned by publish or draft')
+    .action(async (options) => {
+      const data = await executeTikTokTool({ client, auth, program }, 'tiktok_get_publish_status', { publish_id: options.publishId });
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+      const result = data.result || {};
+      if (!result.status) {
+        printInfo('No status returned.');
+        return;
+      }
+      console.log(`${result.publish_id}  status: ${result.status}`);
+      if (result.fail_reason) console.log(`  fail_reason: ${result.fail_reason}`);
+      if (result.publicly_available_post_ids) console.log(`  publicly_available_post_ids: ${result.publicly_available_post_ids}`);
+    });
+}

package/lib/commands/tool.js

@@ -0,0 +1,216 @@
+/**
+ * Tool commands: CRUD, catalog, install, publish
+ */
+
+import { missingReasonWarning } from '../core/callerSource.js';
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { resolveOrgId, parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerToolCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const tool = program
+    .command('tool')
+    .description('Manage tools and tool catalog');
+
+  tool
+    .command('list')
+    .description('List tools in the organization')
+    .option('--type <type>', 'filter by type: mcp, function, api, script, workflow')
+    .option('--status <status>', 'filter by status: active, draft')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const query = {};
+      if (options.type) query.type = options.type;
+      if (options.status) query.status = options.status;
+      const data = await client.get(resolveEndpoint('tools.list', { orgId }).path, { service: resolveEndpoint('tools.list', { orgId }).service, query });
+      formatOutput({
+        // fleet #392: column is tool_type.
+        columns: ['id', 'name', 'tool_type', 'status', 'risk_level', 'created_at'],
+        headers: ['ID', 'Name', 'Type', 'Status', 'Risk', 'Created'],
+        rows: data.items || data.tools || data,
+      }, { format: program.opts().output });
+    });
+
+  tool
+    .command('get')
+    .description('Get tool details')
+    .argument('<toolId>', 'tool ID')
+    .action(async (toolId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const data = await client.get(resolveEndpoint('tools.get', { orgId, toolId }).path, { service: resolveEndpoint('tools.get', { orgId, toolId }).service });
+      formatDetail(data.tool || data, { format: program.opts().output, title: data.tool?.name || data.name });
+    });
+
+  tool
+    .command('create')
+    .description('Create a new tool')
+    .requiredOption('--name <name>', 'tool name')
+    .requiredOption('--type <type>', 'type: mcp, function, api, script, workflow')
+    .option('--description <desc>', 'description')
+    .option('--risk-level <level>', 'risk level: low, medium, high', 'low')
+    .option('--spec <json>', 'tool spec as JSON string')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {
+        name: options.name,
+        type: options.type,
+        risk_level: options.riskLevel,
+      };
+      if (options.description) body.description = options.description;
+      if (options.spec) body.spec = parseJSON(options.spec, '--spec');
+      await client.post(resolveEndpoint('tools.create', { orgId }).path, { service: resolveEndpoint('tools.create', { orgId }).service, body });
+      printSuccess(`Tool "${options.name}" created.`);
+    });
+
+  tool
+    .command('update')
+    .description('Update a tool')
+    .argument('<toolId>', 'tool ID')
+    .option('--name <name>', 'new name')
+    .option('--description <desc>', 'new description')
+    .option('--status <status>', 'new status')
+    .action(async (toolId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const body = {};
+      if (options.name) body.name = options.name;
+      if (options.description) body.description = options.description;
+      if (options.status) body.status = options.status;
+      await client.patch(resolveEndpoint('tools.update', { orgId, toolId }).path, { service: resolveEndpoint('tools.update', { orgId, toolId }).service, body });
+      printSuccess('Tool updated.');
+    });
+
+  tool
+    .command('delete')
+    .description('Delete a tool')
+    .argument('<toolId>', 'tool ID')
+    .action(async (toolId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await client.delete(resolveEndpoint('tools.delete', { orgId, toolId }).path, { service: resolveEndpoint('tools.delete', { orgId, toolId }).service });
+      printSuccess('Tool deleted.');
+    });
+
+  tool
+    .command('publish')
+    .description('Publish a tool')
+    .argument('<toolId>', 'tool ID')
+    .action(async (toolId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await client.post(resolveEndpoint('tools.publish', { orgId, toolId }).path, { service: resolveEndpoint('tools.publish', { orgId, toolId }).service });
+      printSuccess('Tool published.');
+    });
+
+  tool
+    .command('catalog')
+    .description('Browse the tool catalog')
+    .option('--search <query>', 'search tools')
+    .option('--category <cat>', 'filter by category')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = {};
+      if (options.search) query.search = options.search;
+      if (options.category) query.category = options.category;
+      const data = await client.get(resolveEndpoint('catalog.list').path, { service: resolveEndpoint('catalog.list').service, query });
+      // NOTE: display the business key `tool_id` (not the catalog row `id`)
+      // as the identifier column — `tool install <toolId>` and the
+      // POST /api/tools/install-to-scope handler both validate against
+      // tool_definitions.tool_id, not tool_definitions.id. Showing `id`
+      // here previously led users to copy the wrong value into `install`.
+      formatOutput({
+        columns: ['tool_id', 'name', 'category', 'risk_level', 'description'],
+        headers: ['Tool ID', 'Name', 'Category', 'Risk', 'Description'],
+        rows: data.items || data.tools || data,
+      }, { format: program.opts().output });
+    });
+
+  tool
+    .command('exec')
+    .description('Execute a governed tool via the collector (POST /api/v1/tools/execute)')
+    .argument('<name>', 'tool name/id (the TOOL_DEFS key, e.g. "codebase_query")')
+    .option('--args <json>', "tool arguments as a JSON string, e.g. '{\"query\":\"...\"}'", '{}')
+    // #620: docs/muscle-memory reach for --input; accept it as an alias for
+    // --args so the documented form works. --args still wins if both given.
+    .option('--input <json>', 'alias for --args (tool arguments as a JSON string)')
+    .option('--reason <text>', 'why you are running this; shown on the approval card if the call is held for a human')
+    .action(async (name, options) => {
+      auth.requireAuth();
+      // Prefer whichever was explicitly given; --args carries the '{}' default
+      // so it is always defined, hence check --input first.
+      const usedInput = options.input !== undefined && (options.args === undefined || options.args === '{}');
+      const raw = usedInput ? options.input : options.args;
+      const input = parseJSON(raw, usedInput ? '--input' : '--args');
+      const body = { tool_name: name, input };
+      if (options.reason) body.reason = String(options.reason);
+      { const w = missingReasonWarning(name, options.reason); if (w) console.error(w); }
+
+      // Same org-resolution precedence as `fleet exec` (lib/commands/fleet.js):
+      // the collector's /api/v1/tools/execute requires org_id in the body for
+      // service-key authenticated callers (isServiceKeyAuth = !req.user,
+      // services/collector/server.js ~8326) since there is no session to
+      // derive org from. A human-logged-in caller has req.user and the
+      // server derives org from the session instead — --org / QUOX_ORG_ID
+      // still wins when set explicitly.
+      const orgId = auth.getOrgId(program.opts().org || process.env.QUOX_ORG_ID);
+      if (!orgId && process.env.QUOX_SERVICE_KEY) {
+        throw new Error(
+          'QUOX_SERVICE_KEY is set but no org could be resolved. '
+          + 'Set QUOX_ORG_ID=<org> for automation callers, or pass --org <id>.'
+        );
+      }
+      if (orgId) body.org_id = orgId;
+
+      // QUOXHAT T0 (2026-10-01): automation callers (the collector's
+      // CLI-tools chat path) carry the conversation + acting user in env,
+      // exactly like QUOX_ORG_ID above. The collector's execute route keys
+      // hat-binding resolution on body.session_id and user prefs on
+      // body.user_id; without them every CLI-tools execution ran against the
+      // org default hat and user-less. Interactive humans have neither set.
+      if (process.env.QUOX_SESSION_ID) body.session_id = process.env.QUOX_SESSION_ID;
+      if (process.env.QUOX_USER_ID) body.user_id = process.env.QUOX_USER_ID;
+      // QUOXHAT #657 P-C.2: forward the ACTING AGENT so a specialist's CLI-tools
+      // chat turn executes as that specialist, not the orchestrator. Without it
+      // the spawned CLI is a service caller with no agent_id, which the
+      // collector defaults to 'quox' — so under enforce a restricted specialist
+      // would silently run tools against the orchestrator's broad grant (the
+      // "CLI exec silently becomes quox" bypass). The collector sets this from
+      // its own selected_agent; a service-key caller's known agent_id is
+      // trusted, and the P-B gate then authorizes against the specialist's own
+      // grant ceiling ∩ the hat mode.
+      if (process.env.QUOX_AGENT_ID) body.agent_id = process.env.QUOX_AGENT_ID;
+
+      const ep = resolveEndpoint('v1.tools.execute');
+      const data = await client.post(ep.path, { service: ep.service, body, timeout: 120000 });
+
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+      }
+      const result = data && (data.result !== undefined ? data.result : data);
+      if (typeof result === 'string') {
+        console.log(result);
+      } else {
+        console.log(JSON.stringify(result, null, 2));
+      }
+    });
+
+  tool
+    .command('install')
+    .description('Install a tool from the catalog')
+    .argument('<toolId>', 'catalog tool_id (the "Tool ID" column from `tool catalog`, not its row id)')
+    .action(async (toolId) => {
+      auth.requireAuth();
+      // org_id is derived server-side from the JWT — no :orgId in the path.
+      await client.post(resolveEndpoint('tools.install-to-scope').path, {
+        service: resolveEndpoint('tools.install-to-scope').service,
+        body: { tool_id: toolId },
+      });
+      printSuccess('Tool installed.');
+    });
+}