@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/site-provision.js

@@ -0,0 +1,68 @@
+// velaro site-provision: staff-only site provisioning, including cross-environment
+// parity provisioning (forcing a specific SiteId to match another environment).
+import { messagingPost, getCredentials } from '../api.js';
+import { runCommand } from '../run.js';
+
+function isVelaroAdmin(creds) {
+  return creds.siteId === 1032;
+}
+
+export const siteProvisionCommand = {
+  command:  'site-provision',
+  describe: 'Provision a new Velaro site (Velaro staff only)',
+  builder:  (y) =>
+    y
+      .option('company',      { type: 'string',  demandOption: true,  describe: 'Company name' })
+      .option('admin-email',  { type: 'string',  demandOption: true,  describe: 'Admin user email' })
+      .option('admin-first-name', { type: 'string', describe: 'Admin first name' })
+      .option('admin-last-name',  { type: 'string', describe: 'Admin last name' })
+      .option('tier',          { type: 'string',  default: 'Starter', describe: 'Starter, Professional, Business, Enterprise, or Trial' })
+      .option('site-id',       { type: 'number',  describe: 'Force a specific SiteId (>= 100000), used for cross-environment parity' })
+      .option('package-id',    { type: 'number',  describe: 'SubscriptionPackage Id to provision from' })
+      .option('package-version-id', { type: 'number', describe: 'Specific PackageVersion Id (defaults to latest published for package-id)' })
+      .option('all-features-on', { type: 'boolean', default: false, describe: 'Everything ON subscription, internal/demo use only' })
+      .option('trial',         { type: 'boolean', default: false, describe: 'Provision as a trial' })
+      .option('trial-days',    { type: 'number',  default: 7 })
+      .option('is-velaro-internal-site', { type: 'boolean', describe: 'Mark as a Velaro-internal site' })
+      .option('has-demo-data', { type: 'boolean', describe: 'Mark as having demo data' })
+      .option('billing-source', { type: 'string', describe: 'e.g. "direct"' }),
+  handler:  runCommand(async (argv) => {
+    const creds = await getCredentials();
+    if (!isVelaroAdmin(creds)) {
+      console.error('This command is only available to Velaro staff.');
+      process.exit(1);
+    }
+
+    const body = {
+      companyName:          argv.company,
+      adminEmail:           argv['admin-email'],
+      adminFirstName:       argv['admin-first-name'],
+      adminLastName:        argv['admin-last-name'],
+      subscriptionTier:     argv.tier,
+      explicitSiteId:       argv['site-id'],
+      packageId:            argv['package-id'],
+      packageVersionId:     argv['package-version-id'],
+      allFeaturesOn:        argv['all-features-on'],
+      isTrial:              argv.trial,
+      trialDurationDays:    argv['trial-days'],
+      isVelaroInternalSite: argv['is-velaro-internal-site'],
+      hasDemoData:          argv['has-demo-data'],
+      billingSource:        argv['billing-source'],
+    };
+
+    console.log(`\nProvisioning site${argv['site-id'] ? ` ${argv['site-id']}` : ''} for "${argv.company}" on ${creds.env}...`);
+    const result = await messagingPost('/SuperAdmin/ProvisionSite', body);
+
+    if (!result.success) {
+      console.error(`\x1b[31mFAILED: ${result.error}\x1b[0m`);
+      if (result.existingSiteId) console.error(`  Existing site: ${result.existingSiteId}`);
+      process.exit(1);
+    }
+
+    console.log(`\x1b[32mOK: site ${result.siteId} provisioned\x1b[0m`);
+    console.log(`  Company: ${result.companyName}`);
+    console.log(`  Admin:   ${result.adminEmail}`);
+    console.log(`  Team:    ${result.defaultTeamId}`);
+    if (result.temporaryPassword) console.log(`  Temp password: ${result.temporaryPassword}`);
+  }),
+};

package/lib/commands/site.js

@@ -1,62 +1,62 @@
-import { get }       from '../api.js';
-import { runCommand } from '../run.js';
-
-const FEATURE_MAP = {
-  enableWeb:                'Web Chat',
-  enableSms:                'SMS',
-  enableEmail:              'Email',
-  enableWhatsapp:           'WhatsApp',
-  enableIvr:                'IVR / Voice',
-  enableFacebook:           'Facebook Messenger',
-  enableInstagram:          'Instagram',
-  enableAI:                 'AI Bots',
-  enableKnowledgeBase:      'Knowledge Base',
-  enableAutomation:         'Workflows',
-  enableWorkflowRules:      'Routing Rules',
-  enableChatTranslations:   'Chat Translation',
-  enableVideoChat:          'Video Chat',
-  enableTicketing:          'Ticketing',
-  enableAgentDashboard:     'Agent Dashboard',
-  enableMcpApi:             'MCP API Gateway',
-  enableOutboundCampaigns:  'Email Campaigns',
-  enableRcs:                'RCS Messaging',
-  enablePageWidgets:        'Page Widgets',
-  enableVisitorTracking:    'Visitor Tracking',
-};
-
-const STATUS_LABEL = { Available: 'online', Away: 'away', Offline: 'offline' };
-
-export const siteCommand = {
-  command:  'site',
-  describe: 'Show site overview: active features and agent availability',
-  handler:  runCommand(async () => {
-    const [sub, agents] = await Promise.all([
-      get('/Subscription'),
-      get('/Users/List'),
-    ]);
-
-    // Active features — friendly names only, no internal flag names
-    const active = Object.entries(FEATURE_MAP)
-      .filter(([key]) => sub[key] === true)
-      .map(([, label]) => label);
-
-    console.log('\nActive features:');
-    if (active.length) {
-      console.log('  ' + active.join('  ·  '));
-    } else {
-      console.log('  (none)');
-    }
-
-    if (sub.maxCreatedUsers) {
-      console.log(`\nAgent seats: ${sub.maxCreatedUsers} licensed`);
-    }
-
-    // Agent availability summary
-    const counts = { online: 0, away: 0, offline: 0 };
-    for (const a of agents) {
-      const key = STATUS_LABEL[a.status] ?? 'offline';
-      counts[key]++;
-    }
-    console.log(`Agent status: ${counts.online} online · ${counts.away} away · ${counts.offline} offline\n`);
-  }),
-};
+import { get, messagingGet } from '../api.js';
+import { runCommand } from '../run.js';
+
+const FEATURE_MAP = {
+  enableWeb:                'Web Chat',
+  enableSms:                'SMS',
+  enableEmail:              'Email',
+  enableWhatsapp:           'WhatsApp',
+  enableIvr:                'IVR / Voice',
+  enableFacebook:           'Facebook Messenger',
+  enableInstagram:          'Instagram',
+  enableAI:                 'AI Bots',
+  enableKnowledgeBase:      'Knowledge Base',
+  enableAutomation:         'Workflows',
+  enableWorkflowRules:      'Routing Rules',
+  enableChatTranslations:   'Chat Translation',
+  enableVideoChat:          'Video Chat',
+  enableTicketing:          'Ticketing',
+  enableAgentDashboard:     'Agent Dashboard',
+  enableMcpApi:             'MCP API Gateway',
+  enableOutboundCampaigns:  'Email Campaigns',
+  enableRcs:                'RCS Messaging',
+  enablePageWidgets:        'Page Widgets',
+  enableVisitorTracking:    'Visitor Tracking',
+};
+
+const STATUS_LABEL = { Available: 'online', Away: 'away', Offline: 'offline' };
+
+export const siteCommand = {
+  command:  'site',
+  describe: 'Show site overview: active features and agent availability',
+  handler:  runCommand(async () => {
+    const [sub, agents] = await Promise.all([
+      messagingGet('/Subscription'),
+      get('/Users/List'),
+    ]);
+
+    // Active features — friendly names only, no internal flag names
+    const active = Object.entries(FEATURE_MAP)
+      .filter(([key]) => sub[key] === true)
+      .map(([, label]) => label);
+
+    console.log('\nActive features:');
+    if (active.length) {
+      console.log('  ' + active.join('  ·  '));
+    } else {
+      console.log('  (none)');
+    }
+
+    if (sub.maxCreatedUsers) {
+      console.log(`\nAgent seats: ${sub.maxCreatedUsers} licensed`);
+    }
+
+    // Agent availability summary
+    const counts = { online: 0, away: 0, offline: 0 };
+    for (const a of agents) {
+      const key = STATUS_LABEL[a.status] ?? 'offline';
+      counts[key]++;
+    }
+    console.log(`Agent status: ${counts.online} online · ${counts.away} away · ${counts.offline} offline\n`);
+  }),
+};

package/lib/commands/sitesync.js

@@ -0,0 +1,158 @@
+// velaro sitesync: copies AI configs, bot profiles, workflows, deployments, and site
+// settings from a source site to a target site (Velaro staff only). The blob-push/blob-import
+// pair is the cross-environment path (shared blob storage between staging and prod), so a
+// bundle exported on one environment can be applied on another without direct cross-DB access.
+import { get, post, getCredentials } from '../api.js';
+import { runCommand } from '../run.js';
+
+function isVelaroAdmin(creds) {
+  return creds.siteId === 1032;
+}
+
+function requireStaff(creds) {
+  if (!isVelaroAdmin(creds)) {
+    console.error('This command is only available to Velaro staff.');
+    process.exit(1);
+  }
+}
+
+function printResult(result) {
+  if (result.errors?.length) {
+    console.log('\x1b[31mErrors:\x1b[0m');
+    for (const e of result.errors) console.log(`  ${e}`);
+  }
+  if (result.warnings?.length) {
+    console.log('\x1b[33mWarnings:\x1b[0m');
+    for (const w of result.warnings) console.log(`  ${w}`);
+  }
+  if (result.plan?.length) {
+    console.log(`\nPlan (${result.isDryRun ? 'dry run' : 'applied'}):`);
+    for (const item of result.plan) {
+      console.log(`  [${item.action}] ${item.resource}: ${item.name}${item.note ? ` (${item.note})` : ''}`);
+    }
+  }
+  console.log(`\nApplied: ${result.applied?.length ?? 0}  Skipped: ${result.skipped?.length ?? 0}  Errors: ${result.errors?.length ?? 0}`);
+  console.log(result.success ? '\x1b[32mSuccess\x1b[0m' : '\x1b[31mCompleted with errors\x1b[0m');
+}
+
+const previewCommand = {
+  command:  'preview',
+  describe: 'Dry-run preview of a site sync, no writes',
+  builder:  (y) =>
+    y
+      .option('source', { type: 'number', demandOption: true, describe: 'Source site ID' })
+      .option('target', { type: 'number', demandOption: true, describe: 'Target site ID' })
+      .option('conflict-mode', { type: 'string', default: 'skip', choices: ['skip', 'overwrite', 'rename'] }),
+  handler: runCommand(async (argv) => {
+    const creds = await getCredentials();
+    requireStaff(creds);
+    const result = await get(`/SiteSync/preview?sourceSiteId=${argv.source}&targetSiteId=${argv.target}&conflictMode=${argv['conflict-mode']}`);
+    printResult(result);
+  }),
+};
+
+const blobPushCommand = {
+  command:  'blob-push',
+  describe: 'Export a site config bundle and push it to shared blob storage (readable from any environment)',
+  builder:  (y) =>
+    y
+      .option('source', { type: 'number', demandOption: true, describe: 'Source site ID' })
+      .option('label',  { type: 'string', describe: 'Label for this bundle' }),
+  handler: runCommand(async (argv) => {
+    const creds = await getCredentials();
+    requireStaff(creds);
+    const result = await post('/SiteSync/blob/push', { sourceSiteId: argv.source, label: argv.label });
+    if (!result.success) {
+      console.error(`\x1b[31mFAILED: ${result.error}\x1b[0m`);
+      process.exit(1);
+    }
+    console.log(`\x1b[32mOK: pushed\x1b[0m`);
+    console.log(`  Blob key: ${result.blobKey}`);
+    console.log(`\nOn the target environment, run:`);
+    console.log(`  velaro env <target-env>`);
+    console.log(`  velaro sitesync blob-import --blob-key ${result.blobKey} --target <targetSiteId> --dry-run`);
+  }),
+};
+
+const blobListCommand = {
+  command:  'blob-list',
+  describe: 'List bundles currently in shared blob storage, newest first',
+  handler: runCommand(async () => {
+    const creds = await getCredentials();
+    requireStaff(creds);
+    const entries = await get('/SiteSync/blob/list');
+    if (!entries?.length) {
+      console.log('No bundles in blob storage.');
+      return;
+    }
+    for (const e of entries) {
+      console.log(`${e.blobKey}`);
+      console.log(`  label: ${e.label ?? '(none)'}  source site: ${e.sourceSiteId ?? '?'}  pushed by: ${e.pushedBy ?? 'unknown'}  at: ${e.exportedAt ?? '?'}`);
+    }
+  }),
+};
+
+const blobImportCommand = {
+  command:  'blob-import',
+  describe: 'Pull a bundle from blob by key and apply (or preview) it to a target site',
+  builder:  (y) =>
+    y
+      .option('blob-key', { type: 'string', demandOption: true })
+      .option('target',   { type: 'number', demandOption: true, describe: 'Target site ID' })
+      .option('conflict-mode', { type: 'string', default: 'skip', choices: ['skip', 'overwrite', 'rename'] })
+      .option('dry-run',  { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const creds = await getCredentials();
+    requireStaff(creds);
+    const result = await post('/SiteSync/blob/import', {
+      blobKey: argv['blob-key'],
+      targetSiteId: argv.target,
+      conflictMode: argv['conflict-mode'],
+      dryRun: argv['dry-run'],
+    });
+    printResult(result);
+    if (argv['dry-run'] && result.success) {
+      console.log(`\nRe-run without --dry-run to apply.`);
+    }
+  }),
+};
+
+const applyCommand = {
+  command:  'apply',
+  describe: 'Export a bundle from a source site (same database) and apply it directly to a target site',
+  builder:  (y) =>
+    y
+      .option('source', { type: 'number', demandOption: true, describe: 'Source site ID' })
+      .option('target', { type: 'number', demandOption: true, describe: 'Target site ID' })
+      .option('conflict-mode', { type: 'string', default: 'skip', choices: ['skip', 'overwrite', 'rename'] })
+      .option('dry-run', { type: 'boolean', default: false }),
+  handler: runCommand(async (argv) => {
+    const creds = await getCredentials();
+    requireStaff(creds);
+    const bundle = await get(`/SiteSync/export?sourceSiteId=${argv.source}`);
+    const result = await post('/SiteSync/apply', {
+      targetSiteId: argv.target,
+      conflictMode: argv['conflict-mode'],
+      dryRun: argv['dry-run'],
+      bundle,
+    });
+    printResult(result);
+    if (argv['dry-run'] && result.success) {
+      console.log(`\nRe-run without --dry-run to apply.`);
+    }
+  }),
+};
+
+export const siteSyncCommand = {
+  command:  'sitesync <subcommand>',
+  describe: 'Copy AI configs, bot profiles, workflows, deployments, and site settings between sites (Velaro staff only)',
+  builder:  (yargs) =>
+    yargs
+      .command(previewCommand)
+      .command(applyCommand)
+      .command(blobPushCommand)
+      .command(blobListCommand)
+      .command(blobImportCommand)
+      .demandCommand(1, 'Specify a subcommand: preview, apply, blob-push, blob-list, blob-import'),
+  handler: () => {},
+};

package/lib/commands/slack.js

@@ -0,0 +1,64 @@
+import { request } from '../api.js';
+
+export const slackCommand = {
+  command: 'slack <subcommand>',
+  describe: 'Send messages to Slack channels',
+  builder: (yargs) =>
+    yargs
+      .command(
+        'notify [message]',
+        'Send a message to a Slack channel webhook',
+        (y) =>
+          y
+            .positional('message', { type: 'string', describe: 'Message to send' })
+            .option('title', { type: 'string', describe: 'Message title', alias: 't' })
+            .option('id', { type: 'number', describe: 'Webhook config ID (omit to list)', alias: 'i' }),
+        async (argv) => {
+          const webhooks = await request('GET', '/SlackNotification');
+
+          if (!Array.isArray(webhooks) || !webhooks.length) {
+            console.log('No Slack webhooks configured. Go to Integrations → Slack to add one.');
+            return;
+          }
+
+          if (!argv.id) {
+            console.log('Available Slack webhooks:');
+            for (const w of webhooks) {
+              console.log(`  [${w.id}] ${w.name}${w.isEnabled ? '' : ' (disabled)'}`);
+            }
+            console.log('\nRun with --id <number> to send a message.');
+            return;
+          }
+
+          const webhook = webhooks.find((w) => w.id === argv.id);
+          if (!webhook) { console.error(`No webhook with id ${argv.id}`); process.exit(1); }
+          if (!webhook.isEnabled) { console.error(`Webhook "${webhook.name}" is disabled.`); process.exit(1); }
+
+          const message = argv.message;
+          if (!message) { console.error('Message is required. Pass it as an argument: velaro slack notify "hello"'); process.exit(1); }
+
+          await request('POST', `/SlackNotification/Send/${argv.id}`, {
+            message,
+            title: argv.title || null,
+          });
+          console.log(`✓ Sent to Slack webhook "${webhook.name}"`);
+        }
+      )
+      .command(
+        'list',
+        'List configured Slack webhooks',
+        () => {},
+        async () => {
+          const webhooks = await request('GET', '/SlackNotification');
+          if (!Array.isArray(webhooks) || !webhooks.length) {
+            console.log('No Slack webhooks configured.');
+            return;
+          }
+          for (const w of webhooks) {
+            console.log(`[${w.id}] ${w.name} — ${w.isEnabled ? 'enabled' : 'disabled'}`);
+          }
+        }
+      )
+      .demandCommand(1, 'Specify a subcommand: notify, list'),
+  handler: () => {},
+};

package/lib/commands/squarespace.js

@@ -0,0 +1,108 @@
+/**
+ * velaro squarespace, Squarespace Commerce integration management
+ *
+ *   velaro squarespace status              Show connection status for the current site
+ *   velaro squarespace connect <apiKey>    Connect a Squarespace store with a Commerce API Key
+ *   velaro squarespace disconnect          Disconnect the Squarespace store
+ *   velaro squarespace test                Test the current connection
+ *
+ * Read-only integration: Squarespace has no cart or checkout API, so there is no
+ * "order create" or "checkout" subcommand here by design.
+ */
+
+import { request } from '../api.js';
+
+const GRN  = '\x1b[32m';
+const RED  = '\x1b[31m';
+const DIM  = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RST  = '\x1b[0m';
+
+async function statusHandler(_argv) {
+  const r = await request('GET', `/Squarespace/Config`);
+  if (!r || !r.connected) {
+    console.log('\nNo Squarespace connection found for this site.\n');
+    return;
+  }
+  console.log(`\n${BOLD}Squarespace Status${RST}\n`);
+  console.log(`  Status:      ${r.isEnabled ? `${GRN}connected${RST}` : `${RED}disabled${RST}`}`);
+  if (r.storeUrl)  console.log(`  Store URL:   ${r.storeUrl}`);
+  console.log(`  API Key:     ${r.hasApiKey ? 'on file' : 'missing'}`);
+  if (r.updatedAt) console.log(`  Updated:     ${DIM}${new Date(r.updatedAt).toLocaleString()}${RST}`);
+  console.log('');
+}
+
+async function connectHandler(argv) {
+  if (!argv.apiKey) {
+    console.error(`${RED}x <apiKey> is required (velaro squarespace connect --apiKey <key> [--storeUrl <url>])${RST}`);
+    process.exitCode = 1;
+    return;
+  }
+  const r = await request('POST', `/Squarespace/Config`, {
+    apiKey: argv.apiKey,
+    storeUrl: argv.storeUrl || '',
+  });
+  if (r?.success) {
+    console.log(`${GRN}Squarespace connected.${RST}`);
+  } else {
+    console.error(`${RED}x ${r?.message || 'Failed to connect Squarespace.'}${RST}`);
+    process.exitCode = 1;
+  }
+}
+
+async function disconnectHandler(_argv) {
+  const cfg = await request('GET', `/Squarespace/Config`);
+  if (!cfg?.connected) {
+    console.log('Squarespace is not connected.');
+    return;
+  }
+  const r = await request('DELETE', `/Squarespace/Config/${cfg.id}`);
+  if (r?.success) {
+    console.log(`${GRN}Squarespace disconnected.${RST}`);
+  } else {
+    console.error(`${RED}x ${r?.message || 'Failed to disconnect.'}${RST}`);
+    process.exitCode = 1;
+  }
+}
+
+async function testHandler(_argv) {
+  const r = await request('POST', `/Squarespace/TestConnection`, {});
+  if (r?.success) {
+    console.log(`${GRN}${r.message}${RST}`);
+  } else {
+    console.error(`${RED}x ${r?.message || 'Connection test failed.'}${RST}`);
+    process.exitCode = 1;
+  }
+}
+
+export const squarespaceCommand = {
+  command:  'squarespace <subcommand>',
+  describe: 'Manage the Squarespace Commerce integration',
+  builder: (yy) =>
+    yy
+      .command({
+        command: 'status',
+        describe: 'Show Squarespace connection status',
+        handler: statusHandler,
+      })
+      .command({
+        command: 'connect',
+        describe: 'Connect a Squarespace store with a Commerce API Key',
+        builder: (y) => y
+          .option('apiKey', { describe: 'Squarespace Commerce API Key', type: 'string' })
+          .option('storeUrl', { describe: 'Squarespace store URL (optional, reference only)', type: 'string' }),
+        handler: connectHandler,
+      })
+      .command({
+        command: 'disconnect',
+        describe: 'Disconnect the Squarespace store',
+        handler: disconnectHandler,
+      })
+      .command({
+        command: 'test',
+        describe: 'Test the current Squarespace connection',
+        handler: testHandler,
+      })
+      .demandCommand(1, 'Specify a subcommand. Run "velaro squarespace --help" for options.'),
+  handler: () => {},
+};

package/lib/commands/status.js

@@ -1,24 +1,24 @@
-import { readConfig, getActiveEnv, ENVS } from '../config.js';
-
-export const statusCommand = {
-  command:  'status',
-  describe: 'Check Velaro API health',
-  handler:  async () => {
-    const cfg     = readConfig();
-    const env     = getActiveEnv();
-    const apiBase = cfg.envs?.[env]?.adminApiBase ?? ENVS[env].adminApiBase;
-    process.stdout.write(`Checking ${apiBase}/Status ... `);
-    try {
-      const res = await fetch(`${apiBase}/Status`);
-      if (res.ok) {
-        console.log('OK');
-      } else {
-        console.log(`DEGRADED (HTTP ${res.status})`);
-        process.exit(1);
-      }
-    } catch (err) {
-      console.log(`UNREACHABLE: ${err.message}`);
-      process.exit(1);
-    }
-  },
-};
+import { readConfig, getActiveEnv, ENVS } from '../config.js';
+
+export const statusCommand = {
+  command:  'status',
+  describe: 'Check Velaro API health',
+  handler:  async () => {
+    const cfg     = readConfig();
+    const env     = getActiveEnv();
+    const apiBase = cfg.envs?.[env]?.adminApiBase ?? ENVS[env].adminApiBase;
+    process.stdout.write(`Checking ${apiBase}/Status ... `);
+    try {
+      const res = await fetch(`${apiBase}/Status`);
+      if (res.ok) {
+        console.log('OK');
+      } else {
+        console.log(`DEGRADED (HTTP ${res.status})`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.log(`UNREACHABLE: ${err.message}`);
+      process.exit(1);
+    }
+  },
+};

package/lib/commands/subscription.js

@@ -0,0 +1,43 @@
+// velaro subscription — apply/diff SubscriptionPackage packages on a site (superadmin only)
+// Wraps SuperAdminController.ApplyPackageToSiteAsync / GetPackageDiffAsync in velaro-messaging,
+// the same reflection-copy service the SuperAdmin browser UI uses -- never hand-toggles flags.
+import { messagingPost, messagingGet } from '../api.js';
+
+async function applyPackage(args) {
+  if (!args.site || !args.package) {
+    console.error('Usage: velaro subscription apply-package --site 100150 --package 3 [--version 3] [--autoUpgrade] [--resetOverrides]');
+    process.exit(1);
+  }
+  const body = {
+    PackageId: args.package,
+    VersionId: args.version ?? null,
+    AutoUpgrade: !!args.autoUpgrade,
+    ResetOverrides: !!args.resetOverrides,
+  };
+  const result = await messagingPost(`SuperAdmin/subscription/${args.site}/apply-package`, body);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function packageDiff(args) {
+  if (!args.site) {
+    console.error('Usage: velaro subscription package-diff --site 100150');
+    process.exit(1);
+  }
+  const result = await messagingGet(`SuperAdmin/subscription/${args.site}/package-diff`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export function subscriptionCommand(yargs) {
+  return yargs
+    .command('apply-package', 'Apply a SubscriptionPackage to a site (superadmin only) -- correct reflection-copy path, never hand-toggles flags', y => y
+      .option('site',            { type: 'number', demandOption: true, desc: 'Target site ID' })
+      .option('package',         { type: 'number', demandOption: true, desc: 'SubscriptionPackage.Id (e.g. 3 = Enterprise) -- verify by name in SuperAdmin first, IDs can drift between staging/prod' })
+      .option('version',         { type: 'number', desc: 'Specific PackageVersion.Id (omit to use the package\'s latest published version)' })
+      .option('autoUpgrade',     { type: 'boolean', desc: 'Auto-upgrade this site to future published versions of the package' })
+      .option('resetOverrides',  { type: 'boolean', desc: 'Clear any existing per-site Subscription overrides before applying' })
+    , a => applyPackage(a))
+    .command('package-diff', 'Show what would change if the site\'s current package were re-applied (read-only)', y => y
+      .option('site', { type: 'number', demandOption: true, desc: 'Target site ID' })
+    , a => packageDiff(a))
+    .demandCommand(1, 'Specify a subcommand: apply-package | package-diff');
+}