Skip to main content

​
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

​
-t, --template
string
The template to use: next, vite, start, or next-monorepo
npx shadcn@latest init --template next
​
-b, --base-color
string
The base color: neutral, gray, zinc, stone, or slate
npx shadcn@latest init --base-color zinc
​
-y, --yes
boolean
default:"true"
Skip confirmation prompt
npx shadcn@latest init --yes
​
-d, --defaults
boolean
default:"false"
Use default configuration
npx shadcn@latest init --defaults
​
-f, --force
boolean
default:"false"
Force overwrite of existing configuration
npx shadcn@latest init --force
​
-c, --cwd
string
The working directory (defaults to current directory)
npx shadcn@latest init --cwd ./my-app
​
--src-dir
boolean
Use the src directory when creating a new project
npx shadcn@latest init --src-dir
​
--css-variables
boolean
default:"true"
Use CSS variables for theming
npx shadcn@latest init --css-variables
npx shadcn@latest init --no-css-variables
​
--rtl
boolean
default:"false"
Enable RTL support
npx shadcn@latest init --rtl
​
--no-base-style
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

​
-t, --template
string
The template to use: next, vite, or start
npx shadcn@latest create my-app --template vite
​
-p, --preset
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?...
​
-c, --cwd
string
The working directory
npx shadcn@latest create --cwd ./projects
​
--src-dir
boolean
Use the src directory
npx shadcn@latest create my-app --src-dir
​
--rtl
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

​
-y, --yes
boolean
default:"false"
Skip confirmation prompt
npx shadcn@latest add button --yes
​
-o, --overwrite
boolean
default:"false"
Overwrite existing files
npx shadcn@latest add button --overwrite
​
-c, --cwd
string
The working directory
npx shadcn@latest add button --cwd ./my-app
​
-a, --all
boolean
default:"false"
Add all available components
npx shadcn@latest add --all
​
-p, --path
string
The path to add the component to
npx shadcn@latest add button --path ./src/components
​
-s, --silent
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

​
-y, --yes
boolean
default:"false"
Skip confirmation prompt
npx shadcn@latest diff button --yes
​
-c, --cwd
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

​
-c, --cwd
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

​
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:
  1. Fetches the component from the registry
  2. 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
  3. Installs dependencies required by the component
  4. Writes the files to your project
  5. 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

Make sure you’re using npx to run the command:
npx shadcn@latest add button
Not:
shadcn add button  # This won't work
If you get configuration errors, try:
  1. Check your components.json is valid JSON
  2. Verify path aliases match your tsconfig.json
  3. Run npx shadcn@latest init --force to reset configuration
If a component is not found:
  1. Check the component name is correct
  2. Run npx shadcn@latest search <name> to find available components
  3. Make sure you have an internet connection (registry is fetched remotely)
If you get import errors:
  1. Check your path aliases in tsconfig.json match components.json
  2. Restart your TypeScript server
  3. 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us