@velaro/cli 1.4.101 → 1.4.103

package/README.md

@@ -138,6 +138,25 @@ velaro kb article screenshot 1234 \
 
 > Titles are auto-normalized to Title Case with no dashes, even if you pass a slug-style name — use `--no-title-normalize` to skip that.
 
+### `velaro logs insights <subcommand>` (Velaro staff only)
+
+Grouped views over Velaro Logger data (same data as the Admin UI "Insights" tab). All subcommands accept `--last 6h`, `--platform v10|v20|admin`, `--environment Production|Staging`, `--site <id>`, `--env staging|prod` and `--json`.
+
+```bash
+velaro logs insights groups --last 6h --platform v20     # error groups, most frequent first
+velaro logs insights new                                 # groups not seen in the previous 7 days
+velaro logs insights regression --at 2h                  # before vs after a deploy
+velaro logs insights trace <correlationId>               # cross-platform timeline
+velaro logs insights trace --site 1032 --last 30m
+velaro logs insights anomalies --hours 48
+velaro logs insights sites                               # per-site scorecard
+velaro logs insights mutes
+velaro logs insights mute <fingerprint> --reason "known outage" --expires 7d
+velaro logs insights unmute <fingerprint>
+velaro logs insights sensitive                           # emails/tokens/cards in logs
+velaro logs insights brief <fingerprint>                 # AI markdown brief
+```
+
 ### `velaro status`
 Check that the Velaro API is reachable.
 

package/bin/velaro.js

@@ -35,6 +35,7 @@ import { updateCommand }     from '../lib/commands/update.js';
 import { agentCommand }      from '../lib/commands/agent.js';
 import { linkedIdentityCommand } from '../lib/commands/linked-identity.js';
 import { notificationsCommand } from '../lib/commands/notifications.js';
+import { signatureCommand } from '../lib/commands/signature.js';
 import { articleCommand }    from '../lib/commands/article.js';
 import { sharepointCommand } from '../lib/commands/sharepoint.js';
 import { calendlyCommand }   from '../lib/commands/calendly.js';
@@ -67,6 +68,7 @@ import { triageCommand }      from '../lib/commands/triage.js';
 import { automationDraftCommand } from '../lib/commands/automation-draft.js';
 import { magentoCommand }       from '../lib/commands/magento.js';
 import { sapCommand }           from '../lib/commands/sap.js';
+import { salesforceCommand }    from '../lib/commands/salesforce.js';
 import { actionsCommand }       from '../lib/commands/actions.js';
 import { mondayCommand }        from '../lib/commands/monday.js';
 import { notionCommand }        from '../lib/commands/notion.js';
@@ -80,6 +82,7 @@ import { zoomPhoneCommand }     from '../lib/commands/zoom-phone.js';
 import { teamsCommand }         from '../lib/commands/teams.js';
 import { slackCommand }         from '../lib/commands/slack.js';
 import { webflowCommand }        from '../lib/commands/webflow.js';
+import { shopifyCommand }        from '../lib/commands/shopify.js';
 import { netsuiteCommand }      from '../lib/commands/netsuite.js';
 import { woocommerceCommand }  from '../lib/commands/woocommerce.js';
 import { squarespaceCommand }  from '../lib/commands/squarespace.js';
@@ -89,6 +92,7 @@ import { migrationStatusCommand } from '../lib/commands/migration-status.js';
 import { complianceCommand }      from '../lib/commands/compliance.js';
 import { billingContactsCommand } from '../lib/commands/billing-contacts.js';
 import { billingSubscriptionCommand } from '../lib/commands/billing-subscription.js';
+import { billingAutomationCommand } from '../lib/commands/billing-automation.js';
 import { orderFormCommand } from '../lib/commands/order-form.js';
 import { billingEmailPreferenceCommand } from '../lib/commands/billing-email-preference.js';
 import { billingCommand }         from '../lib/commands/billing.js';
@@ -110,6 +114,8 @@ import { emailInboxCommand }        from '../lib/commands/email-inbox.js';
 import { callbackCommand }          from '../lib/commands/callback.js';
 import { caseCommand }              from '../lib/commands/case.js';
 import { pickupCommand }            from '../lib/commands/pickup.js';
+import { applePayCommand }         from '../lib/commands/apple-pay.js';
+import { siteBuilderCommand }        from '../lib/commands/site-builder.js';
 import { paymentRecoveryCommand }   from '../lib/commands/payment-recovery.js';
 import { recruitingCommand }        from '../lib/commands/recruiting.js';
 import { surveyCommand }            from '../lib/commands/survey.js';
@@ -172,6 +178,7 @@ await yargs(hideBin(process.argv))
   .command(agentCommand)
   .command(linkedIdentityCommand)
   .command(notificationsCommand)
+  .command(signatureCommand)
   .command(articleCommand)
   .command(sharepointCommand)
   .command(calendlyCommand)
@@ -206,6 +213,7 @@ await yargs(hideBin(process.argv))
   .command(automationDraftCommand)
   .command(magentoCommand)
   .command(sapCommand)
+  .command(salesforceCommand)
   .command(actionsCommand)
   .command(mondayCommand)
   .command(notionCommand)
@@ -219,6 +227,7 @@ await yargs(hideBin(process.argv))
   .command(teamsCommand)
   .command(slackCommand)
   .command(webflowCommand)
+  .command(shopifyCommand)
   .command(netsuiteCommand)
   .command(woocommerceCommand)
   .command(squarespaceCommand)
@@ -228,6 +237,7 @@ await yargs(hideBin(process.argv))
   .command(complianceCommand)
   .command(billingContactsCommand)
   .command(billingSubscriptionCommand)
+  .command(billingAutomationCommand)
   .command(orderFormCommand)
   .command(billingEmailPreferenceCommand)
   .command(billingCommand)
@@ -249,6 +259,8 @@ await yargs(hideBin(process.argv))
   .command(callbackCommand)
   .command(caseCommand)
   .command(pickupCommand)
+  .command(applePayCommand)
+  .command(siteBuilderCommand)
   .command(paymentRecoveryCommand)
   .command(recruitingCommand)
   .command(surveyCommand)

package/lib/api.js

@@ -60,7 +60,7 @@ export const post = (path, body) => request('POST',   path, body);
 export const put  = (path, body) => request('PUT',    path, body);
 export const del  = (path)       => request('DELETE', path);
 
-export async function messagingRequest(method, path, body, envOverride, extraHeaders = {}) {
+export async function messagingRequest(method, path, body, envOverride, extraHeaders = {}, opts = {}) {
   const creds = await getCredentials(envOverride);
   const res = await fetch(joinUrl(creds.messagingApiBase, path), {
     method,
@@ -75,6 +75,7 @@ export async function messagingRequest(method, path, body, envOverride, extraHea
       ...extraHeaders,
     },
     body: body !== undefined ? JSON.stringify(body) : undefined,
+    ...(opts.timeoutMs ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
   });
   if (!res.ok) {
     let msg = `${method} ${path} → ${res.status}`;

package/lib/apple-pay.js

@@ -0,0 +1,32 @@
+// Pure helpers for `velaro apple-pay ...` (no I/O except the optional logo file read, so they are unit-testable).
+// Backend: velaro-messaging ApplePayConfigsController (GET/POST ApplePayConfig, PUT ApplePayConfig/{id}).
+// Only display + test-mode fields are exposed here. The merchant id / certificate decide the CHARGE and stay behind
+// secure Velaro admin provisioning; this CLI deliberately cannot set them.
+
+import fs from 'node:fs';
+
+export const LOGO_MAX_BYTES = 500 * 1024;
+
+/** Returns the base64 of a PNG/JPEG file under 500 KB, or throws with a plain-language reason. */
+export function readLogoBase64(filePath) {
+  const bytes = fs.readFileSync(filePath);
+  if (bytes.length > LOGO_MAX_BYTES) throw new Error('--logo must be under 500 KB.');
+  const png = bytes.length > 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47;
+  const jpg = bytes.length > 8 && bytes[0] === 0xff && bytes[1] === 0xd8;
+  if (!png && !jpg) throw new Error('--logo must be a PNG or JPEG image.');
+  return bytes.toString('base64');
+}
+
+/**
+ * Builds the PUT/POST body from CLI args. Apply-if-present: only fields the operator named are sent.
+ * argv: { name, testMode, logo, clearLogo }. Returns {} when nothing was named.
+ */
+export function buildApplePayUpdate(argv, readLogo = readLogoBase64) {
+  if (argv.logo && argv.clearLogo) throw new Error('Use either --logo or --clear-logo, not both.');
+  const body = {};
+  if (argv.name !== undefined) body.merchantDisplayName = String(argv.name);
+  if (argv.testMode !== undefined) body.isTestMode = !!argv.testMode;
+  if (argv.logo) body.bubbleLogoBase64 = readLogo(argv.logo);
+  else if (argv.clearLogo) body.bubbleLogoBase64 = '';
+  return body;
+}

package/lib/apple-pay.test.js

@@ -0,0 +1,32 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { buildApplePayUpdate, readLogoBase64, LOGO_MAX_BYTES } from './apple-pay.js';
+
+function tmpFile(bytes) {
+  const f = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'applepay-')), 'logo.bin');
+  fs.writeFileSync(f, bytes);
+  return f;
+}
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3]);
+
+test('only named fields are sent, with the exact JSON names the controller binds', () => {
+  assert.deepEqual(buildApplePayUpdate({ name: 'Aurora Guitars' }), { merchantDisplayName: 'Aurora Guitars' });
+  assert.deepEqual(buildApplePayUpdate({ testMode: true }), { isTestMode: true });
+  assert.deepEqual(buildApplePayUpdate({ testMode: false }), { isTestMode: false });
+  assert.deepEqual(buildApplePayUpdate({}), {});
+});
+
+test('clear-logo sends an empty string; logo and clear-logo together are rejected', () => {
+  assert.deepEqual(buildApplePayUpdate({ clearLogo: true }), { bubbleLogoBase64: '' });
+  assert.throws(() => buildApplePayUpdate({ logo: 'x.png', clearLogo: true }), /either --logo or --clear-logo/);
+});
+
+test('logo is read as base64 and validated as PNG/JPEG under 500 KB', () => {
+  assert.equal(readLogoBase64(tmpFile(PNG)), PNG.toString('base64'));
+  assert.equal(buildApplePayUpdate({ logo: tmpFile(PNG) }).bubbleLogoBase64, PNG.toString('base64'));
+  assert.throws(() => readLogoBase64(tmpFile(Buffer.from('GIF89a-not-allowed'))), /PNG or JPEG/);
+  assert.throws(() => readLogoBase64(tmpFile(Buffer.concat([PNG, Buffer.alloc(LOGO_MAX_BYTES)]))), /under 500 KB/);
+});

package/lib/avatar-switch.js

@@ -0,0 +1,42 @@
+// Pure helpers for `velaro avatar workflow-switch | bulk-switch`.
+// The on / off / rules switch per workflow or team lives in velaro-messaging (VelaroAvatarController):
+//   PUT /avatar/workflows/{id}/enabled   body {"mode":"on"|"off"|"rules"}
+//   PUT /avatar/overrides/enabled        body {"mode":..., "workflowIds":[], "groupIds":[]} (max 500 rows)
+// "rules" clears the switch so the site rules decide. Kept dependency-free so it is unit-testable.
+
+export const SWITCH_VALUES = ['on', 'off', 'rules'];
+const MAX_BULK_ROWS = 500;
+
+/** Returns the normalized mode or throws. Mirrors AvatarOverrideEnabledMode.TryParse on the server. */
+export function parseSwitchValue(raw) {
+  const v = String(raw ?? '').trim().toLowerCase();
+  if (!SWITCH_VALUES.includes(v)) throw new Error(`The value must be one of: ${SWITCH_VALUES.join(', ')}`);
+  return v;
+}
+
+/** Parses "12,13, 14" into positive whole ids, de-duplicated. Throws on anything else. */
+export function parseIdList(raw, label = '--ids') {
+  const parts = String(raw ?? '').split(',').map(s => s.trim()).filter(s => s !== '');
+  if (parts.length === 0) throw new Error(`${label} needs at least one id, e.g. ${label} 12,13`);
+  const ids = parts.map(p => {
+    const n = Number(p);
+    if (!/^\d+$/.test(p) || !Number.isInteger(n) || n <= 0) throw new Error(`${label} must be positive whole numbers; got "${p}"`);
+    return n;
+  });
+  return [...new Set(ids)];
+}
+
+/** Body for PUT /avatar/workflows/{id}/enabled. */
+export function workflowSwitchBody(raw) {
+  return { mode: parseSwitchValue(raw) };
+}
+
+/** Body for PUT /avatar/overrides/enabled. Enforces the server's selection rules up front so a bad call fails before the network. */
+export function bulkSwitchBody({ ids, groups, value }) {
+  const mode = parseSwitchValue(value);
+  const workflowIds = ids === undefined ? [] : parseIdList(ids, '--ids');
+  const groupIds = groups === undefined ? [] : parseIdList(groups, '--groups');
+  if (workflowIds.length + groupIds.length === 0) throw new Error('Pass --ids <workflowIds> and/or --groups <teamIds>');
+  if (workflowIds.length + groupIds.length > MAX_BULK_ROWS) throw new Error(`Too many rows in one call (max ${MAX_BULK_ROWS})`);
+  return { mode, workflowIds, groupIds };
+}

package/lib/avatar-switch.test.js

@@ -0,0 +1,49 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { parseSwitchValue, parseIdList, workflowSwitchBody, bulkSwitchBody } from './avatar-switch.js';
+
+test('switch value accepts on, off, rules and normalizes case; anything else is rejected', () => {
+  assert.equal(parseSwitchValue('ON'), 'on');
+  assert.equal(parseSwitchValue(' rules '), 'rules');
+  assert.throws(() => parseSwitchValue('sometimes'), /one of: on, off, rules/);
+  assert.throws(() => parseSwitchValue(''), /one of/);
+  assert.throws(() => parseSwitchValue(undefined), /one of/);
+});
+
+test('id list parses comma lists, de-duplicates, and rejects non-positive or non-integer ids', () => {
+  assert.deepEqual(parseIdList('12, 13,12'), [12, 13]);
+  assert.throws(() => parseIdList(''), /at least one id/);
+  assert.throws(() => parseIdList('12,abc'), /positive whole numbers/);
+  assert.throws(() => parseIdList('0'), /positive whole numbers/);
+  assert.throws(() => parseIdList('1.5'), /positive whole numbers/);
+  assert.throws(() => parseIdList('-3'), /positive whole numbers/);
+});
+
+test('workflow switch sends exactly {mode}', () => {
+  assert.deepEqual(workflowSwitchBody('off'), { mode: 'off' });
+  assert.deepEqual(workflowSwitchBody('rules'), { mode: 'rules' });
+  assert.throws(() => workflowSwitchBody('maybe'), /one of/);
+});
+
+test('bulk switch builds the request shape and enforces selection rules', () => {
+  assert.deepEqual(bulkSwitchBody({ ids: '5,6', value: 'on' }), { mode: 'on', workflowIds: [5, 6], groupIds: [] });
+  assert.deepEqual(bulkSwitchBody({ groups: '9', value: 'rules' }), { mode: 'rules', workflowIds: [], groupIds: [9] });
+  assert.throws(() => bulkSwitchBody({ value: 'on' }), /Pass --ids/);
+  assert.throws(() => bulkSwitchBody({ ids: '5', value: 'bogus' }), /one of/);
+  const many = Array.from({ length: 501 }, (_, i) => i + 1).join(',');
+  assert.throws(() => bulkSwitchBody({ ids: many, value: 'off' }), /max 500/);
+});
+
+test('avatar command registers workflow-switch and bulk-switch and the MCP server exposes matching tools', () => {
+  const src = fs.readFileSync(new URL('./commands/avatar.js', import.meta.url), 'utf8');
+  assert.match(src, /command:\s+'workflow-switch <workflowId> <value>'/);
+  assert.match(src, /command:\s+'bulk-switch'/);
+  assert.match(src, /\/avatar\/workflows\/\$\{id\}\/enabled/);
+  assert.match(src, /\/avatar\/overrides\/enabled/);
+  const mcp = fs.readFileSync(new URL('../../mcp/server.js', import.meta.url), 'utf8');
+  assert.match(mcp, /name: 'avatar_set_workflow_switch'/);
+  assert.match(mcp, /name: 'avatar_bulk_set_switch'/);
+  assert.match(mcp, /`\/avatar\/workflows\/\$\{id\}\/enabled`/);
+  assert.match(mcp, /'\/avatar\/overrides\/enabled'/);
+});

package/lib/build-info.js

@@ -0,0 +1,28 @@
+// Real running-build info from each service's /api/health `build` block.
+// Admin reports {sha, shortSha, builtAt}; messaging reports {commitId, shortCommitId, builtAt}.
+export function parseBuild(health) {
+  const b = health?.build;
+  if (!b) return null;
+  const full = b.commitId ?? b.sha ?? null;
+  const short = b.shortCommitId ?? b.shortSha ?? (full ? String(full).slice(0, 7) : null);
+  if (!short && !b.builtAt) return null;
+  return { short: short ?? '?', builtAt: b.builtAt ?? null };
+}
+
+export function ptLabel(dateStr) {
+  const d = new Date(dateStr);
+  const s = d.toLocaleString('en-US', {
+    timeZone: 'America/Los_Angeles', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', hour12: false,
+  });
+  const tz = d.toLocaleString('en-US', { timeZone: 'America/Los_Angeles', timeZoneName: 'short' }).split(' ').pop();
+  return `${s.replace(',', '')} ${tz}`;
+}
+
+export function formatBuild(build, now = Date.now()) {
+  if (!build) return 'build unknown';
+  if (!build.builtAt) return `commit ${build.short} built unknown`;
+  const mins = Math.max(0, Math.round((now - new Date(build.builtAt).getTime()) / 60000));
+  const age = mins < 2 ? 'just now' : mins < 60 ? `${mins}m ago` : mins < 1440 ? `${Math.round(mins / 60)}h ago` : `${Math.round(mins / 1440)}d ago`;
+  return `commit ${build.short} built ${ptLabel(build.builtAt)} (${age})`;
+}

package/lib/build-info.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseBuild, formatBuild } from './build-info.js';
+
+test('parses messaging health build (commitId/shortCommitId)', () => {
+  const b = parseBuild({ build: { commitId: '5398fce8069e98de38edacb74db8c77155ca70a5', shortCommitId: '5398fce', builtAt: '2026-10-12T05:28:25Z' } });
+  assert.deepEqual(b, { short: '5398fce', builtAt: '2026-10-12T05:28:25Z' });
+});
+
+test('parses admin health build (sha/shortSha)', () => {
+  const b = parseBuild({ build: { sha: 'a908399d25ee3b0d35bcfca2a499ae6508d03c88', shortSha: 'a908399', builtAt: '2026-10-12T01:22:28Z' } });
+  assert.equal(b.short, 'a908399');
+});
+
+test('derives short from full sha; null without build block', () => {
+  assert.equal(parseBuild({ build: { sha: 'abcdef1234567', builtAt: 'x' } }).short, 'abcdef1');
+  assert.equal(parseBuild({}), null);
+});
+
+test('formats commit, PT time and age', () => {
+  const now = new Date('2026-10-12T05:50:25Z').getTime();
+  const s = formatBuild({ short: '5398fce', builtAt: '2026-10-12T05:28:25Z' }, now);
+  assert.match(s, /^commit 5398fce built 10\/11 22:28 PDT \(22m ago\)$/);
+});

package/lib/commands/apple-pay.js

@@ -0,0 +1,73 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+import { buildApplePayUpdate } from '../apple-pay.js';
+
+// ── velaro apple-pay ───────────────────────────────────────────────────────────
+// CLI surface for the per-site Apple Pay display settings (business name, payment bubble logo, test mode).
+// siteId is applied server-side from the vmsg-siteId header -- never a CLI arg.
+//
+// Backend contract: server/Velaro.Messaging/Controllers/Channels/ApplePayConfigsController.cs
+//   GET  ApplePayConfig        -> dto (id 0 when the site has no row yet)
+//   POST ApplePayConfig        -> create (409 if one already exists)
+//   PUT  ApplePayConfig/{id}   -> apply-if-present update
+
+const BOLD = '\x1b[1m';
+const DIM  = '\x1b[2m';
+const GRN  = '\x1b[32m';
+const RST  = '\x1b[0m';
+
+async function configGetHandler() {
+  const c = await messagingGet('/ApplePayConfig');
+  console.log(`\n${BOLD}Apple Pay config${RST}  (id ${c.id || 'none yet'})`);
+  console.log(`  Enabled:               ${c.isEnabled ? `${GRN}yes${RST}` : 'no'}`);
+  console.log(`  Test mode (sandbox):   ${c.isTestMode ? 'on -- no real money moves' : 'off'}`);
+  console.log(`  Business name shown:   ${c.merchantDisplayName ?? `${DIM}(default)${RST}`}`);
+  console.log(`  Bubble logo:           ${c.hasBubbleLogo ? 'custom' : `${DIM}(default image)${RST}`}`);
+  console.log(`  Merchant:              ${c.usingPlatformDefault ? `Velaro platform (${c.platformMerchantIdentifier || 'default'})` : c.merchantIdentifier}`);
+  console.log('');
+}
+
+async function configSetHandler(argv) {
+  const body = buildApplePayUpdate(argv);
+  if (Object.keys(body).length === 0) {
+    throw new Error('Nothing to set. Pass --name, --test-mode, --logo <file> or --clear-logo.');
+  }
+  const existing = await messagingGet('/ApplePayConfig');
+  const config = existing && existing.id > 0
+    ? await messagingPut(`/ApplePayConfig/${existing.id}`, body)
+    : await messagingPost('/ApplePayConfig', body);
+  console.log(`\n${GRN}✓${RST} Apple Pay config ${existing && existing.id > 0 ? 'updated' : 'created'} (id ${config.id}).\n`);
+}
+
+const configCommand = {
+  command:  'config <subcommand>',
+  describe: 'Get or set this site\'s Apple Pay display settings and test mode',
+  builder:  (y) => y
+    .command({
+      command:  'get',
+      describe: 'Show this site\'s Apple Pay config',
+      handler:  runCommand(configGetHandler),
+    })
+    .command({
+      command:  'set',
+      describe: 'Create or update display settings (apply-if-present -- omit a flag to leave it unchanged). Display only: never changes the charge.',
+      builder:  (y2) => y2
+        .option('name',       { describe: 'Business name shown on the Apple Pay sheet (pass "" to clear)', type: 'string' })
+        .option('test-mode',  { describe: 'Sandbox mode: Velaro Stripe test account, no real money, real Wallet cards decline', type: 'boolean' })
+        .option('logo',       { describe: 'Path to a PNG/JPEG (under 500 KB) for the payment bubble', type: 'string' })
+        .option('clear-logo', { describe: 'Remove the custom logo and use the default image', type: 'boolean' }),
+      handler: runCommand(configSetHandler),
+    })
+    .demandCommand(1, 'Specify a config subcommand: get | set'),
+  handler: () => {},
+};
+
+export const applePayCommand = {
+  command:  'apple-pay <subcommand>',
+  describe: 'Apple Pay (Apple Messages for Business) -- display settings and test mode',
+  builder:  (y) => y
+    .command(configCommand)
+    .demandCommand(1, 'Specify a subcommand: config')
+    .strict(),
+  handler: () => {},
+};

package/lib/commands/avatar.js

@@ -1,6 +1,7 @@
 import { request, messagingGet, messagingPut, messagingDel } from '../api.js';
 import { overrideBody, scopePath } from '../avatar-override.js';
 import { applyMotionArgs } from '../avatar-motion.js';
+import { SWITCH_VALUES, workflowSwitchBody, bulkSwitchBody } from '../avatar-switch.js';
 import { runCommand } from '../run.js';
 
 // ── velaro avatar ─────────────────────────────────────────────────────────────
@@ -28,7 +29,9 @@ export const avatarCommand = {
         console.log(`\nSite ${argv.site}: AI Video Avatar ${data.enabled ? 'ENABLED ✓' : 'configured but DISABLED'}`);
         console.log(`  Provider:      ${data.providerSlug}`);
         console.log(`  Avatar ID:     ${data.avatarId || '(provider default)'}`);
+        console.log(`  Face/provider: ${data.avatarIdByProvider && Object.keys(data.avatarIdByProvider).length ? JSON.stringify(data.avatarIdByProvider) : '(none saved)'} (read-only)`);
         console.log(`  Voice ID:      ${data.voiceId || '(site default)'}`);
+        console.log(`  Keep on agent join: ${data.enabledOnAgentTransfer ? 'yes' : 'no'}`);
         console.log(`  Enabled:       ${data.enabled ? 'yes' : 'no'}`);
         console.log(`  "Call me":     ${data.showCallMeOption ? 'yes' : 'no'}`);
         console.log(`  Callback window: ${data.callbackConfirmWindowMinutes} min`);
@@ -37,7 +40,32 @@ export const avatarCommand = {
         console.log(`  Size:          ${data.sizePx}px`);
         console.log(`  Body motion:   ${data.motionLevel || '(default: natural)'} @ ${data.motionIntensityPercent ?? 100}%`);
         console.log(`  Max minutes/mo:   ${data.maxAvatarMinutesPerMonth ?? '(plan default)'}`);
-        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars ?? '(plan default)'}\n`);
+        console.log(`  Max TTS chars/mo: ${data.maxAvatarTtsChars ?? '(plan default)'}`);
+        try {
+          const ent = await request('GET', `/Entitlements/${argv.site}`);
+          console.log(`  HeyGen entitled:  ${ent?.features?.EnableAvatarHeyGen ? 'yes' : 'no'}\n`);
+        } catch (e) { console.log(`  HeyGen entitled:  unknown (${e.message})\n`); }
+      }),
+    })
+    .command({
+      command:  'heygen',
+      describe: 'Grant or revoke the HeyGen provider entitlement (EnableAvatarHeyGen) for a site',
+      builder:  y => y
+        .option('site',    { type: 'number', demandOption: true, describe: 'Site ID' })
+        .option('enabled', { type: 'boolean', demandOption: true, describe: 'true = grant, false = revoke' }),
+      handler:  runCommand(async argv => {
+        await request('POST', `/Entitlements/${argv.site}/override`, { featureKey: 'EnableAvatarHeyGen', value: argv.enabled, reason: 'velaro avatar heygen' });
+        const ent = await request('GET', `/Entitlements/${argv.site}`);
+        console.log(`\n✓ Site ${argv.site}: EnableAvatarHeyGen=${ent?.features?.EnableAvatarHeyGen ? 'true' : 'false'}\n`);
+      }),
+    })
+    .command({
+      command:  'session-readiness',
+      describe: 'Staff diagnostic: why an avatar session will or will not start for a site (plan, config, key, billing, concurrency). Read-only, no provider call.',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const data = await messagingGet(`/avatar/diagnostics/session-readiness?siteId=${argv.site}`);
+        console.log(JSON.stringify(data, null, 2));
       }),
     })
     .command({
@@ -49,6 +77,7 @@ export const avatarCommand = {
         .option('bot',      { type: 'string', describe: 'Reserved for a future per-bot override (not yet implemented on this endpoint)' })
         .option('avatar-id',{ type: 'string', describe: 'Provider-specific avatar/face ID. Omit for provider default.' })
         .option('voice',    { type: 'string', describe: 'ElevenLabs voice ID override' })
+        .option('keep-on-agent-join', { type: 'boolean', describe: 'Keep the avatar running after a human agent joins. Omit on a re-run to leave it untouched.' })
         .option('call-me',  { type: 'boolean', describe: 'Show the "Call me instead" option. Omit on a re-run to leave it untouched.' })
         .option('display-name', { type: 'string', describe: 'Visitor-facing avatar name on the badge (e.g. Moshky). Empty string resets to "AI".' })
         .option('show-badge',   { type: 'boolean', describe: 'Show the name badge over the avatar video.' })
@@ -66,6 +95,7 @@ export const avatarCommand = {
         body.providerSlug = argv.provider ?? 'velaro';
         if (argv['avatar-id'] !== undefined) body.avatarId = argv['avatar-id'];
         if (argv.voice !== undefined) body.voiceId = argv.voice;
+        if (argv['keep-on-agent-join'] !== undefined) body.enabledOnAgentTransfer = argv['keep-on-agent-join'];
         if (argv['call-me'] !== undefined) body.showCallMeOption = argv['call-me'];
         if (argv['display-name'] !== undefined) body.displayName = argv['display-name'];
         if (argv['show-badge'] !== undefined) body.showBadge = argv['show-badge'];
@@ -163,5 +193,33 @@ export const avatarCommand = {
 `);
       }),
     })
-    .demandCommand(1, 'Specify a subcommand: get | enable | disable | set | override | effective | reset'),
+    .command({
+      command:  'workflow-switch <workflowId> <value>',
+      describe: 'Switch the avatar on, off, or back to the site rules (rules) for ONE workflow of your site',
+      builder:  y => y
+        .positional('workflowId', { type: 'number', describe: 'Workflow id' })
+        .positional('value',      { type: 'string', choices: SWITCH_VALUES, describe: 'on | off | rules (rules = the site rules decide)' }),
+      handler:  runCommand(async argv => {
+        const id = Number(argv.workflowId);
+        if (!Number.isInteger(id) || id <= 0) throw new Error('The workflow id must be a positive whole number');
+        const data = await messagingPut(`/avatar/workflows/${id}/enabled`, workflowSwitchBody(argv.value));
+        if (!data?.success) throw new Error(data?.error || 'Switch failed');
+        console.log(`\n✓ Workflow ${id} avatar switch: ${data.mode} (${data.changed ? 'changed' : 'already set'})\n`);
+      }),
+    })
+    .command({
+      command:  'bulk-switch',
+      describe: 'Set the avatar switch for many workflows and/or teams of your site in one call (max 500)',
+      builder:  y => y
+        .option('ids',    { type: 'string', describe: 'Comma-separated workflow ids, e.g. 12,13,14' })
+        .option('groups', { type: 'string', describe: 'Comma-separated team (group) ids' })
+        .option('value',  { type: 'string', choices: SWITCH_VALUES, demandOption: true, describe: 'on | off | rules' }),
+      handler:  runCommand(async argv => {
+        const body = bulkSwitchBody({ ids: argv.ids, groups: argv.groups, value: argv.value });
+        const data = await messagingPut('/avatar/overrides/enabled', body);
+        if (!data?.success) throw new Error(data?.error || 'Bulk switch failed');
+        console.log(`\n✓ Bulk avatar switch ${data.mode}: ${data.changed} of ${data.requested} rows changed\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: get | enable | disable | set | override | effective | reset | workflow-switch | bulk-switch'),
 };