CLI and Configuration Deployment

The CLI creates, validates, deploys, promotes, and rolls back immutable ChattyBox configuration versions. Each deployment token is scoped to exactly one existing project and selected environments. Treat one config file plus one project-scoped token as one managed ChattyBox project.

What Config as Code Manages

The config controls the project's description, assistant persona and fallback behavior, complete website discovery and refresh policy, locale behavior, and hosted-widget presentation. A preview or production deployment applies those values and refreshes the project's indexed corpus. With Config-as-code lock enabled, these runtime settings are changed through versioned deployments rather than dashboard forms.

Initial project creation is currently a one-time dashboard step. Credentials and operational data stay outside configuration: public widget keys and allowed origins, deployment-token lifecycle, analytics/conversations/content gaps, destructive actions, and uploaded icon files are not config fields. Use a URL or emoji for a declarative custom icon. The config intentionally contains no project ID: the secret deployment token selects the one project that receives it.

Credential	Scope	Safe in browser code?
Public widget API key	Chat and widget configuration	Yes; restrict allowed origins
Config deployment token	Project management and selected environments	No; keep in local/CI secrets

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 promotions are recorded for review without changing runtime state. Preview and production promotions atomically apply the assistant prompt, fallback response, widget settings, locale, and website source to their token-scoped project. Both runtime environments require 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.

CI/CD Workflows

Add CHATTYBOX_DEPLOY_TOKEN as an encrypted, production-scoped secret in your CI provider. Add CHATTYBOX_API_URL as a secret or variable using the widget API URL from the project's Embed tab. Run validation on pull requests, but restrict production deployment to your protected default branch or an approved deployment environment.

GitHub Actions

name: Deploy ChattyBox configuration

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bunx @openstaticfish/chattybox-cli validate

  deploy:
    if: github.event_name == 'push'
    needs: validate
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Validate and deploy
        env:
          CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
          CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
        run: |
          bunx @openstaticfish/chattybox-cli validate
          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.

GitLab CI/CD

Store both values under Settings → CI/CD → Variables. Protect the deployment token, mask it, and scope it to the production environment.

.gitlab-ci.yml

image: oven/bun:1

validate_chattybox:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - bunx @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx @openstaticfish/chattybox-cli validate
    - bunx @openstaticfish/chattybox-cli deploy --environment production --json

GitLab exposes CHATTYBOX_DEPLOY_TOKEN and CHATTYBOX_API_URL automatically to the job using their variable names. Use a protected default branch so protected variables are unavailable to untrusted branches.

Bitbucket Pipelines

Add both values as deployment variables under Repository settings → Pipelines → Deployments → Production. Mark the deployment token as secured.

bitbucket-pipelines.yml

image: oven/bun:1

pipelines:
  pull-requests:
    '**':
      - step:
          name: Validate ChattyBox configuration
          script:
            - bunx @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx @openstaticfish/chattybox-cli validate
            - bunx @openstaticfish/chattybox-cli deploy --environment production --json

Replace main if your default branch has another name. Bitbucket injects deployment variables only into steps associated with that deployment environment.

Configuration Sections

Section	Purpose
schemaVersion	Selects the public configuration contract. Version 1 is currently supported.
project	Optional project metadata such as its dashboard description.
assistant	Names the assistant and defines a built-in persona or custom system prompt plus fallback copy.
knowledge.sources	Selects homepage, sitemap, manual URL, or crawl discovery plus limits, filters, and refresh schedule.
runtime	Controls automatic/fixed locale, default locale, and page-level locale overrides.
widget	Controls enablement, position, copy, colors, and default/emoji/URL icon presentation.

Personas

Set promptProfile to default, support, sales, or sarcastic to use the maintained persona instructions. Set it to custom and provide systemPrompt for a custom persona. If both a built-in profile and systemPrompt are provided, the explicit prompt wins.

Knowledge discovery

{
  "type": "website",
  "url": "https://docs.example.com",
  "mode": "sitemap",
  "sitemapUrl": "https://docs.example.com/docs-sitemap.xml",
  "include": ["/docs/"],
  "exclude": ["/private/"],
  "maxPages": 500,
  "autoRescrape": true,
  "rescrapeInterval": "daily"
}

Supported modes are:

• homepage: index only url.
• sitemap: use sitemapUrl, or discover /sitemap.xml and /sitemap_index.xml when omitted.
• manual: index the non-empty manualUrls list.
• crawl: try conventional sitemaps, then follow links from url up to maxDepth (default 3).

include and exclude currently use URL substring matching, not glob syntax.

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.