Contributing to the CLI

The create-opencauldron CLI is a standalone package that scaffolds new OpenCauldron projects. It lives in a separate repository from the main app.

Repository: opencauldron/create-opencauldron

npm: create-opencauldron

What the CLI does

Running npx create-opencauldron@latest walks a user through an interactive setup wizard that:

Prompts for a studio name, database provider, storage backend, and AI model API keys
Shallow-clones the main opencauldron/opencauldron repository
Generates a configured .env.local from .env.example using the user’s input
Installs dependencies using the detected package manager (Bun, pnpm, Yarn, or npm)
Initializes a git repository with an initial commit

See the CLI Wizard guide for the full user-facing documentation.

Prerequisites

Node.js 20+ or Bun 1.0+
Git

1. Fork and clone

Fork opencauldron/create-opencauldron on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/create-opencauldron
cd create-opencauldron

2. Install dependencies

bun install

3. Run the CLI locally

To test the wizard locally without publishing to npm:

node index.js

Or run it in a specific target directory:

node index.js my-test-studio

To test non-interactive mode:

node index.js my-test-studio --skip

CLI structure

The CLI is intentionally small. The entry point is index.js at the repo root.

Key areas to understand when making changes:

Prompts — Built with the prompts package. Each wizard step is a prompt object in the main flow. The provider selection step is a multi-select built from a static list of providers.
Provider list — The list of AI providers shown in the wizard (with their env var names and model descriptions) is defined inline near the top of the file. When a new provider is added to the main app, it should be added here too.
Env file generation — The CLI reads .env.example from the cloned repo and replaces placeholder values with the user’s input. The replacement logic looks for specific commented-out lines matching each env var name.
Package manager detection — The CLI detects which package manager is available by checking for lockfiles and running which checks in order: Bun, pnpm, Yarn, npm.

Common contribution types

Adding a new provider to the wizard

When a new AI provider is added to the main app (via src/providers/ and .env.example), the CLI wizard should be updated to include it in the provider selection step.

Find the provider list array in index.js. Each entry looks like this:

{
  title: 'Google Gemini',
  description: 'Imagen 4, Flash, Flash Lite + Veo 3 video',
  value: 'GEMINI_API_KEY',
  type: 'image+video',
}

Add a new entry following the same shape. The value field must match the env var name exactly as it appears in .env.example.

Fixing a wizard step

Each wizard step is a prompts configuration object. Refer to the prompts documentation for available field types and validation options.

Improving non-interactive mode

The --skip flag bypasses all prompts and uses hardcoded defaults. If you change the defaults or add new prompts, update the skip-mode fallback values to match.

Testing your changes

Before opening a pull request, run a full end-to-end test:

Create a clean temporary directory somewhere outside the repo.
Run node /path/to/create-opencauldron/index.js test-studio from inside that directory.
Walk through all wizard steps (or test with --skip).
Verify the generated .env.local contains the expected values.
Confirm bun install runs without errors in the scaffolded directory.

There are no automated tests. Manual end-to-end verification is required.

Publishing

The CLI package is published to npm as create-opencauldron. Maintainers handle releases — contributors do not need to publish.

CLI Wizard guide — User-facing documentation for create-opencauldron
Contributing Overview — Full contribution process
Code Style and PR Guidelines — PR conventions