> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Velt CLI

> Use the add-velt CLI to scaffold Velt collaboration features into your Next.js app with a single command.

Add Velt real-time collaboration to an existing Next.js project from your terminal. The CLI installs dependencies, generates components, and auto-wires `VeltProvider` into your app layout. No manual configuration required.

<Card title="GitHub Repository" icon="github" href="https://github.com/velt-js/add-velt-next-js">
  velt-js/add-velt-next-js
</Card>

## When to Use the CLI

* You want to add Velt to a Next.js project quickly from the command line
* You prefer a non-interactive, flag-driven workflow
* You want to scaffold specific features (comments, notifications, CRDT) in one step
* You are setting up Velt without an AI coding assistant

<Info>
  If you are using an AI coding agent like Claude Code or Cursor, see the [MCP Installer](/get-started/mcp-installer) for an AI-assisted setup experience.
</Info>

## Prerequisites

* **Node.js** 18+
* **Next.js** 13.4.0+ (App Router or Pages Router)
* **React** 18.2.0+
* **Package manager**: npm, yarn, or pnpm
* A [Velt API key](https://console.velt.dev)

## Quickstart

Run the CLI in your Next.js project directory:

```bash theme={null}
npx @velt-js/add-velt
```

This installs the baseline Velt SDK (`@veltdev/react`, `@veltdev/types`) and generates core components. To include specific features, add flags:

```bash theme={null}
npx @velt-js/add-velt --comments
```

After the CLI completes, set your API key in `.env.local`:

```bash theme={null}
NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
```

Then update the generated files with your app-specific logic:

1. **`components/velt/VeltInitializeDocument.tsx`**: replace the placeholder document ID with your own (e.g., from a route parameter)
2. **`components/velt/VeltInitializeUser.tsx`**: replace the placeholder user object with your real user context

Start your dev server and verify Velt loads in the browser console.

## Configuration

### API Key

The CLI wires `VeltProvider` to read your API key from the `NEXT_PUBLIC_VELT_API_KEY` environment variable. Add it to `.env.local`:

```bash theme={null}
NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
```

Get your API key from the [Velt Console](https://console.velt.dev).

### Document ID

Update `components/velt/VeltInitializeDocument.tsx` with your document ID source:

```tsx theme={null}
// Replace with your document ID logic
const documentId = 'your-document-id';
const documentName = 'your-document-name';
```

### User Authentication

Update `components/velt/VeltInitializeUser.tsx` with your user retrieval logic:

```tsx theme={null}
// Replace with your user retrieval logic
const user = {
  userId: 'user-id',
  organizationId: 'organization-id',
  email: 'user@example.com',
};
```

## Options

### Feature Flags

| Flag              | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `--comments`      | Add inline comments (VeltComments, VeltCommentsSidebar, VeltCursor) |
| `--notifications` | Add notifications (VeltNotificationsTool, VeltCursor)               |
| `--presence`      | Add presence indicators (VeltPresence)                              |
| `--cursors`       | Add live cursors (VeltCursor)                                       |

<Info>
  The CLI supports core scaffolding features. For additional features like Recorder, Single Editor Mode, Self-Hosting Data, Activity Logs, and Huddle, use the [MCP Installer](/get-started/mcp-installer) with an AI coding agent.
</Info>

### CRDT Type Flags (choose one)

| Flag                | Description                                |
| ------------------- | ------------------------------------------ |
| `--reactflow-crdt`  | Canvas collaboration with ReactFlow        |
| `--tiptap-crdt`     | Rich text editor collaboration with Tiptap |
| `--codemirror-crdt` | Code editor collaboration with CodeMirror  |

### Combined Flag

| Flag    | Description                                                        |
| ------- | ------------------------------------------------------------------ |
| `--all` | Enable comments + notifications + CRDT (requires a CRDT type flag) |

### Installation Flags

| Flag                 | Description                     |
| -------------------- | ------------------------------- |
| `--force`, `-f`      | Force overwrite existing files  |
| `--legacy-peer-deps` | Use legacy peer deps (npm only) |
| `--help`, `-h`       | Show help message               |

## What the CLI Does

The CLI performs these steps automatically:

1. **Detects your project**: finds `next.config.js`/`next.config.ts`, determines App Router vs Pages Router, and identifies your package manager (npm, yarn, or pnpm with workspace support)
2. **Installs dependencies**: adds `@veltdev/react` and `@veltdev/types`, plus feature-specific packages (e.g., `yjs` for CRDT)
3. **Generates components**: creates files under `components/velt/` for collaboration, document initialization, and user authentication
4. **Copies assets**: adds icon SVGs to `public/icons/` when features like notifications are selected

After the CLI completes, you need to manually wrap your page content with `VeltProvider`. The CLI skips auto-wiring the layout if it detects a `metadata` export (server component). See the [Troubleshooting](#manual-veltprovider-setup) section for the required code.

## Generated Files

### Core (always created)

```
components/velt/
├── VeltCollaboration.tsx       # Main collaboration wrapper
├── VeltInitializeDocument.tsx  # Document initialization hook
└── VeltInitializeUser.tsx      # User authentication hook
```

### With features enabled

When you use `--comments`, `--notifications`, or CRDT flags, the CLI also generates:

```
components/velt/
├── VeltTools.tsx               # Toolbar (presence, sidebar, notifications)
└── ui-customization/
    ├── VeltCustomization.tsx   # Dark mode + wireframe wrapper
    ├── styles.css              # Custom styles
    └── ...                     # Feature-specific wireframe files
```

To use the toolbar components, import `VeltTools` into your page:

```tsx theme={null}
import VeltTools from '@/components/velt/VeltTools';

export default function MyPage() {
  return (
    <>
      <div className="toolbar">
        <VeltTools />
      </div>
      {/* Your page content */}
    </>
  );
}
```

## Examples

```bash theme={null}
# Core only (minimal setup)
npx @velt-js/add-velt

# Comments only (includes Presence + Cursors)
npx @velt-js/add-velt --comments

# Notifications only (includes Presence + Cursors)
npx @velt-js/add-velt --notifications

# Comments + Notifications
npx @velt-js/add-velt --comments --notifications

# All features with ReactFlow CRDT
npx @velt-js/add-velt --all --reactflow-crdt

# All features with Tiptap CRDT
npx @velt-js/add-velt --all --tiptap-crdt

# Force overwrite existing files
npx @velt-js/add-velt --all --reactflow-crdt --force
```

## Troubleshooting

### Dependency conflicts

If installation fails due to peer dependency issues:

```bash theme={null}
npx @velt-js/add-velt --force
# or (npm only)
npx @velt-js/add-velt --legacy-peer-deps
```

The CLI uses a smart retry strategy that automatically tries `--force` and `--legacy-peer-deps` as fallbacks.

### Existing files

Use `--force` to overwrite previously generated files:

```bash theme={null}
npx @velt-js/add-velt --comments --force
```

### Multiple CRDT types

Only one CRDT type can be selected at a time:

```bash theme={null}
# Wrong — will error
npx @velt-js/add-velt --reactflow-crdt --tiptap-crdt

# Correct
npx @velt-js/add-velt --reactflow-crdt
```

### `--all` without a CRDT type

The `--all` flag requires a CRDT type:

```bash theme={null}
# Wrong — will error
npx @velt-js/add-velt --all

# Correct
npx @velt-js/add-velt --all --reactflow-crdt
```

### Manual VeltProvider setup

After running the CLI, wrap your page content with `VeltProvider` in the page where collaboration happens (NOT in `layout.tsx`):

```tsx theme={null}
// app/dashboard/[docId]/page.tsx (or your collaboration page)
"use client";
import { VeltProvider } from '@veltdev/react';
import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
import { VeltCollaboration } from '@/components/velt/VeltCollaboration';

export default function DocumentPage() {
  const { authProvider } = useVeltAuthProvider();
  return (
    <VeltProvider apiKey={process.env.NEXT_PUBLIC_VELT_API_KEY!} authProvider={authProvider}>
      <VeltCollaboration documentId={docId} />
      {/* Your page content */}
    </VeltProvider>
  );
}
```

<Warning>
  Do NOT place `VeltProvider` in `app/layout.tsx`. If your layout exports `metadata` (a server-only feature), adding `VeltProvider` there requires `"use client"` which conflicts with the metadata export. Place VeltProvider in the specific page where collaboration features are needed.
</Warning>

## Next Steps

* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup (without the CLI)
* **[Agent Skills](/get-started/skills)**: Teach your AI coding agent correct Velt patterns
* **[MCP Installer](/get-started/mcp-installer)**: AI-assisted Velt installation through MCP
* **[Comments Overview](/async-collaboration/comments/overview)**: Learn about commenting features
* **[CRDT Setup](/realtime-collaboration/crdt/overview)**: Set up collaborative editing
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control