Velaro CLI

Command-line interface for managing your Velaro account — bots, knowledge base ingestion, and MCP API keys.

Installation

npm install -g @velaro/cli

Or run without installing:

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.

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.

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).

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.

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.

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.

velaro mcp-key revoke 2

velaro mcp-key rotate <id|label>

Create a replacement key, show its value once, then revoke the matched key. The replacement keeps the old expiry unless --expires is supplied. Update every client using the old key; the command does not edit client configurations.

velaro mcp-key rotate 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.

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.

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:

cd cli
npm publish --access public

Requires npm login with the @velaro organization access.