@velaro/cli 1.4.53 → 1.4.55

package/lib/commands/contact-list.js

@@ -23,6 +23,12 @@ import { runCommand } from '../run.js';
 //   GET    ContactSegments/{id}/Members                  -> ContactListController.GetSegmentMembers
 //   POST   ContactLists/crm-preview     { filters }      -> ContactListController.CrmPreview
 //   POST   ContactLists/import-from-crm { filters, newListName? | listId? } -> ContactListController.ImportFromCrm
+//
+// `import-csv` below is NOT a wrapper for the browser file-upload wizard
+// (ContactListController.StartImport, still intentionally absent here) --
+// it is this CLI parsing a local CSV and looping the plain AddMember POST
+// above, once per row. No new backend endpoint, no IFormFile, fully
+// scriptable.
 
 function fmtRow(label, value) {
   console.log(`  ${label.padEnd(24)}${value ?? '—'}`);
@@ -86,6 +92,78 @@ async function addMemberHandler(argv) {
   console.log(result.isNew ? `\n✅ Added ${argv.email} to list #${argv.id}.\n` : `\n${argv.email} was already a member of list #${argv.id}.\n`);
 }
 
+// Minimal RFC4180-ish CSV line parser -- handles quoted fields (with embedded
+// commas/newlines via doubled quotes) without pulling in a new dependency for
+// a CLI tool that otherwise has none. Not a full CSV spec implementation, but
+// covers what a customer exporting from Excel/Sheets/another CRM produces.
+function parseCsv(text) {
+  const rows = [];
+  let row = [], field = '', inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; }
+        else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ',') { row.push(field); field = ''; }
+    else if (c === '\r') { /* skip, \n handles the row break */ }
+    else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
+    else field += c;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter(r => r.length > 1 || (r.length === 1 && r[0].trim() !== ''));
+}
+
+// POST ContactLists/{listId}/Members, once per CSV row, drives the existing
+// single-member API (ContactListController.AddMember) from a file instead of
+// one CLI invocation per person. No new backend endpoint needed.
+// mcp-cli-exempt does NOT apply here (unlike the browser upload wizard) since
+// this never touches a raw file-upload/IFormFile path, it's plain scriptable
+// JSON POSTs, just looped.
+async function importCsvHandler(argv) {
+  const { readFileSync } = await import('fs');
+  const raw = readFileSync(argv.file, 'utf8');
+  const rows = parseCsv(raw);
+  if (!rows.length) { console.log('\nNo rows found in CSV.\n'); return; }
+
+  const header = rows[0].map(h => h.trim().toLowerCase());
+  const emailIdx = header.indexOf('email');
+  if (emailIdx === -1) throw new Error('CSV must have an "email" column in its header row.');
+  const nameIdx  = header.indexOf('name');
+  const phoneIdx = header.indexOf('phone');
+  const tagsIdx  = header.indexOf('tags');
+
+  const dataRows = rows.slice(1).filter(r => (r[emailIdx] || '').trim());
+  console.log(`\nImporting ${dataRows.length} row(s) from ${argv.file} into list #${argv.id}${argv.dryRun ? ' (dry run)' : ''}...\n`);
+
+  let added = 0, existing = 0, failed = 0;
+  const concurrency = Math.max(1, Math.min(argv.concurrency || 5, 20));
+  let cursor = 0;
+  async function worker() {
+    while (cursor < dataRows.length) {
+      const r = dataRows[cursor++];
+      const email = (r[emailIdx] || '').trim();
+      const name  = nameIdx  >= 0 ? (r[nameIdx]  || '').trim() : undefined;
+      const phone = phoneIdx >= 0 ? (r[phoneIdx] || '').trim() : undefined;
+      const tags  = tagsIdx  >= 0 ? (r[tagsIdx]  || '').trim() : undefined;
+      if (argv.dryRun) { console.log(`  would add: ${email}`); continue; }
+      try {
+        const result = await request('POST', `ContactLists/${argv.id}/Members`, { email, name, phone, tags });
+        if (result.isNew) added++; else existing++;
+      } catch (e) {
+        failed++;
+        console.log(`  FAILED ${email}: ${e.message}`);
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, worker));
+
+  if (argv.dryRun) { console.log(`\nDry run complete. ${dataRows.length} row(s) would be imported.\n`); return; }
+  console.log(`\n✅ Import complete: ${added} added, ${existing} already members, ${failed} failed.\n`);
+}
+
 // DELETE ContactLists/{listId}/Members/{memberId} -> ContactListController.RemoveMember
 async function removeMemberHandler(argv) {
   await request('DELETE', `ContactLists/${argv.id}/Members/${argv.memberId}`);
@@ -244,6 +322,15 @@ export const contactListCommand = {
         .option('tags',  { type: 'string' }),
       handler: runCommand(addMemberHandler),
     })
+    .command({
+      command:  'import-csv <id> <file>',
+      describe: 'Bulk-add members to a contact list from a CSV file (header row required, "email" column mandatory; optional "name", "phone", "tags")',
+      builder:  (y2) => y2.positional('id', { type: 'number' })
+        .positional('file', { type: 'string' })
+        .option('dryRun',      { type: 'boolean', default: false, describe: 'Preview rows without adding them' })
+        .option('concurrency', { type: 'number',  default: 5, describe: 'Parallel add-member requests (max 20)' }),
+      handler: runCommand(importCsvHandler),
+    })
     .command({
       command:  'remove-member <id> <memberId>',
       describe: 'Remove a member from a contact list',
@@ -292,6 +379,6 @@ export const contactListCommand = {
         .option('listId',      { type: 'number', describe: 'Import into an existing list instead of creating one' }),
       handler: runCommand(importFromCrmHandler),
     })
-    .demandCommand(1, 'Specify a contact-list subcommand: list | create | update | delete | members | add-member | remove-member | export | resync | auto-resync | quota | segment-members | crm-preview | import-from-crm'),
+    .demandCommand(1, 'Specify a contact-list subcommand: list | create | update | delete | members | add-member | import-csv | remove-member | export | resync | auto-resync | quota | segment-members | crm-preview | import-from-crm'),
   handler: () => {},
 };

package/lib/commands/db.js

@@ -25,6 +25,9 @@ const DB_SECRETS = {
   kb: {
     staging: { vault: 'velaro-eastus-stg-kv', secret: 'KnowledgeBaseConnectionString-Staging' },
   },
+  messaging: {
+    prod: { vault: 'velaro-eastus-prd-kv', secret: 'MessagingReadOnlyConnectionString' },
+  },
 };
 
 async function getConnectionString(dbName, env, connectionStringFile) {

package/lib/commands/entitlement.js

@@ -114,6 +114,24 @@ async function reconcile(args) {
   }
 }
 
+async function setLock(args) {
+  if (!args.site) {
+    console.error('Usage: velaro entitlement set-lock --site 1032 --at 2026-01-01T00:00:00Z\n       velaro entitlement set-lock --site 1032 --unlock');
+    process.exit(1);
+  }
+  if (!args.at && !args.unlock) {
+    console.error('Pass --at <ISO 8601 timestamp> to lock, or --unlock to clear an existing lock.');
+    process.exit(1);
+  }
+  const lockedAt = args.unlock ? null : args.at;
+  const result = await request('PUT', `Entitlements/admin/lock/${args.site}`, { lockedAt });
+  if (lockedAt) {
+    console.log(`✅ Site ${args.site} entitlements locked to ${result.entitlementLockedAt} (plan ${result.planKey}).`);
+  } else {
+    console.log(`✅ Site ${args.site} entitlement lock cleared — resolves against the current plan version again.`);
+  }
+}
+
 async function listCutover() {
   const result = await request('GET', 'Entitlements/admin/cutover');
   console.log(`\nCutover flags: ${result.liveCount} live / ${result.total} total`);
@@ -167,10 +185,15 @@ export function entitlementCommand(yargs) {
       .option('until', { type: 'string', desc: 'ISO 8601 comp expiry date (omit for indefinite)' })
       .option('notes', { type: 'string', desc: 'Internal notes' })
     , a => compSite(a))
+    .command('set-lock', 'Lock a site\'s entitlement resolution to a point-in-time plan version, or clear an existing lock', y => y
+      .option('site',   { type: 'number',  demandOption: true, desc: 'Site ID' })
+      .option('at',     { type: 'string',  desc: 'ISO 8601 timestamp to lock entitlement resolution to' })
+      .option('unlock', { type: 'boolean', desc: 'Clear an existing lock (resolves against current plan version again)' })
+    , a => setLock(a))
     .command('list-cutover', 'List all feature keys and whether they are live (messaging reads admin) or not (Subscription.cs)', () => {}, () => listCutover())
     .command('set-cutover', 'Flip a feature key live (or roll it back). Live = messaging reads admin value within 45s. --rollback reverts to Subscription.cs.', y => y
       .option('key',      { type: 'string',  demandOption: true, desc: 'Feature key, e.g. EnableIvr' })
       .option('rollback', { type: 'boolean', desc: 'Pass to roll back this flag to Subscription.cs (default: go live)' })
     , a => setCutover(a))
-    .demandCommand(1, 'Specify a subcommand: get | list-features | set-override | remove-override | seed | seed-plans | backfill | reconcile | comp | list-cutover | set-cutover');
+    .demandCommand(1, 'Specify a subcommand: get | list-features | set-override | remove-override | seed | seed-plans | backfill | reconcile | comp | set-lock | list-cutover | set-cutover');
 }

package/lib/commands/login.js

@@ -11,15 +11,16 @@ export const loginCommand = {
         describe: 'Log in to the staging environment',
         type:     'boolean',
         default:  false,
-      })
-      .option('api', {
-        describe: 'Override the admin API base URL (advanced)',
-        type:     'string',
       }),
 
+  // Advanced API-base overrides go through VELARO_ADMIN_API_STAGING/VELARO_ADMIN_API_PROD env
+  // vars (read by ENVS in config.js) -- never a login flag. A flag-supplied override used to get
+  // persisted into the stored config and then silently clobbered on the next token refresh
+  // (refreshVelaroToken() always resolves against ENVS[env]), so login would report success
+  // against a custom URL while every later command quietly used the canonical one instead.
   handler: runCommand(async (argv) => {
-    const env = argv.staging || argv.api?.includes('staging') ? 'staging' : 'prod';
-    const adminApiBase = argv.api || ENVS[env].adminApiBase;
+    const env = argv.staging ? 'staging' : 'prod';
+    const adminApiBase = ENVS[env].adminApiBase;
 
     console.log(`Starting Velaro login (${env})...\n`);
 

package/lib/commands/logs.js

@@ -307,12 +307,13 @@ function parsePositiveIntFlag(flagName, rawValue, { max } = {}) {
 // it's pure log noise that pages no one. Mirrors the same guard in
 // client/src/pages/Messaging/Integrations/AlertRules.tsx (extended here to
 // also cover webhook, which that component's check omits).
-function hasAnyRecipient({ emails, sms, webhook, mobileUserIds }) {
+function hasAnyRecipient({ emails, sms, webhook, mobileUserIds, teams }) {
   return Boolean(
     (emails && String(emails).trim()) ||
     (sms && String(sms).trim()) ||
     (webhook && String(webhook).trim()) ||
-    (mobileUserIds && String(mobileUserIds).trim())
+    (mobileUserIds && String(mobileUserIds).trim()) ||
+    teams
   );
 }
 
@@ -327,6 +328,7 @@ function printAlertRule(r) {
   if (r.notifyEmails)        bits.push('email');
   if (r.notifyWebhookUrl)    bits.push('webhook');
   if (r.notifyMobileUserIds) bits.push('mobile push');
+  if (r.notifyTeams)         bits.push('Teams');
   bits.push(`cooldown ${r.minRefireMinutes}m`);
   console.log(`${DIM}[${r.id}]${RESET} ${r.name}  ${state}`);
   console.log(`    ${bits.join('  ')}`);
@@ -440,9 +442,9 @@ async function createAlertRule(argv) {
   const [thresholdCheck, windowCheck, cooldownCheck] = checks;
 
   // HIGH: a rule with zero notification channels fires into the void.
-  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, mobileUserIds: argv.mobileUserIds })
+  if (!hasAnyRecipient({ emails: argv.emails, sms: argv.sms, webhook: argv.webhook, mobileUserIds: argv.mobileUserIds, teams: argv.teams })
       && !argv.noRecipientsOk) {
-    console.error('No notification channel given (--emails, --sms, --webhook, or --mobile-user-ids) — this rule would fire but notify no one.');
+    console.error('No notification channel given (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — this rule would fire but notify no one.');
     console.error('If that\'s intentional (e.g. you only want it visible in Alert History), pass --no-recipients-ok to proceed anyway.');
     process.exit(1);
   }
@@ -459,6 +461,7 @@ async function createAlertRule(argv) {
     notifyPhoneNumbers:   argv.sms,
     notifyWebhookUrl:     argv.webhook,
     notifyMobileUserIds:  argv.mobileUserIds,
+    notifyTeams:          Boolean(argv.teams),
     enabled:              true,
   };
 
@@ -494,6 +497,103 @@ async function createAlertRule(argv) {
   console.log('');
 }
 
+async function updateAlertRule(argv) {
+  const creds   = await getCredentials();
+  await requireAdmin(creds);
+  const msgBase = await getMsgBase(argv);
+
+  if (!argv.id) {
+    console.error('Rule id is required. Example: velaro logs alerts update 42 --threshold 60');
+    process.exit(1);
+  }
+
+  // No single-rule GET endpoint (same limitation deleteAlertRule already works
+  // around) -- UpdateRule is a whole-object PUT, not a partial patch, so every
+  // field has to be re-sent or it gets wiped. Fetch the current rule from the
+  // list first and merge only the flags actually passed on top of it.
+  const listRes = await fetch(`${msgBase}/superadmin/log-alerts/rules`, {
+    headers: { Authorization: `Bearer ${creds.velaroToken}`, 'X-Internal-SiteId': String(creds.siteId) },
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!listRes.ok) {
+    console.error(`HTTP ${listRes.status}: ${await listRes.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  const rules  = await listRes.json().catch(() => []);
+  const target = Array.isArray(rules) ? rules.find(r => String(r.id) === String(argv.id)) : null;
+  if (!target) {
+    console.error(`No rule with id ${argv.id} found. Run 'velaro logs alerts list' to see current ids.`);
+    process.exit(1);
+  }
+
+  const checks = [
+    parsePositiveIntFlag('threshold',        argv.threshold),
+    parsePositiveIntFlag('window-minutes',   argv.windowMinutes, { max: 1440 }),
+    parsePositiveIntFlag('cooldown-minutes', argv.cooldownMinutes),
+  ];
+  const failed = checks.find(c => !c.ok);
+  if (failed) {
+    console.error(failed.error);
+    process.exit(1);
+  }
+  const [thresholdCheck, windowCheck, cooldownCheck] = checks;
+
+  const body = {
+    ...target,
+    name:                argv.name             ?? target.name,
+    queryText:           argv.query             ?? target.queryText,
+    level:               argv.level             ? argv.level.toUpperCase() : target.level,
+    integration:         argv.integration       ?? target.integration,
+    windowMinutes:       windowCheck.value      ?? target.windowMinutes,
+    thresholdCount:      thresholdCheck.value   ?? target.thresholdCount,
+    minRefireMinutes:    cooldownCheck.value    ?? target.minRefireMinutes,
+    notifyEmails:        argv.emails            ?? target.notifyEmails,
+    notifyPhoneNumbers:  argv.sms               ?? target.notifyPhoneNumbers,
+    notifyWebhookUrl:    argv.webhook           ?? target.notifyWebhookUrl,
+    notifyMobileUserIds: argv.mobileUserIds     ?? target.notifyMobileUserIds,
+    notifyTeams:         argv.teams !== undefined ? Boolean(argv.teams) : Boolean(target.notifyTeams),
+    enabled:             argv.enabled !== undefined ? argv.enabled : target.enabled,
+  };
+
+  // HIGH: same "fires into the void" guard as create -- an update that strips
+  // every notification channel (or a rule that already had none, being
+  // re-enabled without adding one) silently produces an alert nobody sees.
+  if (!hasAnyRecipient({ emails: body.notifyEmails, sms: body.notifyPhoneNumbers, webhook: body.notifyWebhookUrl, mobileUserIds: body.notifyMobileUserIds, teams: body.notifyTeams })
+      && !argv.noRecipientsOk) {
+    console.error('This update would leave the rule with no notification channel (--emails, --sms, --webhook, --teams, or --mobile-user-ids) — it would fire but notify no one.');
+    console.error('If that\'s intentional, pass --no-recipients-ok to proceed anyway.');
+    process.exit(1);
+  }
+
+  if (!argv.yes) {
+    console.log(`\n${DIM}Current rule:${RESET}\n`);
+    printAlertRule(target);
+    console.log(`\n${DIM}About to update to (dry run — nothing sent yet):${RESET}\n`);
+    printAlertRule(body);
+    console.log(`\nRe-run with --yes to actually apply this update.\n`);
+    return;
+  }
+
+  const res = await fetch(`${msgBase}/superadmin/log-alerts/rules/${argv.id}`, {
+    method:  'PUT',
+    headers: {
+      Authorization:       `Bearer ${creds.velaroToken}`,
+      'X-Internal-SiteId': String(creds.siteId),
+      'Content-Type':      'application/json',
+    },
+    body:   JSON.stringify(body),
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    console.error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+    process.exit(1);
+  }
+  const data = await res.json();
+  console.log(`\n${CYN}✓${RESET} Updated rule [${data.id}] "${data.name}"\n`);
+  printAlertRule(data);
+  console.log('');
+}
+
 async function toggleAlertRule(argv) {
   const creds   = await getCredentials();
   await requireAdmin(creds);
@@ -651,12 +751,36 @@ export const logsCommand = {
             .option('emails',           { describe: 'Comma-separated notification email addresses', type: 'string' })
             .option('sms',              { describe: 'Comma-separated E.164 phone numbers for SMS', type: 'string' })
             .option('webhook',          { describe: 'Webhook URL (Slack/Teams) to POST on fire', type: 'string' })
+            .option('teams',            { describe: 'Also post to the Production/Staging Alerts Teams channel via the velaro-alerts-to-teams Logic App', type: 'boolean' })
             .option('mobile-user-ids',  { describe: 'Comma-separated Velaro workspace user IDs for mobile push', type: 'string' })
             .option('no-recipients-ok', { describe: 'Allow creating a rule with zero notification channels (visible in Alert History only)', type: 'boolean', default: false })
             .option('yes',              { describe: 'Skip the dry-run preview and actually create the rule', type: 'boolean', default: false })
             .option('env',              { describe: 'staging or prod', type: 'string' }),
           handler:  createAlertRule,
         })
+        .command({
+          command:  'update <id>',
+          describe: 'Change an existing alert rule (threshold, window, query, recipients, etc.) without touching code',
+          builder:  yy => yy
+            .positional('id', { describe: 'Rule id (from: velaro logs alerts list)', type: 'number' })
+            .option('name',             { describe: 'Rule name', type: 'string' })
+            .option('query',            { describe: 'Message-contains text to match', type: 'string' })
+            .option('level',            { describe: 'ERROR, WARN, INFO, or DEBUG', type: 'string' })
+            .option('integration',      { describe: 'Integration tag to match', type: 'string' })
+            .option('window-minutes',   { describe: 'Rolling window in minutes', type: 'number' })
+            .option('threshold',        { describe: 'Fire when count >= this within the window', type: 'number' })
+            .option('cooldown-minutes', { describe: 'Minimum minutes between re-fires', type: 'number' })
+            .option('emails',           { describe: 'Comma-separated notification email addresses', type: 'string' })
+            .option('sms',              { describe: 'Comma-separated E.164 phone numbers for SMS', type: 'string' })
+            .option('webhook',          { describe: 'Webhook URL (Slack/Teams) to POST on fire', type: 'string' })
+            .option('teams',            { describe: 'Also post to the Production/Staging Alerts Teams channel via the velaro-alerts-to-teams Logic App', type: 'boolean' })
+            .option('mobile-user-ids',  { describe: 'Comma-separated Velaro workspace user IDs for mobile push', type: 'string' })
+            .option('enabled',          { describe: 'Enable (true) or pause (false) the rule', type: 'boolean' })
+            .option('no-recipients-ok', { describe: 'Allow leaving the rule with zero notification channels', type: 'boolean', default: false })
+            .option('yes',              { describe: 'Skip the dry-run preview and actually apply the update', type: 'boolean', default: false })
+            .option('env',              { describe: 'staging or prod', type: 'string' }),
+          handler:  updateAlertRule,
+        })
         .command({
           command:  'toggle <id>',
           describe: 'Enable/pause an alert rule',
@@ -674,7 +798,7 @@ export const logsCommand = {
             .option('env', { describe: 'staging or prod', type: 'string' }),
           handler:  deleteAlertRule,
         })
-        .demandCommand(1, 'Specify a subcommand: list, suggest, create, toggle, or delete'),
+        .demandCommand(1, 'Specify a subcommand: list, suggest, create, update, toggle, or delete'),
     })
     .demandCommand(1, 'Specify a subcommand: search, tail, diagnose, digest-recipients, set-digest-recipients, or alerts'),
 };

package/lib/commands/mcp-key.js

@@ -1,10 +1,18 @@
 import fs   from 'fs';
 import path from 'path';
 import os   from 'os';
-import { get, post, del } from '../api.js';
+import { get, post, del, request } from '../api.js';
 import { getActiveEnv, ENVS } from '../config.js';
 import { runCommand }      from '../run.js';
 
+// The API returns { keys, monthlyLimit }; older deployments returned an array.
+// Fail on any other shape so a contract change cannot appear as an empty list.
+export function normalizeMcpKeysResponse(response) {
+  if (Array.isArray(response)) return response;
+  if (Array.isArray(response?.keys)) return response.keys;
+  throw new Error('Unexpected MCP API key list response.');
+}
+
 export const mcpKeyCommand = {
   command:  'mcp-key <subcommand>',
   describe: 'Manage MCP API keys (vel_live_* keys for AI skill access)',
@@ -23,8 +31,8 @@ const mcpKeyListCommand = {
   command:  'list',
   describe: 'List MCP API keys for your site',
   handler:  runCommand(async () => {
-    const keys = await get('/McpApiKeys');
-    if (!keys?.length) { console.log('No MCP keys found.'); return; }
+    const keys = normalizeMcpKeysResponse(await get('/McpApiKeys'));
+    if (!keys.length) { console.log('No MCP keys found.'); return; }
     console.log(`Found ${keys.length} key(s):\n`);
     for (const k of keys) {
       const used    = k.lastUsedAt ? new Date(k.lastUsedAt).toLocaleDateString() : 'never';
@@ -90,7 +98,7 @@ const mcpKeyInstallCommand = {
     const label   = argv.label || (env === 'staging' ? 'Claude Code (Staging)' : 'Claude Code');
 
     const payload = { label };
-    const result  = await post('/McpApiKeys', payload);
+    const result  = await request('POST', '/McpApiKeys', payload, env);
     const rawKey  = result.rawKey;
 
     // Claude Code reads MCP server definitions from the top-level "mcpServers" key
@@ -142,7 +150,7 @@ const mcpKeyInstallCommand = {
 
 const mcpKeyRotateCommand = {
   command:  'rotate <id|label>',
-  describe: 'Revoke an existing key and issue a replacement in one step',
+  describe: 'Issue a replacement key, then revoke the existing key',
   builder:  (y) =>
     y
       .positional('id|label', { type: 'string', describe: 'Numeric ID or partial label of the key to rotate (e.g. "jb" or "42")' })
@@ -156,12 +164,12 @@ const mcpKeyRotateCommand = {
       }),
 
   handler: runCommand(async (argv) => {
-    const keys = await get('/McpApiKeys');
+    const keys = normalizeMcpKeysResponse(await get('/McpApiKeys'));
     const search = String(argv['id|label'] ?? argv.id ?? '');
-    const numId  = parseInt(search, 10);
-    const matches = isNaN(numId)
-      ? keys?.filter(k => k.label.toLowerCase().includes(search.toLowerCase()))
-      : keys?.filter(k => k.id === numId);
+    const numId  = /^\d+$/.test(search) ? Number(search) : null;
+    const matches = numId === null
+      ? keys.filter(k => k.label.toLowerCase().includes(search.toLowerCase()))
+      : keys.filter(k => k.id === numId);
 
     if (!matches?.length)
       throw new Error(`No key found matching "${search}". Run 'velaro mcp-key list' to see your keys.`);
@@ -174,15 +182,17 @@ const mcpKeyRotateCommand = {
 
     const label = argv.label || old.label;
 
-    await del(`/McpApiKeys/${old.id}`);
-    console.log(`Revoked:  [${old.id}] ${old.label} (${old.keyPrefix}...)`);
-
     const payload = { label };
     if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
+    else if (old.expiresAt) payload.expiresAt = old.expiresAt;
     const result = await post('/McpApiKeys', payload);
 
-    console.log(`Replaced: [${result.id}] ${result.label}`);
+    // Print the one-time secret before revoking. If revocation fails, the user
+    // can still install this replacement and revoke the old key by ID.
+    console.log(`Created: [${result.id}] ${result.label}`);
     console.log(`\n  New key: ${result.rawKey}`);
     console.log(`\n  ${result.warning ?? 'Copy this key now — it will not be shown again.'}`);
+    await del(`/McpApiKeys/${old.id}`);
+    console.log(`Revoked: [${old.id}] ${old.label} (${old.keyPrefix}...)`);
   }),
 };

package/lib/commands/order-form.js

@@ -0,0 +1,107 @@
+// velaro order-form -- staff-only order form onboarding flow (OrderFormController).
+// See docs/architecture/order-form-onboarding-flow.md. Nothing here provisions, charges, or
+// touches QuickBooks: it drafts a deal, generates the contract, and sends it through Velaro Sign.
+import { request } from '../api.js';
+
+function money(cents) {
+  return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+// --line "slug:qty[:unitPriceCents[:setupFeeCents[:termMonths[:cadence]]]]" (repeatable)
+function parseLine(spec) {
+  const [slug, qty, unit, setup, term, cadence] = String(spec).split(':');
+  if (!slug) throw new Error(`Bad --line "${spec}". Format: slug:qty[:unitPriceCents[:setupFeeCents[:termMonths[:cadence]]]]`);
+  const line = { catalogSlug: slug, quantity: qty ? Number(qty) : 1 };
+  if (unit) line.unitPriceCents = Number(unit);
+  if (setup) line.setupFeeCents = Number(setup);
+  if (term) line.termMonths = Number(term);
+  if (cadence) line.cadence = cadence;
+  return line;
+}
+
+function printForm(f) {
+  console.log(`Order form ${f.id}: ${f.customerName} [${f.status}]`);
+  console.log(`  payment=${f.paymentMode} invoiceDetail=${f.invoiceDetailMode} applyOnSign=${f.applyOnSign} contractId=${f.contractId ?? '-'}`);
+  for (const l of f.lines ?? []) {
+    console.log(`  - ${l.catalogSlug} x${l.quantity} @ ${money(l.unitPriceCents)} (list ${money(l.listPriceCents)}) setup ${money(l.setupFeeCents)} ${l.termMonths}mo ${l.cadence}`);
+  }
+}
+
+async function createForm(args) {
+  const lines = [].concat(args.line ?? []).map(parseLine);
+  if (!args.customer || lines.length === 0) {
+    console.error('Usage: velaro order-form create --customer "Acme" --line slug:qty[:unitCents[:setupCents[:termMonths[:cadence]]]] [--line ...] [--site-id N] [--target v20] [--target-account-id X] [--payment-mode manual|card_checkout|invoice_net_terms] [--invoice-detail LineItemized|TermsReference] [--apply-on-sign]');
+    process.exit(1);
+  }
+  const body = {
+    customerName: args.customer,
+    siteId: args.siteId,
+    targetSystem: args.target,
+    targetAccountId: args.targetAccountId,
+    paymentMode: args.paymentMode,
+    invoiceDetailMode: args.invoiceDetail,
+    applyOnSign: !!args.applyOnSign,
+    lines,
+  };
+  const f = await request('POST', '/api/OrderForm', body);
+  printForm(f);
+}
+
+async function getForm(id) {
+  printForm(await request('GET', `/api/OrderForm/${id}`));
+}
+
+async function listForms(args) {
+  const q = args.status ? `?status=${encodeURIComponent(args.status)}` : '';
+  const forms = await request('GET', `/api/OrderForm${q}`);
+  if (!forms.length) { console.log('No order forms.'); return; }
+  for (const f of forms) console.log(`${f.id}\t${f.status}\t${f.customerName}\tcontract=${f.contractId ?? '-'}`);
+}
+
+async function generateContract(id, args) {
+  if (!args.email) {
+    console.error('Usage: velaro order-form generate-contract <id> --email buyer@example.com [--name "Buyer Name"]');
+    process.exit(1);
+  }
+  const r = await request('POST', `/api/OrderForm/${id}/generate-contract`, { customerEmail: args.email, customerName: args.name });
+  console.log(`Contract ${r.contractId} generated (draft). Run: velaro order-form send ${id}`);
+}
+
+async function sendForm(id, args) {
+  const r = await request('POST', `/api/OrderForm/${id}/send`, { expirationDays: args.expirationDays });
+  console.log(`Sent. emailSent=${r.emailSent}${r.emailError ? ` (${r.emailError})` : ''}\nSigning URL: ${r.signingUrl}`);
+}
+
+async function voidForm(id) {
+  const f = await request('POST', `/api/OrderForm/${id}/void`);
+  console.log(`Order form ${f.id} is now ${f.status}.`);
+}
+
+export const orderFormCommand = {
+  command: 'order-form <subcommand>',
+  describe: 'Draft, contract, send, and void order forms (staff only)',
+  builder: (yargs) =>
+    yargs
+      .command('create', 'Create a draft order form (lines validated against the catalog)', {
+        customer: { type: 'string' },
+        line: { type: 'string', array: true, describe: 'slug:qty[:unitPriceCents[:setupFeeCents[:termMonths[:cadence]]]]' },
+        'site-id': { type: 'number' },
+        target: { type: 'string' },
+        'target-account-id': { type: 'string' },
+        'payment-mode': { type: 'string', choices: ['manual', 'card_checkout', 'invoice_net_terms'] },
+        'invoice-detail': { type: 'string', choices: ['LineItemized', 'TermsReference'] },
+        'apply-on-sign': { type: 'boolean', default: false },
+      }, (args) => createForm(args))
+      .command('get <id>', 'Show an order form', {}, (args) => getForm(args.id))
+      .command('list', 'List order forms', { status: { type: 'string' } }, (args) => listForms(args))
+      .command('generate-contract <id>', 'Generate the draft contract from the order form', {
+        email: { type: 'string' },
+        name: { type: 'string' },
+      }, (args) => generateContract(args.id, args))
+      .command('send <id>', 'Send the generated contract for signature via Velaro Sign', {
+        'expiration-days': { type: 'number' },
+      }, (args) => sendForm(args.id, args))
+      .command('void <id>', 'Void an order form (and its unsigned contract)', {}, (args) => voidForm(args.id))
+      .demandCommand(1),
+  handler: () => {},
+};