---
title: CLI Reference
description: "@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`:

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

Or install globally:

```bash
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.

```bash
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`

```bash
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. |

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

---

### `config`

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

```bash
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)**

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

**Skip prompts, use all defaults**

```bash
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**

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

**Clone from a custom git repository**

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

**Full flow after scaffolding**

```bash
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.