@velaro/cli 0.7.0 → 1.4.8

package/README.md

@@ -1,138 +1,161 @@
-# Velaro CLI
-
-Command-line interface for managing your Velaro account — bots, knowledge base ingestion, and MCP API keys.
-
-## Installation
-
-```bash
-npm install -g @velaro/cli
-```
-
-Or run without installing:
-
-```bash
-npx @velaro/cli login
-```
-
-> Requires Node.js 18 or later.
-
-## Authentication
-
-Velaro CLI uses your existing Velaro account — the same login you use in the admin portal. No separate API key or password required.
-
-```bash
-velaro login
-```
-
-This opens your browser to a short code page. Enter the code shown in the terminal, sign in with your Velaro account, and you're done. Your session is saved to `~/.velaro/config.json` and refreshes automatically — you won't need to log in again for months.
-
-```bash
-velaro logout     # clear saved credentials
-velaro whoami     # confirm who you're logged in as
-```
-
-## Commands
-
-### `velaro bot list`
-List all AI bots configured on your site.
-
-```
-[42] Support Bot    model=velaro-gpt-4o-mini  status=ready
-[43] Sales Bot      model=velaro-gpt-4o-mini  status=ready
-```
-
-### `velaro bot setup`
-Create or update an AI bot (upsert by name).
-
-```bash
-velaro bot setup \
-  --name "Support Bot" \
-  --prompt "You are a helpful support assistant for Acme Corp..." \
-  --tone Professional \
-  --reply-length Medium \
-  --urls "https://help.acme.com,https://acme.com/faq"
-```
-
-Options:
-| Flag | Description | Default |
-|---|---|---|
-| `--name` | Bot name (required) | — |
-| `--prompt` | System prompt | — |
-| `--model` | AI model | `velaro-gpt-4o-mini` |
-| `--tone` | `Professional`, `Friendly`, `Formal`, `Casual` | `Professional` |
-| `--reply-length` | `Short`, `Medium`, `Long` | `Medium` |
-| `--urls` | Comma-separated knowledge base URLs | — |
-
-### `velaro ingest --job-id <id>`
-Trigger knowledge base ingestion for a completed scraper job. The job runs in the background — embedding 50+ pages typically takes 1–2 minutes.
-
-```bash
-velaro ingest --job-id d2d93504
-```
-
-> Requires the **Knowledge Base** feature on your subscription.
-
-### `velaro mcp-key list`
-List MCP API keys for your site (used to connect AI tools like Claude).
-
-```
-[1] Claude Code    prefix=vel_live_aB4  active  last used=4/9/2026
-[2] Zapier         prefix=vel_live_xC7  active  last used=never
-```
-
-### `velaro mcp-key create --label <label>`
-Create a new MCP API key. The full key is shown **once** — copy it immediately.
-
-```bash
-velaro mcp-key create --label "Claude Code"
-velaro mcp-key create --label "Zapier" --expires 2027-01-01
-```
-
-### `velaro mcp-key revoke <id>`
-Revoke an MCP key by ID.
-
-```bash
-velaro mcp-key revoke 2
-```
-
-### `velaro status`
-Check that the Velaro API is reachable.
-
-```bash
-velaro status
-# Checking https://velaro-messaging-api-staging.azurewebsites.net/Status ... OK
-```
-
-## Environment variables
-
-| Variable | Description |
-|---|---|
-| `VELARO_API_BASE` | Override the API base URL (defaults to production) |
-| `VELARO_CLI_CLIENT_ID` | Override the Entra app ID (advanced) |
-
-## What the CLI can access
-
-The CLI operates under your Velaro account with the same permissions you have in the admin portal. It can only access **your own site's data** — it is not possible to read or modify another customer's account.
-
-Feature access is gated by your subscription plan:
-- **Bot setup** — requires the AI feature on your plan
-- **KB ingestion** — requires the Knowledge Base feature
-- **MCP keys** — requires the MCP API Access feature
-
-## Security
-
-- Login uses OAuth 2.0 device authorization (RFC 8628) — no password is ever stored
-- Credentials are saved to `~/.velaro/config.json` with owner-only permissions (`0600`)
-- Your Velaro JWT expires after 1 hour and is silently refreshed using a secure refresh token
-- All API calls go over HTTPS to `velaro-messaging-api.azurewebsites.net`
-
-## Publishing (internal)
-
-The CLI lives in `velaro-admin/cli/`. To publish to npm:
-
-```bash
-cd cli
-npm publish --access public
-```
-
-Requires `npm login` with the `@velaro` organization access.
+# Velaro CLI
+
+Command-line interface for managing your Velaro account — bots, knowledge base ingestion, and MCP API keys.
+
+## Installation
+
+```bash
+npm install -g @velaro/cli
+```
+
+Or run without installing:
+
+```bash
+npx @velaro/cli login
+```
+
+> Requires Node.js 18 or later.
+
+## Authentication
+
+Velaro CLI uses your existing Velaro account — the same login you use in the admin portal. No separate API key or password required.
+
+```bash
+velaro login
+```
+
+This opens your browser to a short code page. Enter the code shown in the terminal, sign in with your Velaro account, and you're done. Your session is saved to `~/.velaro/config.json` and refreshes automatically — you won't need to log in again for months.
+
+```bash
+velaro logout     # clear saved credentials
+velaro whoami     # confirm who you're logged in as
+```
+
+## Commands
+
+### `velaro bot list`
+List all AI bots configured on your site.
+
+```
+[42] Support Bot    model=velaro-gpt-4o-mini  status=ready
+[43] Sales Bot      model=velaro-gpt-4o-mini  status=ready
+```
+
+### `velaro bot setup`
+Create or update an AI bot (upsert by name).
+
+```bash
+velaro bot setup \
+  --name "Support Bot" \
+  --prompt "You are a helpful support assistant for Acme Corp..." \
+  --tone Professional \
+  --reply-length Medium \
+  --urls "https://help.acme.com,https://acme.com/faq"
+```
+
+Options:
+| Flag | Description | Default |
+|---|---|---|
+| `--name` | Bot name (required) | — |
+| `--prompt` | System prompt | — |
+| `--model` | AI model | `velaro-gpt-4o-mini` |
+| `--tone` | `Professional`, `Friendly`, `Formal`, `Casual` | `Professional` |
+| `--reply-length` | `Short`, `Medium`, `Long` | `Medium` |
+| `--urls` | Comma-separated knowledge base URLs | — |
+
+### `velaro ingest --job-id <id>`
+Trigger knowledge base ingestion for a completed scraper job. The job runs in the background — embedding 50+ pages typically takes 1–2 minutes.
+
+```bash
+velaro ingest --job-id d2d93504
+```
+
+> Requires the **Knowledge Base** feature on your subscription.
+
+### `velaro mcp-key list`
+List MCP API keys for your site (used to connect AI tools like Claude).
+
+```
+[1] Claude Code    prefix=vel_live_aB4  active  last used=4/9/2026
+[2] Zapier         prefix=vel_live_xC7  active  last used=never
+```
+
+### `velaro mcp-key create --label <label>`
+Create a new MCP API key. The full key is shown **once** — copy it immediately.
+
+```bash
+velaro mcp-key create --label "Claude Code"
+velaro mcp-key create --label "Zapier" --expires 2027-01-01
+```
+
+### `velaro mcp-key revoke <id>`
+Revoke an MCP key by ID.
+
+```bash
+velaro mcp-key revoke 2
+```
+
+### `velaro kb article <subcommand>`
+Manage your help.velaro.com knowledge base articles. Full reference (including the REST/MCP equivalents and the screenshot pipeline): [`docs/architecture/kb-publishing-system.md`](../docs/architecture/kb-publishing-system.md).
+
+```bash
+velaro kb article topics                                  # list topics (get a topicId first)
+velaro kb article list --search "smart routing"            # search/list articles
+velaro kb article get 1234                                 # fetch one article
+velaro kb article push ./my-article.md --topic-id 4 --publish   # create (or --update-id to update)
+velaro kb article preview 1234                             # render an article's HTML locally
+velaro kb article improve 1234 --instruction "add a troubleshooting section" --publish
+velaro kb article seed-views 1234                          # seed a realistic view count (new articles)
+velaro kb article delete 1234
+
+# Grab a real screenshot off staging, polish it, and drop it into an article:
+velaro kb article screenshot 1234 \
+  --app admin \
+  --route "/Settings/SmartRouting" \
+  --heading "Turning on Smart Routing" \
+  --annotate 120,80,1
+```
+
+> Titles are auto-normalized to Title Case with no dashes, even if you pass a slug-style name — use `--no-title-normalize` to skip that.
+
+### `velaro status`
+Check that the Velaro API is reachable.
+
+```bash
+velaro status
+# Checking https://velaro-messaging-api-staging.azurewebsites.net/Status ... OK
+```
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `VELARO_API_BASE` | Override the API base URL (defaults to production) |
+| `VELARO_CLI_CLIENT_ID` | Override the Entra app ID (advanced) |
+
+## What the CLI can access
+
+The CLI operates under your Velaro account with the same permissions you have in the admin portal. It can only access **your own site's data** — it is not possible to read or modify another customer's account.
+
+Feature access is gated by your subscription plan:
+- **Bot setup** — requires the AI feature on your plan
+- **KB ingestion** — requires the Knowledge Base feature
+- **MCP keys** — requires the MCP API Access feature
+
+## Security
+
+- Login uses OAuth 2.0 device authorization (RFC 8628) — no password is ever stored
+- Credentials are saved to `~/.velaro/config.json` with owner-only permissions (`0600`)
+- Your Velaro JWT expires after 1 hour and is silently refreshed using a secure refresh token
+- All API calls go over HTTPS to `velaro-messaging-api.azurewebsites.net`
+
+## Publishing (internal)
+
+The CLI lives in `velaro-admin/cli/`. To publish to npm:
+
+```bash
+cd cli
+npm publish --access public
+```
+
+Requires `npm login` with the `@velaro` organization access.

package/bin/velaro.js

@@ -1,62 +1,177 @@
-#!/usr/bin/env node
-
-import yargs                                    from 'yargs';
-import { hideBin }                              from 'yargs/helpers';
-import { loginCommand, logoutCommand }          from '../lib/commands/login.js';
-import { envCommand }                           from '../lib/commands/env.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 { indexCommand }                          from '../lib/commands/index.js';
-import { opsCommand }                           from '../lib/commands/ops.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';
-
-// 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)
-  .command(envCommand)
-  // Info
-  .command(siteCommand)
-  .command(checkCommand)
-  .command(statusCommand)
-  // Config
-  .command(teamCommand)
-  .command(botCommand)
-  .command(kbCommand)
-  .command(workflowCommand)
-  .command(ruleCommand)
-  .command(agentCommand)
-  // Integrations / keys / indexes
-  .command(ingestCommand)
-  .command(mcpKeyCommand)
-  .command(indexCommand)
-  .command(opsCommand)
-  // 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))
-  .parseAsync();
-
-// Print update notice after command output (non-intrusive)
-await printUpdateNotice();
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { loginCommand, logoutCommand } from '../lib/commands/login.js';
+import { envCommand }        from '../lib/commands/env.js';
+import { whoamiCommand }     from '../lib/commands/whoami.js';
+import { kbCommand }         from '../lib/commands/kb.js';
+import { botCommand }        from '../lib/commands/bot.js';
+import { indexCommand }      from '../lib/commands/index.js';
+import { ingestCommand }     from '../lib/commands/ingest.js';
+import { productCommand }    from '../lib/commands/product.js';
+import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
+import { opsCommand }        from '../lib/commands/ops.js';
+import { checkCommand }      from '../lib/commands/check.js';
+import { logsCommand }       from '../lib/commands/logs.js';
+import { aiModelsCommand }   from '../lib/commands/ai-models.js';
+import { siteCommand }       from '../lib/commands/site.js';
+import { siteProvisionCommand } from '../lib/commands/site-provision.js';
+import { siteSyncCommand }   from '../lib/commands/sitesync.js';
+import { statusCommand }     from '../lib/commands/status.js';
+import { activityCommand }   from '../lib/commands/activity.js';
+import { ruleCommand }       from '../lib/commands/rule.js';
+import { teamCommand }       from '../lib/commands/team.js';
+import { workflowCommand }   from '../lib/commands/workflow.js';
+import { aiConfigCommand }   from '../lib/commands/ai-config.js';
+import { deploymentCommand } from '../lib/commands/deployment.js';
+import { updateCommand }     from '../lib/commands/update.js';
+import { agentCommand }      from '../lib/commands/agent.js';
+import { notificationsCommand } from '../lib/commands/notifications.js';
+import { articleCommand }    from '../lib/commands/article.js';
+import { sharepointCommand } from '../lib/commands/sharepoint.js';
+import { calendlyCommand }   from '../lib/commands/calendly.js';
+import { copilotStudioCommand } from '../lib/commands/copilotstudio.js';
+import { acuityCommand }     from '../lib/commands/acuity.js';
+import { avatarCommand }     from '../lib/commands/avatar.js';
+import { integrationCommand } from '../lib/commands/integration.js';
+import { appointmentsCommand } from '../lib/commands/appointments.js';
+import { reportCommand }       from '../lib/commands/report.js';
+import { conversationEfficiencyCommand } from '../lib/commands/conversation-efficiency.js';
+import { dbCommand } from '../lib/commands/db.js';
+import { focusCommand }       from '../lib/commands/focus.js';
+import { automationDraftCommand } from '../lib/commands/automation-draft.js';
+import { magentoCommand }       from '../lib/commands/magento.js';
+import { mondayCommand }        from '../lib/commands/monday.js';
+import { notionCommand }        from '../lib/commands/notion.js';
+import { callrailCommand }      from '../lib/commands/callrail.js';
+import { emailCampaignCommand } from '../lib/commands/email-campaign.js';
+import { telephonyCommand }     from '../lib/commands/telephony.js';
+import { teamsPhoneCommand }    from '../lib/commands/teams-phone.js';
+import { teamsCommand }         from '../lib/commands/teams.js';
+import { slackCommand }         from '../lib/commands/slack.js';
+import { webflowCommand }        from '../lib/commands/webflow.js';
+import { netsuiteCommand }      from '../lib/commands/netsuite.js';
+import { woocommerceCommand }  from '../lib/commands/woocommerce.js';
+import { squarespaceCommand }  from '../lib/commands/squarespace.js';
+import { bigcommerceCommand }  from '../lib/commands/bigcommerce.js';
+import { migrateCommand }     from '../lib/commands/migrate.js';
+import { migrationStatusCommand } from '../lib/commands/migration-status.js';
+import { complianceCommand }      from '../lib/commands/compliance.js';
+import { billingContactsCommand } from '../lib/commands/billing-contacts.js';
+import { billingSubscriptionCommand } from '../lib/commands/billing-subscription.js';
+import { billingEmailPreferenceCommand } from '../lib/commands/billing-email-preference.js';
+import { billingCommand }         from '../lib/commands/billing.js';
+import { couponGrantCommand }     from '../lib/commands/coupon-grant.js';
+import { widgetContainerCommand }  from '../lib/commands/widget-container.js';
+import { inlineWidgetConfigCommand } from '../lib/commands/inline-widget-config.js';
+import { pricingCommand }          from '../lib/commands/pricing.js';
+import { entitlementCommand }       from '../lib/commands/entitlement.js';
+import { subscriptionCommand }      from '../lib/commands/subscription.js';
+import { supportCommand }           from '../lib/commands/support.js';
+import { routingCommand }           from '../lib/commands/routing.js';
+import { diagnosticsCommand }       from '../lib/commands/diagnostics.js';
+import { emailInboxCommand }        from '../lib/commands/email-inbox.js';
+import { callbackCommand }          from '../lib/commands/callback.js';
+import { caseCommand }              from '../lib/commands/case.js';
+import { pickupCommand }            from '../lib/commands/pickup.js';
+import { paymentRecoveryCommand }   from '../lib/commands/payment-recovery.js';
+import { recruitingCommand }        from '../lib/commands/recruiting.js';
+import { surveyCommand }            from '../lib/commands/survey.js';
+import { bundleCommand }            from '../lib/commands/bundle.js';
+import { featureDiscoveryCommand }  from '../lib/commands/feature-discovery.js';
+import { campaignsCommand }         from '../lib/commands/campaigns.js';
+import { startUpdateCheck }  from '../lib/update-check.js';
+import { printBannerIfFirstRun } from '../lib/banner.js';
+
+printBannerIfFirstRun();
+
+startUpdateCheck();
+
+yargs(hideBin(process.argv))
+  .scriptName('velaro')
+  .usage('$0 <command> [options]')
+  .command(loginCommand)
+  .command(logoutCommand)
+  .command(envCommand)
+  .command(whoamiCommand)
+  .command(kbCommand)
+  .command(botCommand)
+  .command(indexCommand)
+  .command(ingestCommand)
+  .command(productCommand)
+  .command(mcpKeyCommand)
+  .command(opsCommand)
+  .command(checkCommand)
+  .command(logsCommand)
+  .command(aiModelsCommand)
+  .command(siteCommand)
+  .command(siteProvisionCommand)
+  .command(siteSyncCommand)
+  .command(statusCommand)
+  .command(activityCommand)
+  .command(ruleCommand)
+  .command(teamCommand)
+  .command(workflowCommand)
+  .command(aiConfigCommand)
+  .command(deploymentCommand)
+  .command(updateCommand)
+  .command(agentCommand)
+  .command(notificationsCommand)
+  .command(articleCommand)
+  .command(sharepointCommand)
+  .command(calendlyCommand)
+  .command(copilotStudioCommand)
+  .command(acuityCommand)
+  .command(avatarCommand)
+  .command(integrationCommand)
+  .command(appointmentsCommand)
+  .command(reportCommand)
+  .command(conversationEfficiencyCommand)
+  .command(dbCommand)
+  .command(focusCommand)
+  .command(automationDraftCommand)
+  .command(magentoCommand)
+  .command(mondayCommand)
+  .command(notionCommand)
+  .command(callrailCommand)
+  .command(emailCampaignCommand)
+  .command(telephonyCommand)
+  .command(teamsPhoneCommand)
+  .command(teamsCommand)
+  .command(slackCommand)
+  .command(webflowCommand)
+  .command(netsuiteCommand)
+  .command(woocommerceCommand)
+  .command(squarespaceCommand)
+  .command(bigcommerceCommand)
+  .command(migrateCommand)
+  .command(migrationStatusCommand)
+  .command(complianceCommand)
+  .command(billingContactsCommand)
+  .command(billingSubscriptionCommand)
+  .command(billingEmailPreferenceCommand)
+  .command(billingCommand)
+  .command(couponGrantCommand)
+  .command(widgetContainerCommand)
+  .command(inlineWidgetConfigCommand)
+  .command({ command: 'pricing', desc: 'View and manage the pricing catalog', builder: pricingCommand, handler: () => {} })
+  .command({ command: 'entitlement', desc: 'Query and manage site feature entitlements (superadmin only)', builder: entitlementCommand, handler: () => {} })
+  .command({ command: 'subscription', desc: 'Apply/diff SubscriptionPackage packages on a site (superadmin only)', builder: subscriptionCommand, handler: () => {} })
+  .command({ command: 'support', desc: 'Staff SupportTools actions on a site (superadmin only)', builder: supportCommand, handler: () => {} })
+  .command(routingCommand)
+  .command(diagnosticsCommand)
+  .command(emailInboxCommand)
+  .command(callbackCommand)
+  .command(caseCommand)
+  .command(pickupCommand)
+  .command(paymentRecoveryCommand)
+  .command(recruitingCommand)
+  .command(surveyCommand)
+  .command(bundleCommand)
+  .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
+  .command(campaignsCommand)
+  .demandCommand(1, 'Specify a command. Run "velaro --help" for options.')
+  .strict()
+  .help()
+  .argv;