CLI Reference

@chat-js/cli command reference

Overview

@chat-js/cli scaffolds new ChatJS applications. It walks you through selecting an AI gateway, features, and auth providers, then generates a fully configured Next.js project.

Installation

No installation is required. Run it directly with npx:

npx @chat-js/cli@latest create my-app

Or install globally:

npm install -g @chat-js/cli
chat-js create my-app

Commands

`create`

Scaffold a new ChatJS app. This is the default command, so you can omit the word create and pass the directory directly.

npx @chat-js/cli@latest create [directory] [options]
npx @chat-js/cli@latest [directory] [options]

Arguments

Argument	Description
`directory`	Target directory for the project. Prompted interactively if omitted.

Options

Flag	Default	Description
`-y, --yes`	`false`	Skip prompts and use the scaffold defaults.
`--electron` / `--no-electron`	Prompted	Include or exclude the Electron desktop app.
`--gateway <name-or-address>`	Vercel	Select a built-in or external registry gateway.
`--from-git <url>`	Built-in scaffold	Clone from a Git repository instead of the built-in scaffold.
`--storage-provider <provider>`	Prompted when needed	Select a Files SDK provider such as `vercel-blob`, `s3`, `r2`, or `gcs`.
`--storage-config <json>`	—	Supply non-secret Files SDK adapter options as JSON.

New apps use the invoking package manager, with Bun as the fallback. The CLI records its version in package.json, and shadcn installs dependencies immediately. The former --no-install, --package-manager, and --registry flags are removed.

After scaffolding, the CLI prints the exact environment variables required for your chosen configuration.

Use npx @chat-js/cli@latest --version or chat-js --version after a global installation to print the CLI version.

`add`

npx @chat-js/cli@latest add <tools...> [options]

Install one or more registry tools into an existing ChatJS project. Items specify explicit targets under tools/chatjs. Namespace configuration lives in components.json.

Flag	Default	Description
`-y, --yes`	`false`	Skip the installation confirmation.
`-o, --overwrite`	`false`	Overwrite existing tool files without prompting.
`-c, --cwd <cwd>`	Current directory	Run against another ChatJS project.

npx @chat-js/cli@latest add word-count

`config`

Print the fully resolved chat.config.ts, including gateway defaults.

npx @chat-js/cli@latest config

Flag	Default	Description
`-c, --cwd <cwd>`	Current directory	Read another ChatJS project config.

What gets generated

The create command copies the built-in template and then writes a tailored chat.config.ts. The generated project structure is:

my-app/
├── app/                    # Next.js App Router pages and layouts
│   ├── (auth)/             # Auth-related routes
│   ├── (chat)/             # Chat interface routes
│   ├── api/                # API route handlers
│   └── layout.tsx
├── components/             # Shared UI components
├── hooks/                  # React hooks
├── lib/                    # Core logic (AI, auth, DB, config schema)
├── providers/              # React context providers
├── trpc/                   # tRPC router
├── chat.config.ts          # Your app configuration (generated)
├── drizzle.config.ts       # Database schema config
├── next.config.ts
├── package.json
└── tsconfig.json

chat.config.ts is written with your chosen gateway, features, and auth providers pre-filled. All other config fields are set to sensible defaults with inline comments.

Examples

Interactive setup (recommended)

npx @chat-js/cli@latest create my-chat-app

Skip prompts, use all defaults

npx @chat-js/cli@latest create my-chat-app --yes

Defaults include Vercel AI Gateway, GitHub OAuth, parallel responses, document tools, no Electron app, and npm when invoked through npx.

Select a gateway

npx @chat-js/cli@latest create my-chat-app --gateway openrouter

Clone from a custom git repository

npx @chat-js/cli@latest create my-chat-app --from-git https://github.com/your-org/your-fork

Full flow after scaffolding

npx @chat-js/cli@latest create my-chat-app
cd my-chat-app
cp .env.example .env.local
# Fill in the env vars printed by the CLI
npm run db:push
npm run dev

Run npx @chat-js/cli@latest sync after a direct shadcn tool installation. For a recognized --from-git ChatJS clone, create replaces its selected gateway slot and writes a new configuration. Unsupported clones skip ChatJS installation.