ChimerAI CLI Reference

Version: 0.2.0 Package: @chimerai/cli Binary: chimerai

Complete reference for all ChimerAI CLI commands with usage examples.

Table of Contents

• Installation
• Commands Overview
• chimerai create
• chimerai init
• chimerai add
• chimerai remove
• chimerai list
• chimerai setup
• chimerai dev
• chimerai generate
• chimerai doctor
• chimerai update
• chimerai plugin
• chimerai migrate
• chimerai deploy
• chimerai use
• chimerai secret
• chimerai examples
• Project Root Resolution
• Workflows

Installation

# From the monorepo root
pnpm install

# Build the CLI
pnpm build -F @chimerai/cli

# Link globally (makes 'chimerai' available from any directory)
cd packages/cli
pnpm link --global

After linking, chimerai is available as a global command. Since it's a symlink, changes to the source take effect after pnpm build -F @chimerai/cli — no re-linking needed.

To unlink: pnpm unlink --global @chimerai/cli

Commands Overview

chimerai create

Scaffold a brand-new ChimerAI project with an interactive feature selector.

Synopsis

chimerai create <project-name> [options]

Options

Examples

# Interactive project creation
chimerai create my-ai-app

# Quick start with defaults
chimerai create my-ai-app --yes

# Create and install in one step
chimerai create my-ai-app --yes --install

# Create with SQLite (no Docker needed)
chimerai create my-ai-app --sqlite

# Full quick start: defaults + SQLite + auto-install
chimerai create my-ai-app --yes --sqlite --install

What it does

1. Creates the project directory
2. Prompts for features to include (auth, chat, billing, admin, etc.)
3. Generates package.json, tsconfig.json, .env, .env.example
4. Creates Prisma schema with selected models (PostgreSQL default, SQLite with --sqlite)
5. Scaffolds app structure (app/, lib/, components/, prisma/)
6. With --sqlite: auto-transforms PostgreSQL types (@db.Text, Json, String[]) to SQLite equivalents
7. Optionally generates Docker and docker-compose files
8. Optionally runs pnpm install
9. Creates .chimerai marker file (for project root resolution)
10. Registers project in global registry (~/.chimerai/projects.json)

chimerai init

Initialize a specific feature or the entire project skeleton in an existing directory.

Synopsis

chimerai init [feature] [options]

Arguments

Options

Examples

# Initialize everything
chimerai init

# Initialize only RBAC
chimerai init rbac

# Initialize auth in a specific directory
chimerai init auth --dir ./my-project

chimerai add

Add a component or feature to an existing project. Copies templates, updates config files, and provides next-step instructions.

Requires Next.js 15+. Generated route handlers use the async params API (Promise<params> + await params) introduced in Next.js 15. Projects on Next.js 14 or earlier will see TypeScript compile errors. The CLI detects the Next.js version and warns if < 15.

Synopsis

chimerai add <component> [options]

Available Components

Options

Examples

# Add authentication
chimerai add auth

# Add chat UI with streaming
chimerai add chat-ui

# Add standalone chat widgets (no auth required)
chimerai add chat-widget

# Add billing to a specific directory
chimerai add billing --dir ./frontend

# Add admin dashboard
chimerai add admin-dashboard

# --- AI Service Modules ---

# Add modular AI chat backend (creates services/ai/ with Python FastAPI)
chimerai add ai-chat

# Add RAG pipeline (auto-installs ai-chat if not present)
chimerai add rag

# Add content safety guardrails
chimerai add guardrails

# Add AI tools (interactive selection menu)
chimerai add ai-tools

Database Provider Auto-Detection

When chimerai add creates a Prisma schema, it automatically detects the database provider from DATABASE_URL in .env:

SQLite compatibility: Templates are written for PostgreSQL (production-first). When SQLite is detected, the CLI automatically transforms the schema:

To use PostgreSQL instead of SQLite, set DATABASE_URL in .env before running chimerai add auth:

# .env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp

Auto-Generated Environment Variables

chimerai add writes environment variables to .env (not .env.local) so both Next.js and Prisma can read them:

Port detection reads scripts.dev from package.json — e.g. next dev --port 3001 → NEXTAUTH_URL=http://localhost:3001.

Seed Scripts

chimerai add auth generates prisma/seed.ts with a demo user:

• Email: admin@example.com
• Password: admin123

chimerai add model-providers generates prisma/seed-providers.ts with:

• OpenAI provider + gpt-4o / gpt-4o-mini models
• Auto-activates if OPENAI_API_KEY is set in .env

Run seeds with: npx prisma db seed

What it does per component

auth creates:

• app/api/auth/[...nextauth]/route.ts — NextAuth config
• app/login/page.tsx — Login page
• components/SessionProvider.tsx — Session wrapper
• components/LogoutButton.tsx — Logout button
• types/next-auth.d.ts — Type definitions
• prisma/seed.ts — Demo user seed script
• Updates app/layout.tsx to include <SessionProvider>
• Writes DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL to .env

chat-ui creates:

• app/chat/page.tsx — Chat page
• components/StreamingChat.tsx — Streaming chat component
• app/api/v1/chat/stream/route.ts — SSE streaming endpoint
• app/api/chat/route.ts — Non-streaming endpoint
• app/api/conversations/route.ts — Conversations API

chat-widget creates:

• components/ChimerAIChatWidget.tsx — Simple card widget
• components/StandaloneStreamingChat.tsx — Full-screen streaming chat
• app/chat/page.tsx — Demo page with both widgets

AI Service Modules

These components install a self-contained Python AI backend in services/ai/. They use a manifest file (.chimerai-ai) to track installed modules and dynamically regenerate main.py, models.py, and requirements.txt.

ai-chat creates:

• services/ai/config.py — Pydantic settings
• services/ai/provider_client.py — LiteLLM multi-provider client
• services/ai/services/chat_service.py — Streaming chat completion
• services/ai/services/model_service.py — Model listing
• services/ai/services/moderation_service.py — Content moderation
• services/ai/routes/chat_routes.py — /api/chat, /api/chat/stream, /api/models
• services/ai/main.py — FastAPI entry point (generated)
• services/ai/models.py — Pydantic models (generated)
• services/ai/requirements.txt — Python dependencies (generated)
• services/ai/Dockerfile — Container image
• services/ai/.chimerai-ai — Module manifest
• Extends docker-compose.yml with ai-service block
• Adds AI_SERVICE_URL=http://localhost:8002 to .env

rag creates (auto-installs ai-chat if not present):

• services/ai/services/rag_service.py — Document ingestion and RAG query pipeline
• services/ai/services/vector_store.py — FAISS-based vector storage
• services/ai/services/embedding_service.py — Text embedding
• services/ai/routes/rag_routes.py — /api/rag/upload, /api/rag/query, /api/rag/stats
• services/ai/data/.gitkeep — FAISS index storage directory
• Regenerates main.py, models.py, requirements.txt

guardrails creates:

• services/ai/services/guardrails_service.py — PII detection, profanity filter, prompt injection detection
• services/ai/routes/guardrails_routes.py — /api/guardrails/check, /api/guardrails/config
• Regenerates main.py, models.py, requirements.txt

ai-tools — Interactive tool selection:

Selected tools are installed to services/ai/services/tools/. Running chimerai add ai-tools again allows adding more tools without affecting existing ones.

chimerai remove

Remove a component from your project. Deletes files, cleans up dependencies, and optionally preserves database tables.

Synopsis

chimerai remove <component> [options]

Options

Examples

# Remove billing (with confirmation prompt)
chimerai remove billing

# Remove chat-ui without confirmation
chimerai remove chat-ui --yes

# Remove auth but keep database tables
chimerai remove auth --keep-data

# Remove from a specific directory
chimerai remove model-providers --dir ./frontend

# --- AI Service Modules ---

# Remove AI chat module (regenerates remaining AI service files)
chimerai remove ai-chat

# Remove RAG module
chimerai remove rag

# Remove guardrails
chimerai remove guardrails

# Remove all AI tools
chimerai remove ai-tools

What it does

1. Shows the files that will be deleted
2. Asks for confirmation (unless --yes)
3. Deletes component files and empty directories
4. Removes component-specific dependencies from package.json (only if no other component needs them)
5. Displays cleanup instructions

For AI Service modules (ai-chat, rag, guardrails, ai-tools), the remove command additionally:

6. Updates the .chimerai-ai manifest to reflect removed modules
7. Regenerates main.py, models.py, requirements.txt, and config.py based on remaining modules
8. If no modules remain, suggests removing services/ai/ entirely

chimerai list

Show all installed and available components with their status, category, and dependencies.

Synopsis

chimerai list [options]

Options

Examples

# Show all components
chimerai list

# Show only installed components
chimerai list --installed

# Show only available (not yet installed)
chimerai list --available

# Output as JSON (for scripting)
chimerai list --json

# Check a specific project
chimerai list --dir ./my-project

Output

Components are grouped by category:

📦 ChimerAI Components

  Core:
    ✅ auth                    installed  NextAuth authentication system

  Admin:
    ✅ users-table             installed  Users management CRUD
    ○  roles-table             not installed  Roles management CRUD
       └─ requires: auth

  AI:
    ✅ chat-ui                 installed  Chat interface with streaming
    ○  chat-widget             not installed  Standalone API-key chat widgets

  📊 5/17 components installed

Detected Components (17 total)

The scanner checks for the following components by looking for their key files:

chimerai setup

Configure integrations and services interactively. Generates config files and updates .env.

Synopsis

chimerai setup <service> [options]

Options

Available Services

Examples

# Configure database connection
chimerai setup database

# Configure all AI providers
chimerai setup providers

# Configure Stripe
chimerai setup stripe

# Configure authentication
chimerai setup auth

# Setup RBAC permissions
chimerai setup permissions

# Configure from outside the project directory
chimerai setup database --dir /path/to/my-project

chimerai dev

Start a complete development environment with Docker, dependency installation, database migrations, and a dev server.

Synopsis

chimerai dev [options]

Options

Examples

# Start full development environment
chimerai dev

# Start on custom port
chimerai dev --port 3001

# Start without Docker
chimerai dev --skip-docker

# Skip migrations (faster startup)
chimerai dev --skip-migrate

What it does

1. Docker Services (unless --skip-docker)

   • Starts PostgreSQL container
   • Starts Redis container (if docker-compose.yml exists)

2. Dependencies

   • Installs node_modules if missing
   • Auto-detects package manager (pnpm/npm/yarn)

3. Database (unless --skip-migrate)

   • Runs prisma db push to sync schema
   • Skips if database connection fails (shows warning)

4. AI Service (if services/ai/main.py exists)

   • Creates Python virtual environment in services/ai/.venv/ if not present
   • Installs Python dependencies via pip install -r requirements.txt
   • Starts uvicorn main:app --reload --port 8002 in parallel
   • AI service output is prefixed with [AI] in magenta

5. Dev Server

   • Starts Next.js dev server on specified port
   • Shows Ctrl+C to stop message
   • Auto-stops Docker services and AI service on exit

Output (with AI Service)

  🚀 ChimerAI Dev Environment

  ▶️  Starting dev server on http://localhost:3000
  ▶️  AI service on http://localhost:8002

  Press Ctrl+C to stop

  [AI] INFO:     Uvicorn running on http://0.0.0.0:8002
  [AI] INFO:     Started reloader process

The AI service uses --reload for hot-reloading during development. Changes to Python files in services/ai/ are picked up automatically.

Environment Variables

PORT=3000          # Dev server port
DATABASE_URL=...   # Must be set in .env
NEXTAUTH_SECRET=.. # Must be set for auth features

Troubleshooting

chimerai generate

Scaffold code artifacts for your Next.js project. Generates components, hooks, pages, API routes, and Prisma models with proper TypeScript typing.

Synopsis

chimerai generate <type> <name> [options]

Generator Types

Options

Examples

Generate Component

# Create a component
chimerai generate component Button

# Output: components/Button.tsx
export function Button({ children }: { children: React.ReactNode }) {
  return <button>{children}</button>;
}

Generate Hook

# Create a custom hook
chimerai generate hook useAuth

# Output: hooks/useAuth.ts
export function useAuth() {
  const [user, setUser] = useState(null);
  // ...
  return { user };
}

Generate Page

# Create a page
chimerai generate page dashboard

# Output: app/dashboard/page.tsx (App Router)
export default function Page() {
  return <div>Dashboard</div>;
}

Generate API Route

# Create API route
chimerai generate api users

# Output: app/api/users/route.ts
# Includes: GET, POST handlers
# Output: app/api/users/[id]/route.ts
# Includes: GET, PUT, DELETE handlers with param types

Generate Model

# Create Prisma model with CRUD API
chimerai generate model Post

# Output:
# 1. prisma/schema.prisma - model Post { ... }
# 2. app/api/post/route.ts - GET (list), POST (create)
# 3. app/api/post/[id]/route.ts - GET (read), PUT (update), DELETE
# 4. Next steps printed to console

Naming Conventions

The generator auto-converts names to proper conventions:

Special Cases

Kebab-case conversion:

chimerai generate component user-profile
# → components/UserProfile.tsx

Hook prefix handling:

chimerai generate hook use-auth
# → hooks/useAuth.ts (not useUseAuth)

Nested pages:

chimerai generate page /admin/users
# → app/admin/users/page.tsx

What each generator does

Component Generator

• Creates function component
• Adds TypeScript interface for props
• Includes export statement
• Tailwind-ready (no styling by default)

Hook Generator

• Creates use* function
• Includes 'use client' directive
• Adds TypeScript types
• Includes state/effect patterns

Page Generator

• Creates Next.js App Router page
• Includes 'use client' directive for interactivity
• Supports nested routes
• Follows Next.js conventions

API Route Generator

• Creates route.ts file
• Includes GET and POST handlers
• For models: auto-generates CRUD routes ([id]/route.ts)
• Uses Prisma client for database ops
• Includes proper error handling

Model Generator

• Adds model to prisma/schema.prisma
• Creates complete CRUD API routes
• Prevents duplicate models
• Auto-generates both routes:
  • /api/<model> - List & Create
  • /api/<model>/[id] - Read, Update, Delete
• Prints next steps (edit schema, run migrations)

Overwriting Files

By default, files won't be overwritten:

chimerai generate component Button
# ✓ components/Button.tsx

chimerai generate component Button
# ⊘ components/Button.tsx already exists (use --force to overwrite)

Use --force to overwrite:

chimerai generate component Button --force
# ✓ components/Button.tsx (overwritten)

Validation

• ✅ Checks if project is valid Next.js project
• ✅ Detects App Router vs Pages Router
• ✅ Validates Prisma schema for model generation
• ✅ Prevents invalid names (special characters, reserved words)
• ✅ Auto-creates parent directories

chimerai doctor

Run comprehensive health checks on your ChimerAI project. Validates configuration, dependencies, environment setup, and common issues.

Synopsis

chimerai doctor [options]

Options

Examples

# Run diagnostics
chimerai doctor

# Run diagnostics on a specific project
chimerai doctor --dir ./my-project

# Run diagnostics and auto-fix issues
chimerai doctor --fix

Checks Performed

Auto-fix capabilities (--fix)

• Creates .env from .env.example (or generates defaults)
• Adds .env to .gitignore
• Creates missing directories (app/, prisma/, lib/)

Output

🩺 ChimerAI Doctor - Project Health Check

📋 Diagnostic Results:

  ✓ package.json: Valid with required dependencies
  ✓ Node.js: v20.10.0
  ✓ DATABASE_URL: Configured
  ⚠ NEXTAUTH_SECRET: Using default value - change for production
    Fix: Generate: openssl rand -base64 32
  ✓ Prisma Schema: Valid schema with required models
  ✓ App directory: app/ exists
  ✓ Dependencies: All critical dependencies installed
  ✓ .gitignore: .env excluded from git

📊 Summary:
  ✓ 7 passed
  ⚠ 1 warnings

⚠️  Project is functional but has warnings.

chimerai update

Compare your installed component files against the latest CLI templates to detect local modifications.

Synopsis

chimerai update [component] [options]

Arguments

Options

Tracked Components

Examples

# Check all components for updates
chimerai update

# Check a specific component
chimerai update auth

# Show inline diff
chimerai update --diff

# Dry run (preview only)
chimerai update --dry-run

Output

🔄 ChimerAI Component Update Check

  auth:
    ✓ app/api/auth/[...nextauth]/route.ts (up to date)
    ⚡ components/SessionProvider.tsx (modified locally)
    ✓ components/LogoutButton.tsx (up to date)
    ○ app/login/page.tsx (not installed)

📊 Summary:
  ✓ 2 up to date
  ⚡ 1 modified locally
  ○ 1 not installed

  💡 Run with --diff to see differences.

Diff output (--diff)

Shows up to 8 changed lines per file with − (yours) and + (template) markers:

    ⚡ components/SessionProvider.tsx (modified locally)
      - L5: import { SessionProvider as NextAuthProvider } from 'next-auth/react';
      + L5: import { SessionProvider } from 'next-auth/react';
      - L12:   return <NextAuthProvider>{children}</NextAuthProvider>;
      + L12:   return <SessionProvider>{children}</SessionProvider>;

chimerai plugin

Manage the plugin system: create new plugins, list installed plugins, or scaffold the plugin infrastructure.

Synopsis

chimerai plugin <action> [name] [options]

Actions

Options

Examples

# Set up the plugin system
chimerai plugin scaffold

# Create a basic plugin
chimerai plugin create my-filter

# Create an API plugin
chimerai plugin create rate-limiter --template api

# Create a UI plugin
chimerai plugin create dark-mode --template ui

# List all installed plugins
chimerai plugin list

Plugin Templates

basic — Minimal plugin with a single hook handler:

plugins/my-filter/
├── manifest.json
├── README.md
└── src/index.ts

api — Plugin with API routes:

plugins/rate-limiter/
├── manifest.json
├── README.md
└── src/
    ├── index.ts
    └── routes.ts

ui — Plugin with React components:

plugins/dark-mode/
├── manifest.json
├── README.md
└── src/
    ├── index.ts
    └── components.tsx

Plugin Manifest (manifest.json)

{
  "id": "my-filter",
  "name": "My Filter",
  "version": "1.0.0",
  "description": "My Filter plugin for ChimerAI",
  "hooks": ["ai.response.post"],
  "permissions": [],
  "config": {
    "enabled": { "type": "boolean", "default": true }
  }
}

Available Hooks

Scaffold output

Running chimerai plugin scaffold creates:

• plugins/ directory
• lib/plugin-loader.ts — Automatic plugin discovery and registration

chimerai migrate

Simplified Prisma migration management. Wraps common Prisma CLI commands with pre-flight checks and better error messages.

Synopsis

chimerai migrate [options]

Options

Examples

# Run a migration (auto-generates name if not provided)
chimerai migrate

# Named migration
chimerai migrate --name add-users-table

# Migration + seed
chimerai migrate --name initial --seed

# Check migration status
chimerai migrate --status

# Roll back the last migration
chimerai migrate --rollback

# Reset database (DESTRUCTIVE - deletes all data)
chimerai migrate --reset

# Reset and re-seed
chimerai migrate --reset --seed

# Migrate in a specific directory
chimerai migrate --dir ./apps/frontend --name add-roles

Pre-flight Checks

Before running any migration, the command validates:

1. prisma/schema.prisma exists
2. .env file exists
3. DATABASE_URL is configured (not empty)
4. Prisma CLI is available (npx prisma --version)

What each mode does

Default (migrate dev):

1. Runs npx prisma migrate dev --name <name>
2. Generates Prisma client (npx prisma generate)
3. Optionally runs seed

--status:

• Runs npx prisma migrate status
• Shows pending/applied migrations

--rollback:

• Finds the most recent migration directory
• Uses prisma migrate resolve --rolled-back to mark it as rolled back
• Regenerates Prisma client
• Provides next steps for schema revert

--reset:

• Runs npx prisma migrate reset --force
• Regenerates Prisma client
• Optionally runs seed

Seed File

The seed is run via npx prisma db seed. It looks for:

• prisma/seed.ts
• prisma/seed.js

If neither exists, seeding is skipped with a warning.

chimerai deploy

Generate deployment configuration for your target platform. Runs readiness checks before generating config files.

Synopsis

chimerai deploy [options]

Options

Examples

# Check deployment readiness
chimerai deploy --check-only

# Generate Docker config (default)
chimerai deploy

# Generate Docker config (explicit)
chimerai deploy --target docker

# Generate Vercel config
chimerai deploy --target vercel

# Generate Railway config
chimerai deploy --target railway

# Deploy from a specific directory
chimerai deploy --dir ./apps/frontend --target vercel

Deployment Checks

Before generating configs, the following checks are run:

Target: Docker

Generates three files:

Dockerfile — Multi-stage build:

• base: Node.js 20 Alpine with pnpm
• deps: Install dependencies + generate Prisma client
• builder: Build the Next.js app
• runner: Production image with non-root user

.dockerignore — Excludes node_modules, .next, .git, .env

docker-compose.prod.yml — App + PostgreSQL:

# Build and run
docker-compose -f docker-compose.prod.yml up -d

Target: Vercel

Generates vercel.json:

{
  "framework": "nextjs",
  "buildCommand": "prisma generate && next build",
  "installCommand": "pnpm install"
}

Next steps:

1. Set environment variables in Vercel dashboard
2. Deploy: vercel --prod

Target: Railway

Generates two files:

railway.toml — Build and deploy configuration with health check

app/api/health/route.ts — Health check endpoint (created if missing):

export async function GET() {
  return NextResponse.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
  });
}

Next steps:

1. Install Railway CLI: npm i -g @railway/cli
2. Deploy: railway up

chimerai use

Set a default project for the CLI or view all registered projects. This enables running CLI commands from any directory without --dir.

Synopsis

chimerai use [project-name] [options]

Arguments

Options

Examples

# Show all registered projects
chimerai use --list

# Set default project
chimerai use my-saas-app

# Show current default project
chimerai use

Output

📋 Registered projects:

  ★ my-saas-app     C:\Users\me\projects\my-saas-app
    other-project   C:\Users\me\projects\other-project

  ★ = default project

How projects get registered

Projects are automatically registered when you:

• chimerai create <name> — registers the new project
• chimerai init — registers the current directory

You can also manually set a default with chimerai use <name>.

See Project Root Resolution for the full lookup logic.

chimerai secret

Generate cryptographically secure secrets for your .env file. Supports NEXTAUTH_SECRET, PROVIDER_ENCRYPTION_KEY, and INTERNAL_API_TOKEN.

Synopsis

chimerai secret [type] [options]

Arguments

Secret Types

Options

Examples

# Show all secrets (copy & paste into .env)
chimerai secret

# Generate only NEXTAUTH_SECRET
chimerai secret nextauth

# Generate and write directly into .env
chimerai secret nextauth --update

# Update encryption key in a specific project
chimerai secret encryption --update --dir ./my-project

# Generate all and auto-update .env
chimerai secret all --update

When to Use

• New project setup — chimerai create generates secrets automatically, but if you need to rotate them
• Security rotation — Periodically rotate secrets with chimerai secret nextauth --update
• Team onboarding — New developer needs fresh secrets for their local .env
• JWT errors — If you see JWT_SESSION_ERROR: decryption operation failed, your NEXTAUTH_SECRET is invalid — regenerate it with chimerai secret nextauth --update

Note: After updating secrets, restart your dev server and clear browser cookies (old sessions were signed with the previous secret).

chimerai examples

Display usage examples for all commands in the terminal.

Synopsis

chimerai examples

This is a quick-reference command that prints common usage patterns for every CLI command directly in your terminal.

Project Root Resolution

All CLI commands (except create) use a smart resolution system to find your project directory. This means you can run commands from any directory — you don't have to be inside the project folder.

Priority Order

The CLI resolves the target directory in this order:

If none of these resolve a project, the CLI shows a helpful error with all available options.

Project Detection

When walking up the directory tree (max ~20 levels), the CLI looks for:

1. .chimerai marker file (created by chimerai create or automatically by chimerai add) — highest confidence
2. package.json + Next.js/Prisma indicators (next.config.* or prisma/) — fallback

Note: When running chimerai add on a project that doesn't have a .chimerai marker yet (e.g. a Blazor project via --dir), the CLI automatically creates the marker and registers the project. After that, all commands work by simply cd-ing into the directory.

The .chimerai Marker File

A JSON file created in the project root by chimerai create:

{
  "name": "my-saas-app",
  "createdAt": "2026-02-25T10:30:00.000Z",
  "version": "0.2.0"
}

This file should be committed to the repository (like .nvmrc or .editorconfig). It enables automatic project detection for all team members.

Global Registry

Located at ~/.chimerai/projects.json, the registry stores known projects:

{
  "projects": {
    "my-saas-app": "C:\\Users\\me\\projects\\my-saas-app",
    "other-project": "C:\\Users\\me\\projects\\other-project"
  },
  "default": "my-saas-app"
}

Manage with:

• chimerai use --list — show all registered projects
• chimerai use <name> — set default project
• Projects are auto-registered on chimerai create and chimerai init

Note: ~/.chimerai/projects.json is user-specific and should NOT be committed to git.

Commands That Require a Project

Examples

# Inside the project — works automatically
cd my-saas-app
chimerai doctor

# In a subdirectory — walks up to find root
cd my-saas-app/src/app/dashboard
chimerai doctor

# From any directory — uses default project from registry
cd /tmp
chimerai doctor

# Explicit path — always takes highest priority
chimerai doctor --dir C:\Users\me\projects\my-saas-app

# Via environment variable
$env:CHIMERAI_PROJECT = "C:\Users\me\projects\my-saas-app"
chimerai doctor

Troubleshooting

"No ChimerAI project found"

# Option 1: Use explicit path
chimerai doctor --dir /path/to/project

# Option 2: Register and set default project
chimerai use my-project

# Option 3: Set environment variable
$env:CHIMERAI_PROJECT = "/path/to/project"

Wrong project being used

# Check what's registered
chimerai use --list

# Change default
chimerai use correct-project

Project not found from subdirectory

The CLI walks up looking for .chimerai or package.json + Next.js/Prisma indicators. Make sure your project root has one of these markers, or use --dir to point to the project (this will automatically create a .chimerai marker).

For Team Collaboration

1. Commit .chimerai to git — All team members get automatic project detection
2. Don't commit ~/.chimerai/projects.json — It's user-specific (lives in home directory)
3. Share the project path — Team members can register with chimerai use <name>

Monorepo Usage

Important: In a monorepo like chimerai-kickstart, the CLI expects the Next.js app directory as the project root — not the monorepo root.

The monorepo root does not contain next, app/, or prisma/. The actual Next.js project lives in apps/frontend.

# ❌ Wrong — points to monorepo root (no Next.js here)
chimerai doctor --dir C:\Users\me\chimerai-kickstart

# ✅ Correct — points to the Next.js app
chimerai doctor --dir C:\Users\me\chimerai-kickstart\apps\frontend

# ✅ Also correct — register it once, use from anywhere
chimerai use frontend
# (after registering apps/frontend as "frontend")

To avoid confusion, place a .chimerai marker in apps/frontend or register it:

cd apps/frontend
chimerai init   # Creates .chimerai marker + registers project

After that, running chimerai doctor from anywhere inside the monorepo will auto-detect apps/frontend.

Workflows

New Project from Scratch

# 1. Create the project
chimerai create my-saas-app --install

# 2. Add features
cd my-saas-app
chimerai add auth
chimerai add chat-ui
chimerai add billing
chimerai add admin-dashboard

# 3. Configure services
chimerai setup database
chimerai setup providers
chimerai setup stripe

# 4. Run migrations
chimerai migrate --name initial --seed

# 5. Health check
chimerai doctor

# 6. Start development
pnpm dev

Add AI Service Backend

# 1. Add the AI chat backend (creates services/ai/)
chimerai add ai-chat

# 2. Add RAG for document-based Q&A
chimerai add rag

# 3. Add safety guardrails
chimerai add guardrails

# 4. Add AI tools (interactive selection)
chimerai add ai-tools

# 5. Start development (auto-starts AI service on port 8002)
chimerai dev

# 6. Test the AI service
curl http://localhost:8002/health

Add Enterprise Features

# Add enterprise components
chimerai add auth          # if not already added
chimerai add users-table
chimerai add roles-table

# Set up plugin system
chimerai plugin scaffold
chimerai plugin create content-filter --template api
chimerai plugin create custom-theme --template ui

# Run migration for new models
chimerai migrate --name add-enterprise-features

Prepare for Production

# 1. Run health check
chimerai doctor --fix

# 2. Check for local modifications
chimerai update --diff

# 3. Verify deployment readiness
chimerai deploy --check-only

# 4. Generate deployment config
chimerai deploy --target docker
# or
chimerai deploy --target vercel
# or
chimerai deploy --target railway

# 5. Follow the printed next steps

Plugin Development

# 1. Scaffold the plugin system
chimerai plugin scaffold

# 2. Create your plugin
chimerai plugin create my-plugin --template api

# 3. Edit the plugin handler
# Edit: plugins/my-plugin/src/index.ts

# 4. List plugins to verify
chimerai plugin list

# 5. Register in plugin-engine
# Import loadPlugins() from lib/plugin-loader.ts

Database Workflow

# Check current status
chimerai migrate --status

# Create a new migration
chimerai migrate --name add-api-keys

# Undo the last migration (safe rollback)
chimerai migrate --rollback

# Reset and re-seed (development only!)
chimerai migrate --reset --seed

Environment Variables

The CLI commands expect these environment variables in your .env:

Input Validation

Project and plugin names are validated automatically:

• Must be lowercase alphanumeric with hyphens only (e.g., my-app)
• Maximum 214 characters (npm limit)
• No leading/trailing hyphens, no consecutive hyphens
• No path traversal sequences (.., /, \)
• No reserved names (node_modules, package, dist, build, etc.)

Invalid examples:

chimerai create "My App"           # ❌ uppercase + spaces
chimerai create ../malicious       # ❌ path traversal
chimerai plugin create node_modules # ❌ reserved name
chimerai create a--b               # ❌ consecutive hyphens

Valid examples:

chimerai create my-saas-app        # ✅
chimerai create app2               # ✅
chimerai plugin create rate-limiter # ✅

Troubleshooting

Common Issues

"Templates directory not found" The CLI can't find its templates. Rebuild: cd packages/cli && pnpm build

"prisma/schema.prisma not found" Run chimerai init to create the initial project structure.

"DATABASE_URL not configured" Set DATABASE_URL in your .env file: chimerai setup database

"Cannot connect to database" Ensure PostgreSQL is running. If using Docker: docker-compose up -d

"Prisma CLI not available" Install Prisma: pnpm add -D prisma

Getting Help

# Show all commands
chimerai --help

# Show help for a specific command
chimerai create --help
chimerai add --help
chimerai doctor --help

# Show usage examples
chimerai examples