CLI

react-ai-chat includes a CLI for two main tasks:

Generate an editable chatbot UI
Create an embedding index for RAG

Run the CLI with:

npx react-ai-chat

You can also run a specific command directly.

npx react-ai-chat init

Commands

Command	Purpose
`init`	Generate an editable chatbot UI
`embed`	Create an embedding index from your documents

Generate the chatbot

Run the init command to generate an editable chatbot UI:

npx react-ai-chat init

The CLI supports three options:

Option	Description
`--jsx`	Generate JSX files instead of TSX files
`--path <path>`	Set the output directory
`--force`	Overwrite existing generated files

Generate TypeScript files

By default, the CLI generates TypeScript React components:

npx react-ai-chat init

The default output directory is:

./chatbot

The generated files are:

chatbot/
├── chatbot.tsx
├── chatbot-header.tsx
├── chatbot-messages.tsx
├── chatbot-input.tsx
└── chatbot.css

Generate JSX files

Use --jsx when your project uses JavaScript:

npx react-ai-chat init --jsx

This generates:

chatbot/
├── chatbot.jsx
├── chatbot-header.jsx
├── chatbot-messages.jsx
├── chatbot-input.jsx
└── chatbot.css

Change the output path

Use --path to choose where the generated files should be placed:

npx react-ai-chat init --path ./components/chatbot

This produces:

components/
└── chatbot/
    ├── chatbot.tsx
    ├── chatbot-header.tsx
    ├── chatbot-messages.tsx
    ├── chatbot-input.tsx
    └── chatbot.css

Overwrite existing files

The CLI protects existing generated files by default.

Use --force when you want to overwrite them:

npx react-ai-chat init --force

You can combine the options:

npx react-ai-chat init --jsx --path ./components/chatbot --force

This generates JSX components in ./components/chatbot and allows existing files to be replaced.

See Generated Chatbot.

Create an embedding index

Run:

npx react-ai-chat embed

The CLI uses an interactive setup.

1. Select a provider

Choose the embedding provider you want to use.

The available providers are:

Google
OpenAI
Voyage AI
Cohere
Jina AI
Hugging Face

2. Select the primary model

The CLI loads the models available for the selected provider.

You can choose the model used to generate the primary embeddings.

3. Select dimensions

Some embedding models support multiple output dimensions.

The CLI only presents dimensions supported by the selected model.

The selected dimension is used consistently when generating the index.

4. Select a fallback model

You can optionally select a fallback model.

Fallback models are filtered to models that support the same embedding dimensions.

If the primary provider encounters an error while generating a batch, the CLI can switch to the fallback provider configuration for that batch.

5. Select the documents directory

Choose the directory containing the documents you want to index.

The current indexing pipeline processes Markdown and MDX content.

6. Select the output path

Choose where the generated embedding index should be saved.

The resulting JSON file contains the indexed chunks and embedding metadata.

Batched embedding generation

The CLI generates embeddings in batches instead of sending every document chunk as an individual request.

Each embedding provider has a configured maximum batch size. The indexer uses that limit when sending chunks to the provider.

For example, if the provider supports a maximum batch size of 32 and your documents produce 70 chunks:

70 document chunks
        ↓
Batch 1: chunks 1-32
        ↓
Batch 2: chunks 33-64
        ↓
Batch 3: chunks 65-70

Batches are processed sequentially. This reduces unnecessary API requests and helps reduce rate-limit pressure during large indexing jobs.

Batch progress

The CLI reports progress while embedding batches:

Embedding batch 1/3: chunks 1-32/70
Embedding batch 2/3: chunks 33-64/70
Embedding batch 3/3: chunks 65-70/70

The number of chunks in each batch depends on the provider's configured maximum batch size.

Example workflow

A typical RAG setup looks like:

Your Markdown / MDX files
          ↓
npx react-ai-chat embed
          ↓
Provider
          ↓
Embedding model
          ↓
Embedding dimensions
          ↓
Optional fallback model
          ↓
Split into batches
          ↓
Generate embeddings
          ↓
Embedding index
          ↓
Your server
          ↓
RAG retrieval

Embedding progress

During generation, the CLI reports the progress of each embedding batch and the model currently being used.

For example:

Embedding batch 1/4: chunks 1-32/100
Embedding batch 2/4: chunks 33-64/100
Embedding batch 3/4: chunks 65-96/100
Embedding batch 4/4: chunks 97-100/100

If a batch fails and a fallback model was configured, the CLI can continue processing that batch with the fallback provider configuration.

The generated index records embedding metadata so retrieval can validate that the configured provider and model are compatible.

Environment variables

The embedding provider needs its API credentials.

Set the appropriate environment variable before running the command.

For example:

GEMINI_API_KEY=your_api_key_here

Use the environment variable required by your selected provider.

Do not commit API keys to your repository.

Re-running the command

Run the embed command again whenever your source documents change:

npx react-ai-chat embed

The command creates a new index from the selected documents.

If you change the embedding provider, model, or dimensions, regenerate the index before using it for retrieval.

Why dimensions matter

Embedding vectors have a fixed number of dimensions.

For example, an index generated with:

Model: your-model
Dimensions: 768

must be queried with vectors that also contain 768 values.

react-ai-chat checks vector dimensions during retrieval and reports an error when they do not match.

CLI and RAG

The CLI only creates the index.

Your server route uses that index during chat requests:

CLI
 │
 ├── Read documents
 ├── Split into chunks
 ├── Create embedding batches
 ├── Generate embeddings
 └── Save index
          │
          ▼
     Embedding index
          │
          ▼
   createChatRoute()
          │
          ▼
      RAG retrieval
          │
          ▼
       AI model

See RAG for connecting the generated index to your chat route.

Make sure the fallback model supports the same embedding dimensions as the primary model.

CLI

CLI