CLI and Configuration Deployment

The CLI creates, validates, deploys, promotes, and rolls back immutable ChattyBox configuration versions. Deployment tokens are scoped to one project and selected environments, making the same workflow suitable for local development and CI.

Create a Configuration

bunx @openstaticfish/chattybox-cli init

This creates chattybox.config.json:

{
  "schemaVersion": "1",
  "assistant": {
    "name": "Support"
  },
  "knowledge": {
    "sources": [
      {
        "type": "website",
        "url": "https://example.com"
      }
    ]
  },
  "widget": {
    "enabled": true
  }
}

Use a custom path when the config belongs in a subdirectory:

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Validate Locally or in CI

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

Validation checks the schema, required assistant name, supported source types, HTTP source URLs, positive page limits, and widget colors. A successful validation does not deploy or modify remote state.

Create a Deployment Token

Open the project Settings tab, find Config deployment tokens, and create a token for the environments your workflow may change. Copy it immediately; ChattyBox stores only its hash and cannot show it again.

Set the token and the widget API URL from the project's Embed tab:

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Never commit the token. Store it in your CI provider's encrypted secret store.

After verifying the deployment workflow, enable Config-as-code lock in the same settings section. The lock disables dashboard configuration and corpus mutations so only scoped deployment tokens can change the runtime. Token creation and revocation remain available if a CI credential needs to be rotated.

Deploy Configuration

Deploying creates an immutable version and promotes it to the selected environment:

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

Development and preview promotions are recorded for review. Production promotions atomically apply the assistant prompt, fallback response, widget settings, locale, and website source to the live project. Production configuration must contain exactly one website source. A deployment queues a version-bound, in-place corpus refresh and regenerates embeddings. The last known-good indexed content remains available if the refresh fails. The current runtime rejects multi-source configurations.

Use --json in automation to receive the version, environment, application status, and scrape job ID as structured output.

Status, Promotion, and Rollback

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
  --version '<config-version-id>' \
  --environment production

bunx @openstaticfish/chattybox-cli rollback \
  --version '<known-good-config-version-id>' \
  --environment production

Rollback promotes and reapplies an older immutable version; it never rewrites deployment history. It restores configuration immediately, while any required content refresh continues asynchronously.

GitHub Actions

- name: Deploy ChattyBox configuration
  env:
    CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
    CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
  run: bunx @openstaticfish/chattybox-cli deploy --environment production --json

Use an environment-scoped production secret and require deployment approval when your repository supports it. The CLI records common CI commit and branch variables with the immutable version.

Configuration Sections

Section	Purpose
schemaVersion	Selects the public configuration contract. Version 1 is currently supported.
assistant	Names the assistant and optionally defines its prompt profile and system prompt.
knowledge.sources	Declares website sources and optional include/exclude patterns.
runtime	Holds runtime defaults such as locale.
widget	Describes optional hosted-widget presentation settings.

Typed Configuration Helper

Install the configuration package when building separate TypeScript tooling around the schema:

bun add -d @openstaticfish/chattybox-config

import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
  schemaVersion: '1',
  assistant: { name: 'Support' },
  knowledge: {
    sources: [{ type: 'website', url: 'https://docs.example.com' }],
  },
  widget: { enabled: true },
});

The CLI reads JSON files. defineConfig() is for typed application or build tooling; it does not make TypeScript files directly loadable by the CLI.

For a working production integration today, use the hosted widget or build a custom interface with the JavaScript SDK.