CLI

Use the CLI to add components to your project, manage dependencies, and more.

Installation

You don’t need to install the CLI globally. Use npx to run commands:

npx shadcn@latest

This will always use the latest version of the CLI.

Commands

init

Initialize your project and install dependencies.

npx shadcn@latest init

You can also initialize with components:

npx shadcn@latest init button card

Options

string

The template to use: next, vite, start, or next-monorepo

npx shadcn@latest init --template next

string

The base color: neutral, gray, zinc, stone, or slate

npx shadcn@latest init --base-color zinc

boolean

default:"true"

Skip confirmation prompt

npx shadcn@latest init --yes

boolean

default:"false"

Use default configuration

npx shadcn@latest init --defaults

boolean

default:"false"

Force overwrite of existing configuration

npx shadcn@latest init --force

string

The working directory (defaults to current directory)

npx shadcn@latest init --cwd ./my-app

boolean

Use the src directory when creating a new project

npx shadcn@latest init --src-dir

boolean

default:"true"

Use CSS variables for theming

npx shadcn@latest init --css-variables
npx shadcn@latest init --no-css-variables

boolean

default:"false"

Enable RTL support

npx shadcn@latest init --rtl

boolean

Do not install the base shadcn style

npx shadcn@latest init --no-base-style

create

Create a new project with shadcn/ui.

npx shadcn@latest create my-app

If no name is provided, you’ll be prompted to enter one. If no preset is specified, you’ll be taken to the create page to build your custom design system.

Options

string

The template to use: next, vite, or start

npx shadcn@latest create my-app --template vite

string

Use a preset configuration (name or URL)

# Use a named preset
npx shadcn@latest create my-app --preset default

# Use a URL
npx shadcn@latest create my-app --preset https://ui.shadcn.com/init?...

string

The working directory

npx shadcn@latest create --cwd ./projects

boolean

Use the src directory

npx shadcn@latest create my-app --src-dir

boolean

default:"false"

Enable RTL support

npx shadcn@latest create my-app --rtl

add

Add components to your project.

npx shadcn@latest add button

You can add multiple components at once:

npx shadcn@latest add button card dialog

Or add all components:

npx shadcn@latest add --all

Adding from URLs

You can also add components from URLs:

npx shadcn@latest add https://ui.shadcn.com/r/button.json

Adding from Custom Registries

If you’ve configured custom registries in components.json, you can use them:

npx shadcn@latest add @acme/button

Options

boolean

default:"false"

Skip confirmation prompt

npx shadcn@latest add button --yes

boolean

default:"false"

Overwrite existing files

npx shadcn@latest add button --overwrite

string

The working directory

npx shadcn@latest add button --cwd ./my-app

boolean

default:"false"

Add all available components

npx shadcn@latest add --all

string

The path to add the component to

npx shadcn@latest add button --path ./src/components

boolean

default:"false"

Mute output

npx shadcn@latest add button --silent

diff

Check for updates against the registry.

npx shadcn@latest diff

This will check all components in your project for updates. To check a specific component:

npx shadcn@latest diff button

The command will show you the differences between your local components and the latest versions in the registry.

Options

boolean

default:"false"

Skip confirmation prompt

npx shadcn@latest diff button --yes

string

The working directory

npx shadcn@latest diff --cwd ./my-app

view

View items from the registry.

npx shadcn@latest view button

This outputs the raw JSON for the component from the registry. Useful for debugging or inspecting component metadata. You can view multiple items:

npx shadcn@latest view button card dialog

Options

string

The working directory

npx shadcn@latest view button --cwd ./my-app

search

Search for components in the registry.

npx shadcn@latest search button

This searches the registry for components matching your query.

migrate

Migrate from older versions of shadcn/ui.

npx shadcn@latest migrate

This command helps you migrate your components when there are breaking changes or new conventions.

info

Display project information.

npx shadcn@latest info

Shows information about your project setup, including:

Framework detected
Package manager
Tailwind CSS version
Configuration paths

Usage Examples

# Create a new Next.js project with shadcn/ui
npx shadcn@latest create my-app --template next

# Or initialize in existing project
npx shadcn@latest init

# Add a single component
npx shadcn@latest add button

# Add multiple components
npx shadcn@latest add button card dialog

# Add all components
npx shadcn@latest add --all

# Add and overwrite existing
npx shadcn@latest add button --overwrite

# Check all components
npx shadcn@latest diff

# Check specific component
npx shadcn@latest diff button

# Initialize with specific options
npx shadcn@latest init \
  --template next \
  --base-color zinc \
  --css-variables \
  --defaults

# Add component from URL
npx shadcn@latest add https://ui.shadcn.com/r/button.json

# Add from custom registry
npx shadcn@latest add @acme/button

Environment Variables

The CLI supports environment variables for authentication with custom registries:

.env

V0_TOKEN=your_token_here
ACME_API_KEY=your_api_key

Use them in your components.json:

components.json

{
  "registries": {
    "@v0": {
      "url": "https://api.v0.dev/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${V0_TOKEN}"
      }
    }
  }
}

The CLI automatically loads .env, .env.local, and other environment files using dotenvx.

What Happens When You Add a Component?

When you run shadcn add button, the CLI:

Fetches the component from the registry
Transforms the code to match your project configuration
- Updates import paths based on your aliases
- Applies Tailwind prefix if configured
- Converts to JSX if TypeScript is disabled
- Adds “use client” for React Server Components
Installs dependencies required by the component
Writes the files to your project
Updates your CSS if needed (for new CSS variables)

All transformations are based on your components.json configuration. The CLI reads this file to understand your project structure.

Troubleshooting

Command not found

Make sure you’re using npx to run the command:

npx shadcn@latest add button

Not:

shadcn add button  # This won't work

Invalid configuration

If you get configuration errors, try:

Check your components.json is valid JSON
Verify path aliases match your tsconfig.json
Run npx shadcn@latest init --force to reset configuration

Component not found

If a component is not found:

Check the component name is correct
Run npx shadcn@latest search <name> to find available components
Make sure you have an internet connection (registry is fetched remotely)

Import errors after adding component

If you get import errors:

Check your path aliases in tsconfig.json match components.json
Restart your TypeScript server
Make sure dependencies were installed (check package.json)

Version

To check the CLI version:

npx shadcn@latest --version

Always use @latest to ensure you’re running the most recent version of the CLI. The package is updated frequently with bug fixes and new features.

Get Started

Installation

Customization

Guides

Integrations

CLI

CLI

Installation

Commands

init

Options

create

Options

add

Adding from URLs

Adding from Custom Registries

Options

diff

Options

view

Options

search

migrate

info

Usage Examples

Environment Variables

What Happens When You Add a Component?

Troubleshooting

Version

​CLI

​Installation

​Commands

​init

​Options

​create

​Options

​add

​Adding from URLs

​Adding from Custom Registries

​Options

​diff

​Options

​view

​Options

​search

​migrate

​info

​Usage Examples

​Environment Variables

​What Happens When You Add a Component?

​Troubleshooting

​Version

CLI

Installation

Commands

init

Options

create

Options

add

Adding from URLs

Adding from Custom Registries

Options

diff

Options

view

Options

search

migrate

info

Usage Examples

Environment Variables

What Happens When You Add a Component?

Troubleshooting

Version