@velaro/cli 1.2.0 → 1.4.8

package/lib/commands/support.js

@@ -0,0 +1,128 @@
+// velaro support — staff SupportTools / staff-scoped actions (superadmin only)
+import { request, messagingPost, messagingGet } from '../api.js';
+
+async function toggleFlag(args) {
+  if (!args.site || !args.flag || args.enabled === undefined) {
+    console.error('Usage: velaro support toggle-flag --site 1032 --flag EnableScraperBotIndexing --enabled true');
+    process.exit(1);
+  }
+  const enabled = args.enabled === 'true' || args.enabled === true;
+  const result = await request('POST', `SupportTools/sites/${args.site}/features/${args.flag}`, { enabled });
+  console.log(`✅ Site ${args.site}: ${result.flag} ${result.oldValue} → ${result.newValue}`);
+}
+
+async function scraperCreateJob(args) {
+  if (!args.site || !args.urls) {
+    console.error('Usage: velaro support scraper-create-job --site 1032 --urls "https://example.com" [--maxPages 30] [--crawlDepth 2] [--name "job name"]');
+    process.exit(1);
+  }
+  const urls = String(args.urls).split(',').map(u => u.trim()).filter(Boolean);
+  const body = {
+    name: args.name || `staff-triggered-${Date.now()}`,
+    urls,
+    crawlDepth: args.crawlDepth ?? 1,
+    maxPages: args.maxPages ?? 25,
+  };
+  const result = await request('POST', `ScraperJobs/StaffCreate/${args.site}`, body);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function chatQuery(args) {
+  if (!args.site || !args.aiConfigId || !args.query) {
+    console.error('Usage: velaro support chat-query --site 100150 --aiConfigId 179 --query "your test question" [--channel Web]');
+    process.exit(1);
+  }
+  const body = {
+    aiConfigId: args.aiConfigId,
+    query: args.query,
+    channel: args.channel || 'Web',
+    overrideIndexes: args.overrideIndexes ? String(args.overrideIndexes).split(',').map(s => s.trim()).filter(Boolean) : undefined,
+  };
+  // Hits velaro-messaging's AzureIndexes/StaffChatQuery/{targetSiteId} -- staff-only override for
+  // the customer-facing test-chat (ChatQuery) endpoint, added 2026-08-21 so a Velaro staff member
+  // can adversarial-test ANY site's bot without needing that site's own login.
+  const result = await messagingPost(`AzureIndexes/StaffChatQuery/${args.site}`, body);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function impersonate(args) {
+  if (!args.site) {
+    console.error('Usage: velaro support impersonate --site 100150   (SuperAdmin only; creates a 15-minute X-Support-Token to act as that site\'s admin, fully audit-logged)');
+    process.exit(1);
+  }
+  // Hits SupportToolsController.CreateImpersonationSession (SuperAdmin only, 15-min token,
+  // logged to both BillingAuditLog and the app logger). Added 2026-08-28 to close the gap where
+  // the backend endpoint existed but no CLI verb wrapped it.
+  const result = await request('POST', `SupportTools/sites/${args.site}/impersonate`);
+  console.log(`Impersonation session created for site ${args.site}, expires ${result.expiresAt}`);
+  console.log(`Token: ${result.token}`);
+  console.log('Send this as header X-Support-Token on subsequent requests to act as that site\'s admin.');
+}
+
+async function sendEmail(args) {
+  if (!args.to || !args.subject || !args.html) {
+    console.error('Usage: velaro support send-email --to andrea@velaro.com --subject "..." --html "<p>...</p>" [--cc alex@velaro.com]');
+    process.exit(1);
+  }
+  // Hits velaro-messaging's SupportTools/send-internal-email -- staff JWT or internal-site
+  // vel_live_* key, same auth pattern as every other SupportTools action, never the raw
+  // X-Velaro-Internal-Secret. Restricted server-side to @velaro.com recipients on purpose,
+  // this is for internal staff notifications, not a general external-send relay. Added
+  // 2026-09-01 to close the gap where the only working path required manually fetching a
+  // raw production secret via az.
+  const result = await messagingPost('SupportTools/send-internal-email', {
+    to: args.to,
+    cc: args.cc,
+    subject: args.subject,
+    html: args.html,
+  });
+  console.log(`✅ Sent to ${result.sentCount}/${result.of} recipient(s).`);
+}
+
+async function agentLookup(args) {
+  if (!args.id) {
+    console.error('Usage: velaro support agent-lookup --id 238');
+    process.exit(1);
+  }
+  // Hits velaro-messaging's SuperAdmin/agents/{id}/lookup -- read-only, cross-site WorkspaceUser.Id
+  // resolution for cases where a log line (AgentPresenceFlapping WARN, AgentConnectionLog, etc.)
+  // captured only a bare numeric AgentId with no SiteId. Added 2026-08-27.
+  const result = await messagingGet(`SuperAdmin/agents/${args.id}/lookup`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export function supportCommand(yargs) {
+  return yargs
+    .command('impersonate', 'Start a 15-minute impersonation session for any site (SuperAdmin only, fully audit-logged to the customer\'s own activity log and a management email)', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Target site ID to impersonate' })
+    , a => impersonate(a))
+    .command('send-email', 'Send an ad-hoc internal email via ACS, staff-authed, no raw secret ever needed (recipients must be @velaro.com)', y => y
+      .option('to',      { type: 'string', demandOption: true, desc: 'Comma-separated @velaro.com recipient(s)' })
+      .option('cc',      { type: 'string', desc: 'Comma-separated @velaro.com CC recipient(s)' })
+      .option('subject', { type: 'string', demandOption: true, desc: 'Email subject' })
+      .option('html',    { type: 'string', demandOption: true, desc: 'Email body as HTML' })
+    , a => sendEmail(a))
+    .command('agent-lookup', 'Resolve a bare WorkspaceUser.Id (AgentId) to its Email/DisplayName/SiteId across all sites (superadmin only, read-only)', y => y
+      .option('id', { type: 'number', demandOption: true, desc: 'WorkspaceUser.Id / AgentId to look up' })
+    , a => agentLookup(a))
+    .command('toggle-flag', 'Toggle a single legacy Subscription.cs feature flag on a site (superadmin only, allowlisted flags)', y => y
+      .option('site',    { type: 'number',  demandOption: true, desc: 'Site ID' })
+      .option('flag',    { type: 'string',  demandOption: true, desc: 'Flag name, e.g. EnableScraperBotIndexing (must be on SupportToolsController.AllowedFeatureFlags)' })
+      .option('enabled', { type: 'string',  demandOption: true, desc: 'true or false' })
+    , a => toggleFlag(a))
+    .command('scraper-create-job', 'Trigger a scraper job on behalf of any site (superadmin only — no need to be logged in as that site\'s own user)', y => y
+      .option('site',       { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('urls',       { type: 'string', demandOption: true, desc: 'Comma-separated URLs to crawl' })
+      .option('maxPages',   { type: 'number', desc: 'Max pages for this job (default 25, still capped by the site\'s own plan limits)' })
+      .option('crawlDepth', { type: 'number', desc: 'Crawl depth (default 1)' })
+      .option('name',       { type: 'string', desc: 'Job name' })
+    , a => scraperCreateJob(a))
+    .command('chat-query', 'Run a staff-only test-chat query against ANY site\'s AI config (superadmin only — no need to be logged in as that site\'s own user)', y => y
+      .option('site',            { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('aiConfigId',      { type: 'number', demandOption: true, desc: 'AI Configuration ID on the target site' })
+      .option('query',           { type: 'string', demandOption: true, desc: 'The test question to send' })
+      .option('channel',         { type: 'string', desc: 'Conversation source, e.g. Web, TwilioSms (default Web)' })
+      .option('overrideIndexes', { type: 'string', desc: 'Comma-separated index names to override the config\'s own IndexName for this query' })
+    , a => chatQuery(a))
+    .demandCommand(1, 'Specify a subcommand: impersonate | agent-lookup | toggle-flag | scraper-create-job | chat-query | send-email');
+}

package/lib/commands/survey.js

@@ -0,0 +1,216 @@
+// velaro survey — list/create/update/delete surveys, manage version history, list
+// submissions, and manage the Phase 1 standalone hosted share link (Surveys/* and
+// SurveySubmissions/* on velaro-messaging). Site isolation is enforced server-side by
+// SurveysController's/SurveySubmissionsController's [Authorize]-scoped SiteId
+// (ClientControllerBase) — never passed by the client.
+import { readFileSync } from 'node:fs';
+import { messagingGet, messagingPost, messagingDel, messagingRequest } from '../api.js';
+import { runCommand } from '../run.js';
+
+const get  = messagingGet;
+const post = messagingPost;
+const del  = messagingDel;
+
+export const surveyCommand = {
+  command:  'survey <subcommand>',
+  describe: 'Manage surveys — list, get, upsert, delete, version history, submissions, and standalone hosted share links',
+  builder:  (yargs) =>
+    yargs
+      .command(surveyListCommand)
+      .command(surveyGetCommand)
+      .command(surveyUpsertCommand)
+      .command(surveyDeleteCommand)
+      .command(surveyVersionsCommand)
+      .command(surveyVersionGetCommand)
+      .command(surveyVersionRestoreCommand)
+      .command(surveyStandaloneLinkEnableCommand)
+      .command(surveyStandaloneLinkDisableCommand)
+      .command(surveyMissedChatSubmissionsCommand)
+      .command(surveyStandaloneSubmissionsCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, upsert, delete, versions, version-get, version-restore, standalone-link-enable, standalone-link-disable, missed-chat-submissions, standalone-submissions'),
+  handler: () => {},
+};
+
+// ── list ─────────────────────────────────────────────────────────────────────
+
+const surveyListCommand = {
+  command:  'list',
+  describe: 'List all surveys on the current site',
+  handler:  runCommand(async () => {
+    const surveys = (await get('/Surveys/list')) ?? [];
+    if (!surveys.length) { console.log('No surveys found.'); return; }
+
+    const idW = Math.max(2, ...surveys.map((s) => String(s.id).length));
+    console.log(`\n${'id'.padStart(idW)}  name`);
+    console.log(`${'-'.repeat(idW)}  ----`);
+    for (const s of surveys) {
+      const linkNote = s.allowStandaloneAccess ? `  [standalone link active — slug: ${s.publicSlug}]` : '';
+      console.log(`${String(s.id).padStart(idW)}  ${s.name ?? '(unnamed)'}${linkNote}`);
+    }
+    console.log(`\n${surveys.length} survey(s)`);
+  }),
+};
+
+// ── get ──────────────────────────────────────────────────────────────────────
+
+const surveyGetCommand = {
+  command:  'get <id>',
+  describe: 'Get one survey by ID with its full shape, including all questions. There is no dedicated single-survey backend endpoint — this filters "survey list", which already includes each survey\'s full Questions array. Use this to fetch a template before "survey upsert".',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Survey ID' }),
+  handler:  runCommand(async (argv) => {
+    const surveys = (await get('/Surveys/list')) ?? [];
+    const survey = surveys.find((s) => s.id === argv.id);
+    if (!survey) throw new Error(`Survey ${argv.id} not found`);
+    console.log(JSON.stringify(survey, null, 2));
+  }),
+};
+
+// ── upsert ───────────────────────────────────────────────────────────────────
+
+const surveyUpsertCommand = {
+  command:  'upsert <file>',
+  describe: 'Create (omit id or set id=0) or update (set id) a survey from a JSON file containing the full SurveyViewModel shape (id, name, questions[], ...). Use "survey get <id>" on an existing survey to fetch a starting template.',
+  builder:  (y) => y.positional('file', { type: 'string', describe: 'Path to a JSON file with the survey body' }),
+  handler:  runCommand(async (argv) => {
+    const body = JSON.parse(readFileSync(argv.file, 'utf8'));
+    const survey = await post('/Surveys', body);
+    console.log(`Upserted survey ${survey.id} (${survey.name ?? '(unnamed)'}).`);
+  }),
+};
+
+// ── delete ───────────────────────────────────────────────────────────────────
+
+const surveyDeleteCommand = {
+  command:  'delete <id>',
+  describe: 'Delete a survey by ID',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Survey ID' }),
+  handler:  runCommand(async (argv) => {
+    // SurveysController.DeleteAsync takes the id in the request body, not the route —
+    // messagingDel() doesn't support a body, so call messagingRequest directly.
+    await messagingRequest('DELETE', '/Surveys', { id: argv.id });
+    console.log(`Deleted survey ${argv.id}.`);
+  }),
+};
+
+// ── versions ─────────────────────────────────────────────────────────────────
+
+const surveyVersionsCommand = {
+  command:  'versions <id>',
+  describe: 'List version history for a survey, newest first',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Survey ID' }),
+  handler:  runCommand(async (argv) => {
+    const versions = (await get(`/Surveys/${argv.id}/versions`)) ?? [];
+    if (!versions.length) { console.log('No version history found.'); return; }
+    for (const v of versions) {
+      console.log(`v${v.versionNumber}  ${v.changeType}  by ${v.changedBy || '(unknown)'}  at ${v.savedAt}`);
+    }
+    console.log(`\n${versions.length} version(s)`);
+  }),
+};
+
+const surveyVersionGetCommand = {
+  command:  'version-get <id> <versionNumber>',
+  describe: 'Show the full snapshot for one survey version',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'Survey ID' })
+      .positional('versionNumber', { type: 'number', describe: 'Version number (see "survey versions")' }),
+  handler:  runCommand(async (argv) => {
+    const version = await get(`/Surveys/${argv.id}/versions/${argv.versionNumber}`);
+    console.log(JSON.stringify(version, null, 2));
+  }),
+};
+
+const surveyVersionRestoreCommand = {
+  command:  'version-restore <id> <versionNumber>',
+  describe: 'Restore a survey to a prior version. Snapshots the current state first (as "PreRestore") so this is itself reversible.',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'Survey ID' })
+      .positional('versionNumber', { type: 'number', describe: 'Version number to restore (see "survey versions")' }),
+  handler:  runCommand(async (argv) => {
+    const survey = await post(`/Surveys/${argv.id}/versions/${argv.versionNumber}/restore`);
+    console.log(`Restored survey ${survey.id} to version ${argv.versionNumber}.`);
+  }),
+};
+
+// ── standalone-link-enable ──────────────────────────────────────────────────
+
+const surveyStandaloneLinkEnableCommand = {
+  command:  'standalone-link-enable <id>',
+  describe: "Generate (or re-confirm) a survey's public shareable link — a hosted page anyone can fill out without a live chat conversation, for email/SMS campaigns. Idempotent.",
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Survey ID' }),
+  handler:  runCommand(async (argv) => {
+    const result = await post(`/Surveys/${argv.id}/standalone-link`);
+    console.log(`Standalone link enabled for survey ${argv.id}.`);
+    console.log(`  Slug:   ${result.publicSlug}`);
+    console.log(`  Active: ${result.allowStandaloneAccess}`);
+  }),
+};
+
+// ── standalone-link-disable ─────────────────────────────────────────────────
+
+const surveyStandaloneLinkDisableCommand = {
+  command:  'standalone-link-disable <id>',
+  describe: "Revoke public access to a survey's standalone link. The slug is kept, so re-enabling later reuses the same URL instead of minting a new one.",
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Survey ID' }),
+  handler:  runCommand(async (argv) => {
+    const result = await del(`/Surveys/${argv.id}/standalone-link`);
+    console.log(`Standalone link disabled for survey ${argv.id}.`);
+    console.log(`  Slug (kept, inactive): ${result.publicSlug}`);
+    console.log(`  Active: ${result.allowStandaloneAccess}`);
+  }),
+};
+
+// ── missed-chat-submissions ─────────────────────────────────────────────────
+// SurveySubmissions/missed-chat -- rows from the AM-4013 Part 6 closed-launcher
+// survey surface (Type == "missedChat", no live ConversationBase). See
+// `velaro bundle update --show-on-closed-launcher` for turning this surface on.
+// Both endpoints server-side filter to Answers.Count > 0 -- an empty result can
+// mean "no submissions" OR "submissions exist but every one was empty," not
+// necessarily that the surface has never been used.
+const DEFAULT_SUBMISSION_LIMIT = 50;
+
+function printSubmissions(subs, label, limit) {
+  if (!subs.length) {
+    console.log(`No ${label} submissions with at least one answer found (submissions with zero answers are excluded server-side).`);
+    return;
+  }
+  const shown = subs.slice(0, limit);
+  for (const s of shown) {
+    console.log(`\n[${s.id}] survey ${s.surveyId ?? '(unknown)'}${s.missedReason ? ` — reason: ${s.missedReason}` : ''}`);
+    for (const a of s.answers ?? []) {
+      console.log(`    ${a.question ?? '(question)'}: ${a.answer ?? ''}`);
+    }
+  }
+  const omitted = subs.length - shown.length;
+  console.log(`\n${shown.length} of ${subs.length} ${label} submission(s) shown${omitted > 0 ? ` (${omitted} more omitted — pass --limit to see more)` : ''}`);
+}
+
+const surveyMissedChatSubmissionsCommand = {
+  command:  'missed-chat-submissions',
+  describe: 'List submissions collected from the closed-launcher ("we\'re unavailable") survey surface',
+  builder:  (y) => y
+    .option('survey-id', { type: 'number', describe: 'Narrow to one survey ID' })
+    .option('limit', { type: 'number', default: DEFAULT_SUBMISSION_LIMIT, describe: 'Max submissions to print' }),
+  handler:  runCommand(async (argv) => {
+    const qs = argv.surveyId ? `?surveyId=${argv.surveyId}` : '';
+    const subs = (await get(`/SurveySubmissions/missed-chat${qs}`)) ?? [];
+    printSubmissions(subs, 'missed-chat', argv.limit);
+  }),
+};
+
+// ── standalone-submissions ──────────────────────────────────────────────────
+
+const surveyStandaloneSubmissionsCommand = {
+  command:  'standalone-submissions',
+  describe: 'List submissions collected from a survey\'s public standalone hosted link',
+  builder:  (y) => y
+    .option('survey-id', { type: 'number', describe: 'Narrow to one survey ID' })
+    .option('limit', { type: 'number', default: DEFAULT_SUBMISSION_LIMIT, describe: 'Max submissions to print' }),
+  handler:  runCommand(async (argv) => {
+    const qs = argv.surveyId ? `?surveyId=${argv.surveyId}` : '';
+    const subs = (await get(`/SurveySubmissions/standalone${qs}`)) ?? [];
+    printSubmissions(subs, 'standalone', argv.limit);
+  }),
+};

package/lib/commands/team.js

@@ -1,144 +1,144 @@
-import { get, post }  from '../api.js';
-import { runCommand } from '../run.js';
-
-export const teamCommand = {
-  command:  'team <subcommand>',
-  describe: 'View teams and manage widget placements (deployments)',
-  builder:  (yargs) =>
-    yargs
-      .command(teamListCommand)
-      .command(widgetListCommand)
-      .command(widgetRenameCommand)
-      .command(widgetAssignCommand)
-      .demandCommand(1, 'Specify a subcommand: list, widget'),
-  handler: () => {},
-};
-
-// ── team list ──────────────────────────────────────────────────────────────────
-// Shows teams and their widget placements inline — the mental model is:
-//   team = who handles conversations
-//   widget = which pages route to that team
-
-const teamListCommand = {
-  command:  'list',
-  describe: 'List teams and their widget placements',
-  handler:  runCommand(async () => {
-    const [teams, deployments] = await Promise.all([
-      get('/Teams/List'),
-      get('/Deployment'),
-    ]);
-
-    if (!teams?.length) {
-      console.log('No teams found.');
-      return;
-    }
-
-    // Group deployments by team
-    const byTeam = {};
-    for (const d of (deployments ?? [])) {
-      if (!byTeam[d.teamId]) byTeam[d.teamId] = [];
-      byTeam[d.teamId].push(d);
-    }
-
-    for (const t of teams) {
-      const widgets = byTeam[t.id] ?? [];
-      const routing = t.routingAction ? `  routing=${t.routingAction}` : '';
-      console.log(`\n[${t.id}] ${t.name}${routing}`);
-
-      if (widgets.length) {
-        for (const w of widgets) {
-          console.log(`     widget [${w.id}] "${w.displayName ?? 'unnamed'}"  key: ${w.deploymentId}`);
-        }
-      } else {
-        console.log(`     (no widgets assigned — conversations can reach this team via routing rules)`);
-      }
-    }
-
-    console.log(`\n${teams.length} team(s)  ·  ${(deployments ?? []).length} widget(s)`);
-    console.log('\nPaste a widget key into your page\'s embed snippet to route that page to its team.');
-  }),
-};
-
-// ── widget subcommands ─────────────────────────────────────────────────────────
-// "Widget" is the user-facing term. Internally these are deployments.
-// A widget is a snippet you paste on a page. The page routes to the widget's team.
-
-const widgetListCommand = {
-  command:  'widget list',
-  describe: 'List all widgets (embed snippets) and which team each routes to',
-  handler:  runCommand(async () => {
-    const [deployments, teams] = await Promise.all([
-      get('/Deployment'),
-      get('/Teams/List'),
-    ]);
-
-    if (!deployments?.length) {
-      console.log('No widgets found.');
-      console.log('\nCreate a widget in the Velaro admin under Deployments,');
-      console.log('then paste its embed snippet on the pages you want chat on.');
-      return;
-    }
-
-    const teamMap = Object.fromEntries((teams ?? []).map(t => [t.id, t.name]));
-    const rows    = deployments.map(d => ({
-      id:   `[${d.id}]`,
-      key:  d.deploymentId ?? '—',
-      team: teamMap[d.teamId] ?? `team ${d.teamId}`,
-      name: d.displayName ?? '(unnamed)',
-    }));
-
-    const idW   = Math.max(...rows.map(r => r.id.length));
-    const keyW  = Math.max('embed-key'.length, ...rows.map(r => r.key.length));
-    const teamW = Math.max('routes-to'.length, ...rows.map(r => r.team.length));
-
-    console.log(`\n${'id'.padStart(idW)}  ${'embed-key'.padEnd(keyW)}  ${'routes-to'.padEnd(teamW)}  name`);
-    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(keyW)}  ${'-'.repeat(teamW)}  ----`);
-    for (const r of rows) {
-      console.log(`${r.id.padStart(idW)}  ${r.key.padEnd(keyW)}  ${r.team.padEnd(teamW)}  ${r.name}`);
-    }
-    console.log(`\n${rows.length} widget(s)`);
-  }),
-};
-
-const widgetRenameCommand = {
-  command:  'widget rename <id> <name>',
-  describe: 'Rename a widget',
-  builder:  (y) =>
-    y
-      .positional('id',   { type: 'number', describe: 'Widget ID' })
-      .positional('name', { type: 'string', describe: 'New name' }),
-  handler: runCommand(async (argv) => {
-    const dep = await get(`/Deployment/${argv.id}`);
-    if (!dep) { console.error(`Widget ${argv.id} not found.`); process.exit(1); }
-    await post('/Deployment', { ...dep, id: argv.id, displayName: argv.name });
-    console.log(`Widget ${argv.id} renamed to "${argv.name}".`);
-  }),
-};
-
-const widgetAssignCommand = {
-  command:  'widget assign <id> <team-id>',
-  describe: 'Point a widget at a different team (embed code stays the same)',
-  builder:  (y) =>
-    y
-      .positional('id',      { type: 'number', describe: 'Widget ID' })
-      .positional('team-id', { type: 'number', describe: 'Team ID to route to' }),
-  handler: runCommand(async (argv) => {
-    const [dep, teams] = await Promise.all([
-      get(`/Deployment/${argv.id}`),
-      get('/Teams/List'),
-    ]);
-
-    if (!dep) { console.error(`Widget ${argv.id} not found.`); process.exit(1); }
-
-    const team = (teams ?? []).find(t => t.id === argv['team-id']);
-    if (!team) {
-      console.error(`Team ${argv['team-id']} not found.`);
-      console.error('Run: velaro team list');
-      process.exit(1);
-    }
-
-    await post('/Deployment', { ...dep, id: argv.id, teamId: argv['team-id'] });
-    console.log(`Widget "${dep.displayName ?? dep.id}" now routes to team "${team.name}".`);
-    console.log('Your embed snippet is unchanged — no website edits needed.');
-  }),
-};
+import { get, post }  from '../api.js';
+import { runCommand } from '../run.js';
+
+export const teamCommand = {
+  command:  'team <subcommand>',
+  describe: 'View teams and manage widget placements (deployments)',
+  builder:  (yargs) =>
+    yargs
+      .command(teamListCommand)
+      .command(widgetListCommand)
+      .command(widgetRenameCommand)
+      .command(widgetAssignCommand)
+      .demandCommand(1, 'Specify a subcommand: list, widget'),
+  handler: () => {},
+};
+
+// ── team list ──────────────────────────────────────────────────────────────────
+// Shows teams and their widget placements inline — the mental model is:
+//   team = who handles conversations
+//   widget = which pages route to that team
+
+const teamListCommand = {
+  command:  'list',
+  describe: 'List teams and their widget placements',
+  handler:  runCommand(async () => {
+    const [teams, deployments] = await Promise.all([
+      get('/Teams/List'),
+      get('/Deployment'),
+    ]);
+
+    if (!teams?.length) {
+      console.log('No teams found.');
+      return;
+    }
+
+    // Group deployments by team
+    const byTeam = {};
+    for (const d of (deployments ?? [])) {
+      if (!byTeam[d.teamId]) byTeam[d.teamId] = [];
+      byTeam[d.teamId].push(d);
+    }
+
+    for (const t of teams) {
+      const widgets = byTeam[t.id] ?? [];
+      const routing = t.routingAction ? `  routing=${t.routingAction}` : '';
+      console.log(`\n[${t.id}] ${t.name}${routing}`);
+
+      if (widgets.length) {
+        for (const w of widgets) {
+          console.log(`     widget [${w.id}] "${w.displayName ?? 'unnamed'}"  key: ${w.deploymentId}`);
+        }
+      } else {
+        console.log(`     (no widgets assigned — conversations can reach this team via routing rules)`);
+      }
+    }
+
+    console.log(`\n${teams.length} team(s)  ·  ${(deployments ?? []).length} widget(s)`);
+    console.log('\nPaste a widget key into your page\'s embed snippet to route that page to its team.');
+  }),
+};
+
+// ── widget subcommands ─────────────────────────────────────────────────────────
+// "Widget" is the user-facing term. Internally these are deployments.
+// A widget is a snippet you paste on a page. The page routes to the widget's team.
+
+const widgetListCommand = {
+  command:  'widget list',
+  describe: 'List all widgets (embed snippets) and which team each routes to',
+  handler:  runCommand(async () => {
+    const [deployments, teams] = await Promise.all([
+      get('/Deployment'),
+      get('/Teams/List'),
+    ]);
+
+    if (!deployments?.length) {
+      console.log('No widgets found.');
+      console.log('\nCreate a widget in the Velaro admin under Deployments,');
+      console.log('then paste its embed snippet on the pages you want chat on.');
+      return;
+    }
+
+    const teamMap = Object.fromEntries((teams ?? []).map(t => [t.id, t.name]));
+    const rows    = deployments.map(d => ({
+      id:   `[${d.id}]`,
+      key:  d.deploymentId ?? '—',
+      team: teamMap[d.teamId] ?? `team ${d.teamId}`,
+      name: d.displayName ?? '(unnamed)',
+    }));
+
+    const idW   = Math.max(...rows.map(r => r.id.length));
+    const keyW  = Math.max('embed-key'.length, ...rows.map(r => r.key.length));
+    const teamW = Math.max('routes-to'.length, ...rows.map(r => r.team.length));
+
+    console.log(`\n${'id'.padStart(idW)}  ${'embed-key'.padEnd(keyW)}  ${'routes-to'.padEnd(teamW)}  name`);
+    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(keyW)}  ${'-'.repeat(teamW)}  ----`);
+    for (const r of rows) {
+      console.log(`${r.id.padStart(idW)}  ${r.key.padEnd(keyW)}  ${r.team.padEnd(teamW)}  ${r.name}`);
+    }
+    console.log(`\n${rows.length} widget(s)`);
+  }),
+};
+
+const widgetRenameCommand = {
+  command:  'widget rename <id> <name>',
+  describe: 'Rename a widget',
+  builder:  (y) =>
+    y
+      .positional('id',   { type: 'number', describe: 'Widget ID' })
+      .positional('name', { type: 'string', describe: 'New name' }),
+  handler: runCommand(async (argv) => {
+    const dep = await get(`/Deployment/${argv.id}`);
+    if (!dep) { console.error(`Widget ${argv.id} not found.`); process.exit(1); }
+    await post('/Deployment', { ...dep, id: argv.id, displayName: argv.name });
+    console.log(`Widget ${argv.id} renamed to "${argv.name}".`);
+  }),
+};
+
+const widgetAssignCommand = {
+  command:  'widget assign <id> <team-id>',
+  describe: 'Point a widget at a different team (embed code stays the same)',
+  builder:  (y) =>
+    y
+      .positional('id',      { type: 'number', describe: 'Widget ID' })
+      .positional('team-id', { type: 'number', describe: 'Team ID to route to' }),
+  handler: runCommand(async (argv) => {
+    const [dep, teams] = await Promise.all([
+      get(`/Deployment/${argv.id}`),
+      get('/Teams/List'),
+    ]);
+
+    if (!dep) { console.error(`Widget ${argv.id} not found.`); process.exit(1); }
+
+    const team = (teams ?? []).find(t => t.id === argv['team-id']);
+    if (!team) {
+      console.error(`Team ${argv['team-id']} not found.`);
+      console.error('Run: velaro team list');
+      process.exit(1);
+    }
+
+    await post('/Deployment', { ...dep, id: argv.id, teamId: argv['team-id'] });
+    console.log(`Widget "${dep.displayName ?? dep.id}" now routes to team "${team.name}".`);
+    console.log('Your embed snippet is unchanged — no website edits needed.');
+  }),
+};