CLI

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

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

init

Use the init command to add assistant-ui to an existing project.

npx assistant-ui@latest init

This will:

Exit with a notice if the project already has a components.json
Run create instead if the directory has no package.json
Run shadcn init to configure the project
Use shadcn add to install the assistant-ui quick-start component
Add the default assistant-ui components (thread, composer, etc.) to your project

When init sets up an existing project in a non-interactive shell such as CI, pass --yes. Without it, init exits with an error because it cannot prompt.

When to use:

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

Options

Usage: assistant-ui init [options] [project-directory]

initialize assistant-ui in an existing project

Arguments:
  project-directory  directory for the new project

Options:
  -y, --yes          skip confirmation prompt. (default: false)
  -o, --overwrite    overwrite existing files. (default: false)
  -c, --cwd <cwd>    the working directory. defaults to the current directory.
  --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

create

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

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

This command scaffolds a project from assistant-ui starter templates or examples.

Available Templates

Template	Description	Command
`default`	Default template with Vercel AI SDK	`npx assistant-ui create`
`minimal`	Bare-bones starting point	`npx assistant-ui create -t minimal`
`cloud`	Cloud-backed persistence starter	`npx assistant-ui create -t cloud`
`cloud-clerk`	Cloud-backed starter with Clerk auth	`npx assistant-ui create -t cloud-clerk`
`cloud-harness`	A hosted harness with a shared conversation across browsers	`npx assistant-ui@latest cloud setup my-app`
`langchain`	LangGraph starter with the react-langchain adapter	`npx assistant-ui create -t langchain`
`mcp`	MCP tools + MCP Apps renderer starter	`npx assistant-ui create -t mcp`
`eve`	Eve agent + Next.js starter	`npx assistant-ui create -t eve`

Available Examples

Use --example to create a project from one of the monorepo examples with full feature demonstrations:

Example	Description	Command
`with-ai-sdk-v7`	Vercel AI SDK v7 integration	`npx assistant-ui create my-app -e with-ai-sdk-v7`
`with-eve`	Eve agent integration	`npx assistant-ui create my-app -e with-eve`
`with-artifacts`	HTML artifact rendering with live preview	`npx assistant-ui create my-app -e with-artifacts`
`with-langgraph`	LangGraph agent with custom tools	`npx assistant-ui create my-app -e with-langgraph`
`with-google-adk`	Google ADK agent integration	`npx assistant-ui create my-app -e with-google-adk`
`with-cloud`	Assistant Cloud persistence	`npx assistant-ui create my-app -e with-cloud`
`with-ag-ui`	AG-UI protocol integration	`npx assistant-ui create my-app -e with-ag-ui`
`with-assistant-transport`	Custom backend via Assistant Transport	`npx assistant-ui create my-app -e with-assistant-transport`
`with-resumable-stream`	Resumable LLM stream that survives reload mid-response	`npx assistant-ui create my-app -e with-resumable-stream`
`with-chain-of-thought`	Chain-of-thought reasoning, tool calls, and source citations	`npx assistant-ui create my-app -e with-chain-of-thought`
`with-external-store`	External message store	`npx assistant-ui create my-app -e with-external-store`
`with-interactables`	AI-driven interactive UI components	`npx assistant-ui create my-app -e with-interactables`
`with-openui`	OpenUI generative UI integration	`npx assistant-ui create my-app -e with-openui`
`with-custom-thread-list`	Custom thread list UI	`npx assistant-ui create my-app -e with-custom-thread-list`
`with-react-hook-form`	React Hook Form integration	`npx assistant-ui create my-app -e with-react-hook-form`
`with-ffmpeg`	FFmpeg video processing tool	`npx assistant-ui create my-app -e with-ffmpeg`
`with-elevenlabs-conversational`	Realtime voice with ElevenLabs	`npx assistant-ui create my-app -e with-elevenlabs-conversational`
`with-livekit`	Realtime voice with LiveKit	`npx assistant-ui create my-app -e with-livekit`
`with-elevenlabs-scribe`	ElevenLabs voice transcription	`npx assistant-ui create my-app -e with-elevenlabs-scribe`
`with-expo`	Expo / React Native	`npx assistant-ui create my-app -e with-expo`
`with-react-ink`	Terminal UI chat	`npx assistant-ui create my-app -e with-react-ink`
`with-react-router`	React Router v7 integration	`npx assistant-ui create my-app -e with-react-router`
`with-tanstack`	TanStack Start integration	`npx assistant-ui create my-app -e with-tanstack`

Examples

# 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 cloud + clerk template
npx assistant-ui@latest create my-app -t cloud-clerk

# Create from an example
npx assistant-ui@latest create my-app --example with-langgraph

# 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

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, minimal, cloud, cloud-clerk, cloud-harness, langchain, mcp, eve)
  -e, --example <example>        create from an example (e.g., with-langgraph)
  -p, --preset <name-or-url>     preset name or URL (e.g., chatgpt)
  --native                       create an Expo / React Native project
  --ink                          create a React Ink terminal project
  --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
  --skills                       add assistant-ui agent skills for AI coding assistants
  --no-skills                    skip adding assistant-ui agent skills
  -h, --help                     display help for command

cloud

Use cloud setup to create a multiplayer chat backed by a hosted harness:

npx assistant-ui@latest cloud setup multiplayer-chat

The command signs you in with browser device OAuth, selects or creates an organization and project, provisions the harness, and installs a Next.js app. Add your OPENAI_API_KEY to its .env.local, then run the app's dev script. Open http://localhost:3000/#main in two browsers to join the same conversation. Both clients receive the shared messages and streaming replies. Share this chat copies the current thread's URL.

For a script or coding agent, select cloud resources with flags:

npx assistant-ui@latest cloud setup multiplayer-chat --org team --new-project hackathon-chat --backend-url http://localhost:3000/api/chat --yes

Option	Effect
`--org <id-or-slug>`	Select an existing organization.
`--new-org <slug>`	Create an organization.
`--project <id-or-slug>`	Select an existing project.
`--new-project <slug>`	Create a project.
`--name <name>`	Set the display name of a new organization or project.
`--harness-name <name>`	Name the shared chat harness.
`--backend-url <url>`	Set the absolute chat endpoint; defaults to `http://localhost:3000/api/chat`.
`--access-code <code>`	Redeem a hackathon harness access code; also reads `ASSISTANT_UI_ACCESS_CODE`.
`--api-url <url>`	Select the cloud management server; also reads `ASSISTANT_UI_CLOUD_URL`.
`--no-open`	Print the device sign-in URL without opening a browser.
`--setup-url <url>`	Show device approval in the active setup wizard while the CLI completes sign-in.
`--yes`	Skip prompts; choose resources with flags.
`--skip-install`	Leave dependency installation to you.
`--use-npm`, `--use-pnpm`, `--use-yarn`, `--use-bun`	Choose a package manager.

The server's project API key is written to .env.local with owner-only permissions and a Git ignore entry. Public environment values identify the cloud API, harness origin, and workspace. .assistant-ui/cloud.json records the selected cloud resources. Existing environment values are preserved, and conflicting settings stop setup.

The starter's /api/credential route issues short-lived credentials for the shared hackathon user. The browser uses HarnessCloudThreadList to connect to the hosted conversation, and the AI SDK chat route holds the model API key. Add application authentication to /api/credential for private access or individual users. Local development uses the runtime's browser tunnel; a deployed app supplies its public HTTPS chat endpoint to --backend-url during initial setup. To deploy a chat already configured locally, update the harness backend allowlist in the Cloud dashboard and backendUrl in .assistant-ui/cloud.json, then rerun with the same HTTPS --backend-url. Existing conversations keep their original backend, so open the deployed app with a fresh thread fragment such as #deployed-chat, then use Share this chat. Setup rejects a changed backend URL instead of silently ignoring it.

Run npx assistant-ui@latest cloud setup . inside a generated cloud-harness app to resume setup. npx assistant-ui@latest cloud login signs in separately; npx assistant-ui@latest cloud login --no-open prints the sign-in URL. npx assistant-ui@latest cloud logout revokes and removes the saved CLI credentials.

In an active setup wizard, an agent can pass its setup-agent URL to cloud login or cloud setup with --setup-url <url>. The wizard displays the public code, then opens Accounts for explicit approval and returns to the same setup. It waits for the CLI to poll Accounts and save owner-only credentials locally; returning alone never completes login. Tokens never pass through the wizard or its secret inputs. Cancelling the question or setup ends a pending login.

Before the npm patch is released, wizard sign-in is available in the verified CLI prerelease. Use the active setup-agent connection URL supplied by your agent:

npx --yes --package=https://www.assistant-ui.com/downloads/assistant-ui-wizard-login-ea9aae48e.tgz assistant-ui cloud login --setup-url "<active-setup-agent-url>"

This prerelease is separate from the existing hackathon setup download.

add

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

npx assistant-ui@latest add [component]

The add command runs shadcn add against the assistant-ui registry. It copies each component's source into your project and installs the dependencies the component needs.

Popular Components

# 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

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.
  --use-npm              explicitly use npm
  --use-pnpm             explicitly use pnpm
  --use-yarn             explicitly use yarn
  --use-bun              explicitly use bun
  -h, --help             display help for command

update

Use the update command to update all @assistant-ui/*, assistant-stream, and assistant-cloud packages to their latest versions.

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

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

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

Options

Usage: assistant-ui update [options]

Update all '@assistant-ui/*' and 'assistant-*' packages in package.json to latest versions using your package manager.

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

The command matches @assistant-ui/*, assistant-stream, and assistant-cloud in dependencies and devDependencies.

upgrade

Use the upgrade command to migrate your codebase after breaking changes.

npx assistant-ui@latest upgrade

This command:

Applies the current bundled codemods sequentially to update import paths and API usage
Shows a progress bar with file count
Reports any transformation errors
Detects new package dependencies and prompts to install them

The latest upgrade excludes the historical v0.8 UI package split because its @assistant-ui/react-ui destination is incompatible with current runtime versions. Do not run codemod v0-8/ui-package-split as part of a v0.15 upgrade.

Example output:

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

Options

Usage: assistant-ui upgrade [options]

Upgrade ai package dependencies and apply codemods

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.

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

Use it to run one migration instead of the full upgrade bundle.

Examples

# 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

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

CLI tool for running codemods

Arguments:
  codemod                Codemod to run (e.g., rewrite-framework-imports)
  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

mcp

Use the mcp command to connect your IDE to the assistant-ui MCP server.

npx assistant-ui@latest mcp

The command registers the hosted Model Context Protocol endpoint (https://www.assistant-ui.com/mcp) for Cursor, Windsurf, VSCode, and Claude Code. Zed and Claude Desktop only launch local stdio servers, so for those it configures the @assistant-ui/mcp-docs-server package instead.

Examples

# Interactive - prompts to select IDE
npx assistant-ui mcp

# Install for specific IDE
npx assistant-ui mcp --cursor
npx assistant-ui mcp --windsurf
npx assistant-ui mcp --vscode
npx assistant-ui mcp --zed
npx assistant-ui mcp --claude-code
npx assistant-ui mcp --claude-desktop

Options

Usage: assistant-ui mcp [options]

connect your IDE to the assistant-ui MCP server

Options:
  --cursor          install for Cursor
  --windsurf        install for Windsurf
  --vscode          install for VSCode
  --zed             install for Zed
  --claude-code     install for Claude Code
  --claude-desktop  install for Claude Desktop
  -h, --help        display help for command

agent

Use the agent command to open Claude Code with the assistant-ui skills loaded and a prompt already sent.

npx assistant-ui@latest agent "add a chat sidebar to this app"

The command fetches the assistant-ui skills plugin pinned to this CLI release into ~/.cache/assistant-ui/skills/<commit> (under $XDG_CACHE_HOME when set), then runs claude with --plugin-dir for that session only. Nothing is written into your project; run npx skills add assistant-ui/skills to install the skills permanently. The claude CLI must be on your PATH, and a GITHUB_TOKEN avoids GitHub's unauthenticated rate limit on the first fetch.

Options

Usage: assistant-ui agent [options] <prompt...>

launch Claude Code with assistant-ui skills

Arguments:
  prompt      prompt for the agent

Options:
  --dry       print the command instead of running it
  -h, --help  display help for command

info

Use the info command to print your environment and package versions for bug reports.

npx assistant-ui@latest info

This command collects and prints:

The running assistant-ui CLI version
OS, Node.js version, package manager, and framework
All installed @assistant-ui/* and assistant-* package versions
Key ecosystem dependency versions (React, Next.js, AI SDK, etc.)
Peer dependency warnings if any mismatches are detected

Example output:

Environment:
  assistant-ui CLI: 0.0.106
  OS:               macOS 15.3 (arm64)
  Node.js:          v22.14.0
  Package Manager:  pnpm 10.32.1
  Framework:        Next.js 15.3.1

Packages:
  @assistant-ui/react            0.12.15
  @assistant-ui/react-ai-sdk     1.3.12
  @assistant-ui/react-markdown   0.3.8
  assistant-stream                0.2.14

Ecosystem:
  react      19.1.0
  react-dom  19.1.0
  next       15.3.1
  ai         6.0.120

The output includes a copy-pasteable markdown block that you can paste directly into a bug report.

Options

Usage: assistant-ui info [options]

Print environment and package information for bug reports.

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

doctor

Use the doctor command to find duplicate or outdated assistant-ui packages in node_modules, including transitive ones.

npx assistant-ui@latest doctor

This command:

Reports packages installed in more than one version and exits with code 1 when it finds any
Checks the npm registry and reports packages that are behind the latest version
Recommends npx assistant-ui update to fix either problem

Options

Usage: assistant-ui doctor [options]

Diagnose mismatched or outdated assistant-ui packages (including transitive ones).

Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  --no-network     Skip the npm registry check for latest versions.
  -h, --help       display help for command

Common Workflows

Starting a new project

# 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

# 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

# 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

# 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 the public registry at r.assistant-ui.com.

Configure the style-aware URL in components.json so @assistant-ui/* installs match your shadcn style:

components.json

{
  "registries": {
    "@assistant-ui": "https://r.assistant-ui.com/styles/{style}/{name}.json"
  }
}

The {style} placeholder is filled from your components.json style field. Styles whose name starts with base- resolve to Base UI flavored components; every other style resolves to Radix. Existing Radix projects can keep https://r.assistant-ui.com/{name}.json as a fallback.

Each registry item lists its TypeScript source files and the dependencies to install. Components are added to your project's source code, so you can edit them.

Troubleshooting

Command not found

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

npx assistant-ui@latest init

Permission errors

On Linux/macOS, if you encounter permission errors:

sudo npx assistant-ui@latest init

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

Diagnosing issues

When filing a bug report, run npx assistant-ui info to collect environment details:

npx assistant-ui info

Paste the output into the "Environment info" field of the bug report template.

Conflicting dependencies

If you see dependency conflicts:

# 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:

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