# CLI
URL: /docs/cli

Scaffold projects, add components, and manage updates from the command line.

***

title: CLI
description: Scaffold projects, add components, and manage updates from the command line.
-----------------------------------------------------------------------------------------

Use the `assistant-ui` CLI to quickly set up new projects and add components to existing ones.

## init

Use the `init` command to initialize configuration and dependencies for a new project.

The `init` command installs dependencies, adds components, and configures your project for assistant-ui.

```bash
npx assistant-ui@latest init
```

This will:

* Detect if you have an existing project with a `package.json`
* Use `shadcn add` to install the assistant-ui quick-start component
* Add the default assistant-ui components (thread, composer, etc.) to your project
* Configure TypeScript paths and imports

**When to use:**

* Adding assistant-ui to an **existing** Next.js project
* First-time setup in a project with `package.json`

**Options**

```bash
Usage: assistant-ui init [options]

initialize assistant-ui in a new or existing project

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -h, --help       display help for command
```

## create

Use the `create` command to scaffold a new Next.js project with assistant-ui pre-configured.

```bash
npx assistant-ui@latest create [project-directory]
```

This command uses `create-next-app` with assistant-ui starter templates.

**Available Templates**

| Template    | Description                          | Command                                |
| ----------- | ------------------------------------ | -------------------------------------- |
| `default`   | Basic setup with Vercel AI SDK       | `npx assistant-ui create`              |
| `cloud`     | With Assistant Cloud for persistence | `npx assistant-ui create -t cloud`     |
| `langgraph` | LangGraph integration                | `npx assistant-ui create -t langgraph` |
| `mcp`       | Model Context Protocol support       | `npx assistant-ui create -t mcp`       |

**Examples**

```bash
# Create with default template
npx assistant-ui@latest create my-app

# Create with cloud template
npx assistant-ui@latest create my-app -t cloud

# Create with specific package manager
npx assistant-ui@latest create my-app --use-pnpm

# Skip package installation
npx assistant-ui@latest create my-app --skip-install
```

**Options**

```bash
Usage: assistant-ui create [project-directory] [options]

create a new project

Arguments:
  project-directory         name of the project directory

Options:
  -t, --template <template>  template to use (default, cloud, langgraph, mcp)
  --use-npm                  explicitly use npm
  --use-pnpm                 explicitly use pnpm
  --use-yarn                 explicitly use yarn
  --use-bun                  explicitly use bun
  --skip-install             skip installing packages
  -h, --help                 display help for command
```

## add

Use the `add` command to add individual components to your project.

```bash
npx assistant-ui@latest add [component]
```

The `add` command fetches components from the assistant-ui registry and adds them to your project. It automatically:

* Installs required dependencies
* Adds TypeScript types
* Configures imports

**Popular Components**

```bash
# Add the basic thread component
npx assistant-ui add thread

# Add thread list for multi-conversation support
npx assistant-ui add thread-list

# Add assistant modal
npx assistant-ui add assistant-modal

# Add multiple components at once
npx assistant-ui add thread thread-list assistant-sidebar
```

**Options**

```bash
Usage: assistant-ui add [options] <components...>

add a component to your project

Arguments:
  components             the components to add

Options:
  -y, --yes              skip confirmation prompt. (default: true)
  -o, --overwrite        overwrite existing files. (default: false)
  -c, --cwd <cwd>        the working directory. defaults to the current directory.
  -p, --path <path>      the path to add the component to.
  -h, --help             display help for command
```

## update

Use the `update` command to update all `@assistant-ui/*` packages to their latest versions.

```bash
npx assistant-ui@latest update
```

This command:

* Scans your `package.json` for assistant-ui packages
* Updates them to the latest versions using your package manager
* Preserves other dependencies

**Examples**

```bash
# Update all assistant-ui packages
npx assistant-ui update

# Dry run to see what would be updated
npx assistant-ui update --dry
```

**Options**

```bash
Usage: assistant-ui update [options]

update all '@assistant-ui/*' packages to latest versions

Options:
  --dry          print the command instead of running it
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -h, --help       display help for command
```

## upgrade

Use the `upgrade` command to automatically migrate your codebase when there are breaking changes.

```bash
npx assistant-ui@latest upgrade
```

This command:

* Runs codemods to transform your code
* Updates import paths and API usage
* Detects required dependency changes
* Prompts to install new packages

**What it does:**

* Applies all available codemods sequentially
* Shows progress bar with file count
* Reports any transformation errors
* Automatically detects and offers to install new dependencies

**Example output:**

```bash
Starting upgrade...
Found 24 files to process.
Progress |████████████████████| 100% | ETA: 0s || Running v0-11/content-part-to-message-part...
Checking for package dependencies...
✅ Upgrade complete!
```

**Options**

```bash
Usage: assistant-ui upgrade [options]

upgrade and apply codemods for breaking changes

Options:
  -d, --dry              dry run (no changes are made to files)
  -p, --print            print transformed files to stdout
  --verbose              show more information about the transform process
  -j, --jscodeshift <options>  pass options directly to jscodeshift
  -h, --help             display help for command
```

## codemod

Use the `codemod` command to run a specific codemod transformation.

```bash
npx assistant-ui@latest codemod <codemod> <source>
```

This is useful when you want to run a specific migration rather than all available upgrades.

**Examples**

```bash
# Run specific codemod on a directory
npx assistant-ui codemod v0-11/content-part-to-message-part ./src

# Run with dry run to preview changes
npx assistant-ui codemod v0-11/content-part-to-message-part ./src --dry

# Print transformed output
npx assistant-ui codemod v0-11/content-part-to-message-part ./src --print
```

**Options**

```bash
Usage: assistant-ui codemod [options] <codemod> <source>

run a specific codemod transformation

Arguments:
  codemod                codemod to run
  source                 path to source files or directory to transform

Options:
  -d, --dry              dry run (no changes are made to files)
  -p, --print            print transformed files to stdout
  --verbose              show more information about the transform process
  -j, --jscodeshift <options>  pass options directly to jscodeshift
  -h, --help             display help for command
```

## Common Workflows

### Starting a new project

```bash
# Create a new project with the default template
npx assistant-ui@latest create my-chatbot

# Navigate into the directory
cd my-chatbot

# Start development
npm run dev
```

### Adding to existing project

```bash
# Initialize assistant-ui
npx assistant-ui@latest init

# Add additional components
npx assistant-ui@latest add thread-list assistant-modal

# Start development
npm run dev
```

### Keeping up to date

```bash
# Check for updates (dry run)
npx assistant-ui@latest update --dry

# Update all packages
npx assistant-ui@latest update

# Run upgrade codemods if needed
npx assistant-ui@latest upgrade
```

### Migrating versions

```bash
# Run automated migration
npx assistant-ui@latest upgrade

# Or run specific codemod
npx assistant-ui@latest codemod v0-11/content-part-to-message-part ./src

# Update packages after migration
npx assistant-ui@latest update
```

## Component Registry

The CLI pulls components from our public registry at [r.assistant-ui.com](https://r.assistant-ui.com).

Each component includes:

* Full TypeScript source code
* All required dependencies
* Tailwind CSS configuration
* Usage examples

Components are added directly to your project's source code, giving you full control to customize them.

## Troubleshooting

### Command not found

If you get a "command not found" error, make sure you're using `npx`:

```bash
npx assistant-ui@latest init
```

### Permission errors

On Linux/macOS, if you encounter permission errors:

```bash
sudo npx assistant-ui@latest init
```

Or fix npm permissions: [https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)

### Conflicting dependencies

If you see dependency conflicts:

```bash
# Try with --force flag
npm install --force

# Or use legacy peer deps
npm install --legacy-peer-deps
```

### Component already exists

Use the `--overwrite` flag to replace existing components:

```bash
npx assistant-ui@latest add thread --overwrite
```

## Configuration

The CLI respects your project's configuration:

* **Package Manager**: Automatically detects npm, pnpm, yarn, or bun
* **TypeScript**: Works with your `tsconfig.json` paths
* **Tailwind**: Uses your `tailwind.config.js` settings
* **Import Aliases**: Respects `components.json` or `assistant-ui.json` configuration