@velaro/cli 0.1.1 → 0.2.0

package/bin/velaro.js

@@ -4,25 +4,53 @@ import yargs                                    from 'yargs';
 import { hideBin }                              from 'yargs/helpers';
 import { loginCommand, logoutCommand }          from '../lib/commands/login.js';
 import { whoamiCommand }                        from '../lib/commands/whoami.js';
+import { teamCommand }                          from '../lib/commands/team.js';
 import { botCommand }                           from '../lib/commands/bot.js';
+import { kbCommand }                            from '../lib/commands/kb.js';
+import { workflowCommand }                      from '../lib/commands/workflow.js';
+import { ruleCommand }                          from '../lib/commands/rule.js';
+import { agentCommand }                         from '../lib/commands/agent.js';
 import { ingestCommand }                        from '../lib/commands/ingest.js';
 import { mcpKeyCommand }                        from '../lib/commands/mcp-key.js';
 import { statusCommand }                        from '../lib/commands/status.js';
+import { siteCommand }                          from '../lib/commands/site.js';
+import { checkCommand }                         from '../lib/commands/check.js';
+import { updateCommand }                        from '../lib/commands/update.js';
+import { startUpdateCheck }                     from '../lib/update-check.js';
 
-yargs(hideBin(process.argv))
+// Start background update check — doesn't block the command
+const printUpdateNotice = startUpdateCheck();
+
+await yargs(hideBin(process.argv))
   .scriptName('velaro')
   .usage('$0 <command> [options]')
+  // Auth
   .command(loginCommand)
   .command(logoutCommand)
   .command(whoamiCommand)
+  // Info
+  .command(siteCommand)
+  .command(checkCommand)
+  .command(statusCommand)
+  // Config
+  .command(teamCommand)
   .command(botCommand)
+  .command(kbCommand)
+  .command(workflowCommand)
+  .command(ruleCommand)
+  .command(agentCommand)
+  // Integrations / keys
   .command(ingestCommand)
   .command(mcpKeyCommand)
-  .command(statusCommand)
+  // CLI maintenance
+  .command(updateCommand)
   .demandCommand(1, 'Specify a command. Run velaro --help for a list.')
   .strict()
   .help()
   .alias('h', 'help')
   .alias('v', 'version')
   .wrap(Math.min(100, process.stdout.columns || 100))
-  .argv;
+  .parseAsync();
+
+// Print update notice after command output (non-intrusive)
+await printUpdateNotice();

package/lib/commands/agent.js

@@ -0,0 +1,50 @@
+import { get, post }  from '../api.js';
+import { runCommand }  from '../run.js';
+
+const VALID_STATUSES = ['Available', 'Away', 'Offline'];
+
+export const agentCommand = {
+  command:  'agent <subcommand>',
+  describe: 'View and manage agents',
+  builder:  (yargs) => yargs
+    .command({
+      command:  'list',
+      describe: 'List agents and their current availability',
+      handler:  runCommand(async () => {
+        const [agents, teams] = await Promise.all([
+          get('/Users/List'),
+          get('/Teams/List'),
+        ]);
+
+        const teamMap = Object.fromEntries(teams.map(t => [t.id, t.name]));
+
+        if (!agents.length) { console.log('No agents found.'); return; }
+
+        const rows = agents.map(a => ({
+          id:     `[${a.id}]`,
+          status: (a.status ?? 'Offline').padEnd(9),
+          name:   a.displayName || `${a.firstName} ${a.lastName}`.trim() || a.email,
+          teams:  (a.teamIds ?? []).map(id => teamMap[id] ?? `team ${id}`).join(', ') || '—',
+        }));
+
+        const idW = Math.max(...rows.map(r => r.id.length));
+
+        for (const r of rows) {
+          console.log(`${r.id.padStart(idW)}  ${r.status}  ${r.name.padEnd(30)}  ${r.teams}`);
+        }
+        console.log(`\n${rows.length} agent(s)`);
+      }),
+    })
+    .command({
+      command:  'set-status',
+      describe: 'Set an agent\'s availability status (admin only)',
+      builder:  (y) => y
+        .option('id',     { type: 'number', demandOption: true, describe: 'Agent user ID' })
+        .option('status', { type: 'string', demandOption: true, describe: 'Available | Away | Offline', choices: VALID_STATUSES }),
+      handler: runCommand(async (argv) => {
+        await post('/UserStatus/admin', { userId: argv.id, status: argv.status });
+        console.log(`Agent ${argv.id} set to ${argv.status}.`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: list | set-status'),
+};

package/lib/commands/bot.js

@@ -1,5 +1,7 @@
-import { get, post }  from '../api.js';
-import { runCommand } from '../run.js';
+import { readFileSync }   from 'fs';
+import { get, post }      from '../api.js';
+import { requireFeature } from '../subscription.js';
+import { runCommand }     from '../run.js';
 
 export const botCommand = {
   command:  'bot <subcommand>',
@@ -7,17 +9,26 @@ export const botCommand = {
   builder:  (yargs) =>
     yargs
       .command(botListCommand)
+      .command(botGetCommand)
       .command(botSetupCommand)
-      .demandCommand(1, 'Specify a subcommand: list, setup'),
+      .command(botPromptCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, setup, prompt'),
   handler: () => {},
 };
 
+// ── list ───────────────────────────────────────────────────────────────────────
+
 const botListCommand = {
   command:  'list',
   describe: 'List AI bots on your site',
   handler:  runCommand(async () => {
+    await requireFeature('enableAI', 'AI Bots');
+
     const bots = await get('/AIConfiguration/list');
-    if (!bots?.length) { console.log('No bots found.'); return; }
+    if (!bots?.length) {
+      console.log('No bots found. Create one with: velaro bot setup --name "My Bot"');
+      return;
+    }
     console.log(`Found ${bots.length} bot(s):\n`);
     for (const b of bots) {
       console.log(`  [${b.id}] ${b.name}  model=${b.aiModel ?? '(default)'}  status=${b.status ?? 'ready'}`);
@@ -25,30 +36,102 @@ const botListCommand = {
   }),
 };
 
+// ── get ────────────────────────────────────────────────────────────────────────
+
+const botGetCommand = {
+  command:  'get <id>',
+  describe: 'Show full configuration for a bot',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Bot ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableAI', 'AI Bots');
+
+    const bot = await get(`/AIConfiguration/${argv.id}`);
+    if (!bot) { console.error(`Bot ${argv.id} not found.`); process.exit(1); }
+
+    console.log(`\n[${bot.id}] ${bot.name}`);
+    console.log(`  Model:        ${bot.aiModel ?? '(default)'}`);
+    console.log(`  Tone:         ${bot.tone ?? '—'}`);
+    console.log(`  Reply length: ${bot.replyLength ?? '—'}`);
+    console.log(`  Status:       ${bot.status ?? 'ready'}`);
+    if (bot.prompt) {
+      console.log(`\nSystem prompt:\n`);
+      console.log(bot.prompt);
+    } else {
+      console.log(`\nSystem prompt: (none)`);
+    }
+  }),
+};
+
+// ── setup ──────────────────────────────────────────────────────────────────────
+
 const botSetupCommand = {
   command:  'setup',
   describe: 'Create or update an AI bot (upsert by name)',
   builder:  (y) =>
     y
-      .option('name',         { describe: 'Bot name',                                                       type: 'string', demandOption: true })
-      .option('prompt',       { describe: 'System prompt text',                                              type: 'string' })
-      .option('model',        { describe: 'AI model override',                                               type: 'string', default: 'velaro-gpt-4o-mini' })
-      .option('tone',         { describe: 'Response tone',   choices: ['Professional','Friendly','Formal','Casual'], default: 'Professional' })
-      .option('reply-length', { describe: 'Response length', choices: ['Short','Medium','Long'],                     default: 'Medium' })
-      .option('urls',         { describe: 'Comma-separated data source URLs',                                type: 'string' }),
+      .option('name',         { describe: 'Bot name',                                                              type: 'string', demandOption: true })
+      .option('prompt',       { describe: 'System prompt text (inline)',                                            type: 'string' })
+      .option('prompt-file',  { describe: 'Path to a file containing the system prompt',                           type: 'string' })
+      .option('model',        { describe: 'AI model',           choices: ['velaro-gpt-4o-mini','velaro-gpt-4o'],   type: 'string', default: 'velaro-gpt-4o-mini' })
+      .option('tone',         { describe: 'Response tone',      choices: ['Professional','Friendly','Formal','Casual'], default: 'Professional' })
+      .option('reply-length', { describe: 'Response length',    choices: ['Short','Medium','Long'],                default: 'Medium' })
+      .option('urls',         { describe: 'Comma-separated data source URLs',                                      type: 'string' })
+      .conflicts('prompt', 'prompt-file'),
 
   handler: runCommand(async (argv) => {
+    await requireFeature('enableAI', 'AI Bots');
+
+    let promptText = argv.prompt;
+    if (argv['prompt-file']) {
+      promptText = readFileSync(argv['prompt-file'], 'utf8').trim();
+      console.log(`Read ${promptText.length} chars from ${argv['prompt-file']}`);
+    }
+
     const payload = {
       name:        argv.name,
       aiModel:     argv.model,
       tone:        argv.tone,
       replyLength: argv['reply-length'],
     };
-
-    if (argv.prompt) payload.prompt    = argv.prompt;
-    if (argv.urls)   payload.dataUrls  = argv.urls.split(',').map((u) => u.trim()).filter(Boolean);
+    if (promptText) payload.prompt   = promptText;
+    if (argv.urls)  payload.dataUrls = argv.urls.split(',').map((u) => u.trim()).filter(Boolean);
 
     const result = await post('/AIConfiguration', payload);
     console.log(`Saved: [${result.id}] ${result.name}`);
   }),
 };
+
+// ── prompt ─────────────────────────────────────────────────────────────────────
+
+const botPromptCommand = {
+  command:  'prompt <id>',
+  describe: 'Get or update a bot\'s system prompt',
+  builder:  (y) =>
+    y
+      .positional('id', { type: 'number', describe: 'Bot ID' })
+      .option('set',    { describe: 'New prompt text (inline)',        type: 'string' })
+      .option('file',   { describe: 'Path to a .txt/.md prompt file', type: 'string' })
+      .conflicts('set', 'file'),
+
+  handler: runCommand(async (argv) => {
+    await requireFeature('enableAI', 'AI Bots');
+
+    const bot = await get(`/AIConfiguration/${argv.id}`);
+    if (!bot) { console.error(`Bot ${argv.id} not found.`); process.exit(1); }
+
+    if (!argv.set && !argv.file) {
+      // Read mode — print current prompt
+      console.log(bot.prompt ?? '(no system prompt set)');
+      return;
+    }
+
+    let promptText = argv.set;
+    if (argv.file) {
+      promptText = readFileSync(argv.file, 'utf8').trim();
+      console.log(`Read ${promptText.length} chars from ${argv.file}`);
+    }
+
+    await post('/AIConfiguration', { ...bot, prompt: promptText });
+    console.log(`Bot [${argv.id}] "${bot.name}" prompt updated (${promptText.length} chars).`);
+  }),
+};

package/lib/commands/check.js

@@ -0,0 +1,163 @@
+/**
+ * velaro check — full site health and configuration summary.
+ *
+ * Shows every feature area with:
+ *   ✓  enabled and configured
+ *   ⚠  enabled but nothing configured yet
+ *   ✗  not on your plan
+ */
+
+import { get }        from '../api.js';
+import { getSubscription } from '../subscription.js';
+import { runCommand } from '../run.js';
+
+const TICK  = '✓';
+const WARN  = '⚠';
+const CROSS = '✗';
+
+export const checkCommand = {
+  command:  'check',
+  describe: 'Show full site configuration and health summary',
+  handler:  runCommand(async () => {
+    const [sub, apiStatus] = await Promise.all([
+      getSubscription().catch(() => null),
+      get('/Status').catch(() => null),
+    ]);
+
+    if (!sub) {
+      console.error('Could not retrieve subscription. Check your login: velaro whoami');
+      process.exit(1);
+    }
+
+    const ok  = (msg) => console.log(`  ${TICK}  ${msg}`);
+    const warn = (msg) => console.log(`  ${WARN}  ${msg}`);
+    const off  = (msg) => console.log(`  ${CROSS}  ${msg}`);
+
+    console.log('\n── API Health ────────────────────────────────────────────────');
+    if (apiStatus) {
+      ok(`API reachable`);
+    } else {
+      warn('API did not respond to /Status');
+    }
+
+    // ── Deployments ─────────────────────────────────────────────────────────
+    console.log('\n── Deployments ───────────────────────────────────────────────');
+    try {
+      const [deps, teams] = await Promise.all([get('/Deployment'), get('/Teams/List')]);
+      const teamMap = Object.fromEntries((teams ?? []).map(t => [t.id, t.name]));
+      if (deps?.length) {
+        for (const d of deps) {
+          ok(`[${d.id}] "${d.displayName}"  →  team: ${teamMap[d.teamId] ?? `#${d.teamId}`}  (embed key: ${d.deploymentId})`);
+        }
+      } else {
+        warn('No deployments — create one in the admin UI to get your embed snippet.');
+      }
+    } catch { warn('Could not load deployments'); }
+
+    // ── AI Bots ──────────────────────────────────────────────────────────────
+    console.log('\n── AI Bots ───────────────────────────────────────────────────');
+    if (sub.enableAI) {
+      try {
+        const bots = await get('/AIConfiguration/list');
+        if (bots?.length) {
+          for (const b of bots) ok(`[${b.id}] "${b.name}"  model=${b.aiModel ?? 'default'}`);
+        } else {
+          warn('AI enabled but no bots configured. Run: velaro bot setup --name "My Bot"');
+        }
+      } catch { warn('Could not load bot list'); }
+    } else {
+      off('AI Bots — not on your plan  (upgrade at velaro.com/pricing)');
+    }
+
+    // ── Knowledge Base ───────────────────────────────────────────────────────
+    console.log('\n── Knowledge Base ────────────────────────────────────────────');
+    if (sub.enableKnowledgeBase) {
+      try {
+        const [qna, overrides] = await Promise.all([
+          get('/api/BotQnA').catch(() => []),
+          get('/Ticket/knowledge-overrides').catch(() => []),
+        ]);
+        ok(`${qna?.length ?? 0} Q&A pair(s)  ·  ${overrides?.length ?? 0} override(s)`);
+      } catch { warn('Could not load knowledge base'); }
+    } else {
+      off('Knowledge Base — not on your plan');
+    }
+
+    // ── Workflows ────────────────────────────────────────────────────────────
+    console.log('\n── Workflows ─────────────────────────────────────────────────');
+    if (sub.enableAutomation) {
+      try {
+        const workflows = (await get('/Workflows/List') ?? []).filter(w => !w.isTemplate);
+        const enabled   = workflows.filter(w => w.enabled).length;
+        const disabled  = workflows.length - enabled;
+        if (workflows.length) {
+          ok(`${workflows.length} workflow(s)  ·  ${enabled} enabled  ·  ${disabled} disabled`);
+          for (const w of workflows) {
+            const sym = w.enabled ? TICK : WARN;
+            console.log(`       ${sym}  [${w.id}] "${w.name}"  (${w.enabled ? 'on' : 'off'})`);
+          }
+        } else {
+          warn('Automation enabled but no workflows configured.');
+        }
+      } catch { warn('Could not load workflows'); }
+    } else {
+      off('Workflows — not on your plan');
+    }
+
+    // ── Routing Rules ────────────────────────────────────────────────────────
+    console.log('\n── Routing Rules ─────────────────────────────────────────────');
+    if (sub.enableWorkflowRules) {
+      try {
+        const rules = await get('/Rules/List');
+        if (rules?.length) {
+          ok(`${rules.length} routing rule(s) configured`);
+        } else {
+          warn('Routing rules enabled but none configured.');
+        }
+      } catch { warn('Could not load rules'); }
+    } else {
+      off('Routing Rules — not on your plan');
+    }
+
+    // ── Channels ─────────────────────────────────────────────────────────────
+    console.log('\n── Channels ──────────────────────────────────────────────────');
+    const channels = [
+      ['enableWeb',       'Web Chat'],
+      ['enableSms',       'SMS'],
+      ['enableEmail',     'Email'],
+      ['enableWhatsapp',  'WhatsApp'],
+      ['enableIvr',       'IVR / Voice'],
+      ['enableFacebook',  'Facebook Messenger'],
+      ['enableInstagram', 'Instagram'],
+      ['enableRcs',       'RCS'],
+    ];
+    for (const [flag, label] of channels) {
+      if (sub[flag]) ok(label); else off(`${label} — not on your plan`);
+    }
+
+    // ── IVR detail ───────────────────────────────────────────────────────────
+    if (sub.enableIvr) {
+      try {
+        const ivr = await get('/api/ivr/config');
+        if (ivr?.phoneNumber) {
+          console.log(`\n── IVR Config ────────────────────────────────────────────────`);
+          ok(`Phone: ${ivr.phoneNumber}`);
+          if (ivr.bridgeNumber) ok(`Bridge: ${ivr.bridgeNumber}`);
+          else warn('No bridge (transfer) number set — agents cannot receive transferred calls.');
+        }
+      } catch { /* IVR config is optional */ }
+    }
+
+    // ── Agents ───────────────────────────────────────────────────────────────
+    console.log('\n── Agents ────────────────────────────────────────────────────');
+    try {
+      const agents = await get('/Users/List');
+      const online  = (agents ?? []).filter(a => a.status === 'Available').length;
+      const away    = (agents ?? []).filter(a => a.status === 'Away').length;
+      const offline = (agents ?? []).length - online - away;
+      ok(`${agents?.length ?? 0} agent(s)  ·  ${online} online  ·  ${away} away  ·  ${offline} offline`);
+    } catch { warn('Could not load agents'); }
+
+    console.log('\n──────────────────────────────────────────────────────────────\n');
+  }),
+};

package/lib/commands/deployment.js

@@ -0,0 +1,107 @@
+import { get, post }  from '../api.js';
+import { runCommand } from '../run.js';
+
+export const deploymentCommand = {
+  command:  'deployment <subcommand>',
+  describe: 'Manage chat widget deployments',
+  builder:  (yargs) =>
+    yargs
+      .command(deploymentListCommand)
+      .command(deploymentRenameCommand)
+      .command(deploymentAssignCommand)
+      .demandCommand(1, 'Specify a subcommand: list, rename, assign-team'),
+  handler: () => {},
+};
+
+// ── list ───────────────────────────────────────────────────────────────────────
+
+const deploymentListCommand = {
+  command:  'list',
+  describe: 'List chat widget deployments',
+  handler:  runCommand(async () => {
+    const [deployments, teams] = await Promise.all([
+      get('/Deployment'),
+      get('/Teams/List'),
+    ]);
+
+    if (!deployments?.length) {
+      console.log('No deployments found.');
+      console.log('\nA deployment is a chat widget embed — one per page or team you want to serve.');
+      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('team'.length,      ...rows.map(r => r.team.length));
+
+    console.log(`\n${'id'.padStart(idW)}  ${'embed-key'.padEnd(keyW)}  ${'team'.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} deployment(s)`);
+    console.log('\nThe embed-key goes in your widget JavaScript snippet.');
+  }),
+};
+
+// ── rename ─────────────────────────────────────────────────────────────────────
+
+const deploymentRenameCommand = {
+  command:  'rename <id> <name>',
+  describe: 'Rename a deployment',
+  builder:  (y) =>
+    y
+      .positional('id',   { type: 'number', describe: 'Deployment numeric ID' })
+      .positional('name', { type: 'string', describe: 'New display name' }),
+  handler: runCommand(async (argv) => {
+    const dep = await get(`/Deployment/${argv.id}`);
+    if (!dep) {
+      console.error(`Deployment ${argv.id} not found.`);
+      process.exit(1);
+    }
+
+    await post('/Deployment', { ...dep, id: argv.id, displayName: argv.name });
+    console.log(`Deployment ${argv.id} renamed to "${argv.name}".`);
+  }),
+};
+
+// ── assign-team ────────────────────────────────────────────────────────────────
+
+const deploymentAssignCommand = {
+  command:  'assign-team <id> <team-id>',
+  describe: 'Assign a team to a deployment',
+  builder:  (y) =>
+    y
+      .positional('id',      { type: 'number', describe: 'Deployment numeric ID' })
+      .positional('team-id', { type: 'number', describe: 'Team ID to assign' }),
+  handler: runCommand(async (argv) => {
+    const [dep, teams] = await Promise.all([
+      get(`/Deployment/${argv.id}`),
+      get('/Teams/List'),
+    ]);
+
+    if (!dep) {
+      console.error(`Deployment ${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(`Deployment ${argv.id} ("${dep.displayName}") assigned to team "${team.name}".`);
+  }),
+};

package/lib/commands/kb.js

@@ -0,0 +1,132 @@
+import { get, post, del } from '../api.js';
+import { requireFeature }  from '../subscription.js';
+import { runCommand }      from '../run.js';
+
+export const kbCommand = {
+  command:  'kb <subcommand>',
+  describe: 'Manage knowledge base — Q&A pairs and bot overrides',
+  builder:  (yargs) =>
+    yargs
+      .command(qnaCommand)
+      .command(overrideCommand)
+      .demandCommand(1, 'Specify a subcommand: qna, override'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Q&A
+// ────────────────────────────────────────────────────────────────────────────
+
+const qnaCommand = {
+  command:  'qna <subcommand>',
+  describe: 'Manage Q&A knowledge pairs',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List Q&A pairs',
+        builder:  (y) => y.option('bot-id', { type: 'number', describe: 'Filter by bot ID' }),
+        handler:  runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const params = argv['bot-id'] ? `?aiConfigurationId=${argv['bot-id']}` : '';
+          const items  = await get(`/api/BotQnA${params}`);
+          if (!items?.length) { console.log('No Q&A pairs found.'); return; }
+
+          console.log(`\nFound ${items.length} Q&A pair(s):\n`);
+          for (const item of items) {
+            console.log(`  [${item.id}] Q: ${truncate(item.question, 70)}`);
+            console.log(`       A: ${truncate(item.answer, 70)}\n`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a Q&A pair',
+        builder:  (y) =>
+          y
+            .option('bot-id',   { type: 'number', demandOption: true, describe: 'Bot ID' })
+            .option('question', { type: 'string', demandOption: true, describe: 'Question text' })
+            .option('answer',   { type: 'string', demandOption: true, describe: 'Answer text' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const result = await post('/api/BotQnA', {
+            aiConfigurationId: argv['bot-id'],
+            question:          argv.question,
+            answer:            argv.answer,
+          });
+          console.log(`Q&A pair added: [${result.id}]`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a Q&A pair',
+        builder:  (y) => y.positional('id', { type: 'number', describe: 'Q&A pair ID' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await del(`/api/BotQnA/${argv.id}`);
+          console.log(`Q&A pair ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Overrides — authoritative facts that take priority over KB search
+// ────────────────────────────────────────────────────────────────────────────
+
+const overrideCommand = {
+  command:  'override <subcommand>',
+  describe: 'Manage bot knowledge overrides (authoritative facts)',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command:  'list',
+        describe: 'List knowledge overrides',
+        handler:  runCommand(async () => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const items = await get('/Ticket/knowledge-overrides');
+          if (!items?.length) { console.log('No overrides found.'); return; }
+
+          console.log(`\nFound ${items.length} override(s):\n`);
+          for (const item of items) {
+            const status = item.isActive ? 'active  ' : 'inactive';
+            const expiry = item.expiresAt ? `  expires ${new Date(item.expiresAt).toLocaleDateString()}` : '';
+            console.log(`  [${item.id}] ${status}  ${truncate(item.title ?? item.content, 60)}${expiry}`);
+          }
+        }),
+      })
+      .command({
+        command:  'add',
+        describe: 'Add a knowledge override',
+        builder:  (y) =>
+          y
+            .option('title',   { type: 'string', demandOption: true, describe: 'Override title' })
+            .option('content', { type: 'string', demandOption: true, describe: 'Authoritative content' })
+            .option('expires', { type: 'string',                     describe: 'Expiry date (ISO 8601, e.g. 2026-12-31)' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          const payload = { title: argv.title, content: argv.content, isActive: true };
+          if (argv.expires) payload.expiresAt = new Date(argv.expires).toISOString();
+          const result = await post('/Ticket/knowledge-overrides', payload);
+          console.log(`Override added: [${result.id}] "${argv.title}"`);
+        }),
+      })
+      .command({
+        command:  'delete <id>',
+        describe: 'Delete a knowledge override',
+        builder:  (y) => y.positional('id', { type: 'number', describe: 'Override ID' }),
+        handler: runCommand(async (argv) => {
+          await requireFeature('enableKnowledgeBase', 'Knowledge Base');
+          await del(`/Ticket/knowledge-overrides/${argv.id}`);
+          console.log(`Override ${argv.id} deleted.`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, add, delete'),
+  handler: () => {},
+};
+
+function truncate(str, max) {
+  if (!str) return '—';
+  return str.length <= max ? str : str.slice(0, max - 1) + '…';
+}

package/lib/commands/login.js

@@ -1,19 +1,24 @@
 import { requestDeviceCode, pollForToken, exchangeForVelaroToken } from '../oauth.js';
-import { readConfig, writeConfig, DEFAULT_API_BASE }               from '../config.js';
+import { readConfig, writeConfig, DEFAULT_API_BASE, STAGING_API_BASE } from '../config.js';
 import { runCommand }                                               from '../run.js';
 
 export const loginCommand = {
   command:  'login',
   describe: 'Authenticate with Velaro using your browser',
   builder:  (y) =>
-    y.option('api', {
-      describe: 'Velaro Messaging API base URL',
-      default:  DEFAULT_API_BASE,
-      type:     'string',
-    }),
+    y
+      .option('staging', {
+        describe: 'Connect to the Velaro staging environment',
+        type:     'boolean',
+        default:  false,
+      })
+      .option('api', {
+        describe: 'Override the Velaro API base URL (advanced)',
+        type:     'string',
+      }),
 
   handler: runCommand(async (argv) => {
-    const apiBase = argv.api;
+    const apiBase = argv.api ?? (argv.staging ? STAGING_API_BASE : DEFAULT_API_BASE);
 
     console.log('Starting Velaro login...\n');
 
@@ -36,7 +41,8 @@ export const loginCommand = {
       userName:          velaroResult.profile?.Name,
     });
 
-    console.log(`\nLogged in as ${velaroResult.profile?.Name ?? velaroResult.profile?.UserName}`);
+    const envLabel = argv.staging || argv.api ? ` (${apiBase})` : '';
+    console.log(`\nLogged in as ${velaroResult.profile?.Name ?? velaroResult.profile?.UserName}${envLabel}`);
     console.log(`Site ID: ${velaroResult.profile?.SiteId}`);
     console.log('Credentials saved to ~/.velaro/config.json');
   }),

package/lib/commands/rule.js

@@ -0,0 +1,85 @@
+import { get, post, del } from '../api.js';
+import { requireFeature }  from '../subscription.js';
+import { runCommand }      from '../run.js';
+
+export const ruleCommand = {
+  command:  'rule <subcommand>',
+  describe: 'Manage routing rules',
+  builder:  (yargs) =>
+    yargs
+      .command(ruleListCommand)
+      .command(ruleCreateCommand)
+      .command(ruleDeleteCommand)
+      .demandCommand(1, 'Specify a subcommand: list, create, delete'),
+  handler: () => {},
+};
+
+// ── list ───────────────────────────────────────────────────────────────────────
+
+const ruleListCommand = {
+  command:  'list',
+  describe: 'List all routing rules',
+  handler:  runCommand(async () => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+
+    const rules = await get('/Rules/List');
+    if (!rules?.length) { console.log('No routing rules found.'); return; }
+
+    const sorted = [...rules].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+    const idW    = Math.max(...sorted.map(r => String(r.id).length + 2));
+    const priW   = Math.max('pri'.length, ...sorted.map(r => String(r.priority ?? 0).length));
+    const nameW  = Math.max('name'.length, ...sorted.map(r => (r.name ?? r.trigger ?? '—').length));
+
+    console.log(`\n${'id'.padStart(idW)}  ${'pri'.padEnd(priW)}  ${'name'.padEnd(nameW)}  trigger`);
+    console.log(`${'-'.repeat(idW)}  ${'-'.repeat(priW)}  ${'-'.repeat(nameW)}  -------`);
+    for (const r of sorted) {
+      const id   = `[${r.id}]`.padStart(idW);
+      const pri  = String(r.priority ?? 0).padEnd(priW);
+      const name = (r.name ?? r.trigger ?? '—').padEnd(nameW);
+      console.log(`${id}  ${pri}  ${name}  ${r.trigger ?? '—'}`);
+    }
+    console.log(`\n${sorted.length} rule(s)`);
+  }),
+};
+
+// ── create ─────────────────────────────────────────────────────────────────────
+
+const ruleCreateCommand = {
+  command:  'create',
+  describe: 'Create a routing rule',
+  builder:  (y) =>
+    y
+      .option('name',       { type: 'string', demandOption: true, describe: 'Rule name' })
+      .option('trigger',    { type: 'string', demandOption: true, describe: 'Trigger type (e.g. pageUrl, country)' })
+      .option('value',      { type: 'string', demandOption: true, describe: 'Trigger value to match' })
+      .option('team-id',    { type: 'number', demandOption: true, describe: 'Team ID to route to' })
+      .option('priority',   { type: 'number', default: 0,         describe: 'Rule priority (lower = higher priority)' }),
+
+  handler: runCommand(async (argv) => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+
+    const result = await post('/Rules', {
+      name:      argv.name,
+      trigger:   argv.trigger,
+      value:     argv.value,
+      teamId:    argv['team-id'],
+      priority:  argv.priority,
+      isEnabled: true,
+    });
+
+    console.log(`Rule created: [${result.id}] ${result.name}`);
+  }),
+};
+
+// ── delete ─────────────────────────────────────────────────────────────────────
+
+const ruleDeleteCommand = {
+  command:  'delete <id>',
+  describe: 'Delete a routing rule',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Rule ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableWorkflowRules', 'Routing Rules');
+    await del(`/Rules/${argv.id}`);
+    console.log(`Rule ${argv.id} deleted.`);
+  }),
+};

package/lib/commands/site.js

@@ -0,0 +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`);
+  }),
+};

package/lib/commands/team.js

@@ -0,0 +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.');
+  }),
+};

package/lib/commands/update.js

@@ -0,0 +1,47 @@
+import { execSync }    from 'child_process';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { version: currentVersion } = require('../../package.json');
+
+const NPM_REGISTRY = 'https://registry.npmjs.org/@velaro/cli/latest';
+
+export const updateCommand = {
+  command:  'update',
+  describe: 'Update the Velaro CLI to the latest version',
+  handler:  async () => {
+    process.stdout.write('Checking for updates... ');
+
+    let latest;
+    try {
+      const res = await fetch(NPM_REGISTRY, { signal: AbortSignal.timeout(8000) });
+      const data = await res.json();
+      latest = data?.version;
+    } catch {
+      console.error('Could not reach npm registry. Check your connection and try again.');
+      process.exit(1);
+    }
+
+    if (!latest) {
+      console.error('Could not determine the latest version.');
+      process.exit(1);
+    }
+
+    if (latest === currentVersion) {
+      console.log(`already up to date (${currentVersion}).`);
+      return;
+    }
+
+    console.log(`${currentVersion} → ${latest}`);
+    console.log('Running: npm install -g @velaro/cli@latest\n');
+
+    try {
+      execSync('npm install -g @velaro/cli@latest', { stdio: 'inherit' });
+      console.log('\nUpdated successfully. Run velaro --version to confirm.');
+    } catch {
+      console.error('\nUpdate failed. Try running manually:');
+      console.error('  npm install -g @velaro/cli@latest');
+      process.exit(1);
+    }
+  },
+};

package/lib/commands/workflow.js

@@ -0,0 +1,98 @@
+import { get, post }      from '../api.js';
+import { requireFeature } from '../subscription.js';
+import { runCommand }     from '../run.js';
+
+export const workflowCommand = {
+  command:  'workflow <subcommand>',
+  describe: 'Manage automation workflows',
+  builder:  (yargs) =>
+    yargs
+      .command(workflowListCommand)
+      .command(workflowGetCommand)
+      .command(workflowEnableCommand)
+      .command(workflowDisableCommand)
+      .demandCommand(1, 'Specify a subcommand: list, get, enable, disable'),
+  handler: () => {},
+};
+
+// ── list ───────────────────────────────────────────────────────────────────────
+
+const workflowListCommand = {
+  command:  'list',
+  describe: 'List all workflows',
+  handler:  runCommand(async () => {
+    await requireFeature('enableAutomation', 'Workflows');
+
+    const workflows = await get('/Workflows/List');
+    const rows = (workflows ?? []).filter(w => !w.isTemplate);
+
+    if (!rows.length) { console.log('No workflows found.'); return; }
+
+    const idW      = Math.max(...rows.map(w => String(w.id).length + 2));
+    const triggerW = Math.max('trigger'.length, ...rows.map(w => (w.triggerType ?? '—').length));
+
+    console.log(`\n${'id'.padStart(idW)}  status    ${'trigger'.padEnd(triggerW)}  name`);
+    console.log(`${'-'.repeat(idW)}  --------  ${'-'.repeat(triggerW)}  ----`);
+    for (const w of rows) {
+      const id      = `[${w.id}]`.padStart(idW);
+      const status  = w.enabled ? 'enabled ' : 'disabled';
+      const trigger = (w.triggerType ?? '—').padEnd(triggerW);
+      console.log(`${id}  ${status}  ${trigger}  ${w.name}`);
+    }
+    console.log(`\n${rows.length} workflow(s)`);
+  }),
+};
+
+// ── get ────────────────────────────────────────────────────────────────────────
+
+const workflowGetCommand = {
+  command:  'get <id>',
+  describe: 'Show workflow details',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Workflow ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableAutomation', 'Workflows');
+
+    const w = await get(`/Workflows/${argv.id}`);
+    if (!w) { console.error(`Workflow ${argv.id} not found.`); process.exit(1); }
+
+    console.log(`\n[${w.id}] ${w.name}`);
+    console.log(`  Status:  ${w.enabled ? 'enabled' : 'disabled'}`);
+    console.log(`  Trigger: ${w.triggerType ?? '—'}`);
+    if (w.nodes?.length) {
+      console.log(`  Nodes:   ${w.nodes.length}`);
+    }
+  }),
+};
+
+// ── enable / disable ──────────────────────────────────────────────────────────
+
+const workflowEnableCommand = {
+  command:  'enable <id>',
+  describe: 'Enable a workflow',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Workflow ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableAutomation', 'Workflows');
+    await post(`/Workflows/toggle/${argv.id}`, null);
+    console.log(`Workflow ${argv.id} enabled.`);
+  }),
+};
+
+const workflowDisableCommand = {
+  command:  'disable <id>',
+  describe: 'Disable a workflow',
+  builder:  (y) => y.positional('id', { type: 'number', describe: 'Workflow ID' }),
+  handler:  runCommand(async (argv) => {
+    await requireFeature('enableAutomation', 'Workflows');
+
+    const w = await get(`/Workflows/${argv.id}`);
+    if (!w) { console.error(`Workflow ${argv.id} not found.`); process.exit(1); }
+
+    if (!w.enabled) {
+      console.log(`Workflow ${argv.id} is already disabled.`);
+      return;
+    }
+
+    await post(`/Workflows/toggle/${argv.id}`, null);
+    console.log(`Workflow ${argv.id} disabled.`);
+  }),
+};

package/lib/config.js

@@ -1,25 +1,26 @@
-import { homedir } from 'os';
-import { join }    from 'path';
-import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-
-const CONFIG_DIR  = join(homedir(), '.velaro');
-const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
-
-export const DEFAULT_API_BASE = process.env.VELARO_API_BASE || 'https://velaro-messaging-api-prod.azurewebsites.net';
-
-export function readConfig() {
-  try {
-    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-export function writeConfig(data) {
-  mkdirSync(CONFIG_DIR, { recursive: true }); // no-op if already exists
-  writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
-}
-
-export function clearConfig() {
-  writeConfig({});
-}
+import { homedir } from 'os';
+import { join }    from 'path';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+const CONFIG_DIR  = join(homedir(), '.velaro');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export const DEFAULT_API_BASE   = process.env.VELARO_API_BASE   || 'https://messaging.velaro.com';
+export const STAGING_API_BASE  = process.env.VELARO_STAGING_API || 'https://velaro-messaging-api-staging.azurewebsites.net';
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(data) {
+  mkdirSync(CONFIG_DIR, { recursive: true }); // no-op if already exists
+  writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+export function clearConfig() {
+  writeConfig({});
+}

package/lib/subscription.js

@@ -0,0 +1,39 @@
+/**
+ * Subscription helpers for CLI commands.
+ * Provides a clean gate that prints a plan upgrade message instead of
+ * throwing a confusing 403/400 from the API.
+ */
+
+import { get } from './api.js';
+
+let _cachedSub = null;
+
+export async function getSubscription() {
+  if (!_cachedSub) {
+    _cachedSub = await get('/Subscription');
+  }
+  return _cachedSub;
+}
+
+/**
+ * Throws an Error with a friendly upgrade message if the feature flag is off.
+ * Usage: await requireFeature('enableAI', 'AI Bots');
+ */
+export async function requireFeature(flag, featureName) {
+  const sub = await getSubscription();
+  if (!sub[flag]) {
+    throw new Error(
+      `${featureName} is not enabled on your plan.\n` +
+      `  Upgrade at https://velaro.com/pricing or contact sales@velaro.com.`
+    );
+  }
+  return sub;
+}
+
+/**
+ * Returns true/false without throwing — for check/status commands.
+ */
+export async function hasFeature(flag) {
+  const sub = await getSubscription();
+  return sub[flag] === true;
+}

package/lib/update-check.js

@@ -0,0 +1,64 @@
+/**
+ * Non-blocking update checker.
+ * Fetches the latest version from npm once per day (cached in ~/.velaro/config.json).
+ * Prints a one-line notice AFTER the command completes if a newer version is available.
+ */
+
+import { readConfig, writeConfig } from './config.js';
+import { createRequire }           from 'module';
+
+const require = createRequire(import.meta.url);
+const { version: currentVersion } = require('../package.json');
+
+const NPM_REGISTRY      = 'https://registry.npmjs.org/@velaro/cli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // once per day
+
+/**
+ * Starts the update check in the background.
+ * Returns a function you await AFTER your command finishes to print any notice.
+ */
+export function startUpdateCheck() {
+  const cfg      = readConfig();
+  const lastCheck = cfg._lastUpdateCheck ?? 0;
+  const now       = Date.now();
+
+  if (now - lastCheck < CHECK_INTERVAL_MS) {
+    // Use cached result — no network call
+    return async () => printNoticeIfStale(cfg._latestVersion);
+  }
+
+  // Fire off the network request without awaiting it here
+  const fetchPromise = fetch(NPM_REGISTRY, { signal: AbortSignal.timeout(4000) })
+    .then((r) => r.json())
+    .then((data) => {
+      const latest = data?.version ?? null;
+      writeConfig({ ...readConfig(), _lastUpdateCheck: now, _latestVersion: latest });
+      return latest;
+    })
+    .catch(() => null); // never block the CLI on a network failure
+
+  return async () => {
+    const latest = await fetchPromise;
+    printNoticeIfStale(latest);
+  };
+}
+
+function printNoticeIfStale(latest) {
+  if (!latest || latest === currentVersion) return;
+  if (!isNewer(latest, currentVersion)) return;
+
+  process.stderr.write(
+    `\n  Update available: ${currentVersion} → ${latest}\n` +
+    `  Run: npm install -g @velaro/cli@latest\n\n`
+  );
+}
+
+function isNewer(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+  }
+  return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, and MCP API keys.",
   "type": "module",
   "bin": {