CLI Commands

Command-line interface for interactive component management. The shadcn CLI provides 12 commands for initializing projects, adding components, viewing registry contents, checking for updates, and more.

Capabilities

init

Initializes a new project with shadcn/ui configuration. Installs dependencies, adds the cn utility function, configures Tailwind CSS, and sets up CSS variables for the project.

shadcn init [options]

Description: Sets up a new project with all necessary configuration for shadcn/ui components.

What it does:

• Installs required dependencies (Tailwind CSS, class-variance-authority, clsx, tailwind-merge)
• Creates or updates components.json configuration file
• Adds the cn utility function for className merging
• Configures Tailwind CSS with the selected style and base color
• Sets up CSS variables for theming

Options:

• Interactive prompts guide you through style selection, base color, TypeScript/JavaScript choice, and path configuration
• -c, --cwd <dir> - Set working directory

Example:

npx shadcn init

Exit Codes:

• 0 - Success
• 1 - General error (e.g., package manager not found, network error)
• 2 - Configuration error (invalid existing components.json)
• 4 - Validation error (invalid user input)

Agent Usage: For non-interactive use, ensure components.json exists or use programmatic API to create configuration. The command will fail if run in a directory that already has a valid components.json unless you're updating it.

Edge Cases:

• If components.json already exists, the command may prompt to update or overwrite
• If package manager (npm/yarn/pnpm) is not available, the command will fail with exit code 1
• If Tailwind CSS is not installed, the command will attempt to install it
• Network errors during dependency installation result in exit code 1

create

Creates a new project from scratch using a custom design system. Opens a website where you can build your custom design system and choose your framework.

shadcn create [options]

Description: Launches the project creation wizard for building a new project with shadcn/ui from the ground up.

What it does:

• Opens the shadcn/ui website for interactive project setup
• Allows you to choose framework (Next.js, Vite, Remix, etc.)
• Guides you through design system customization
• Generates a complete starter project with your chosen configuration

Example:

npx shadcn create

Agent Usage: This command requires browser interaction and is not suitable for programmatic use. Use init for programmatic setup. The command will attempt to open a browser; if this fails, it may display a URL to visit manually.

Exit Codes:

• 0 - Success (browser opened or URL displayed)
• 1 - General error (browser launch failed, network error)

add

Adds components to your project. The add command fetches components from registries and installs all required dependencies.

shadcn add [component...] [options]

Description: Installs one or more components into your project with automatic dependency resolution.

What it does:

• Fetches component files from the registry
• Resolves and installs all registry dependencies
• Installs npm dependencies and devDependencies
• Applies code transformations (imports, CSS variables, icon libraries)
• Updates Tailwind configuration if needed
• Updates CSS files with component styles
• Adds environment variables if required

Arguments:

• component - Component name(s) to add (optional for interactive mode). Can be:
  • Simple name: button (uses default registry)
  • Full name with registry: @shadcn/button
  • Multiple components: button card dialog

Options:

• -c, --cwd <dir> - Working directory
• -a, --all - Install all available components (interactive selection)
• -y, --yes - Skip confirmation prompts (required for non-interactive use)
• -o, --overwrite - Overwrite existing files without prompting
• -p, --path <path> - Custom installation path (overrides components.json aliases)

Examples:

# Interactive component selection
npx shadcn add

# Add single component
npx shadcn add button

# Add multiple components
npx shadcn add button card dialog

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

# Add with overwrite (non-interactive)
npx shadcn add button --yes --overwrite

# Add to custom path
npx shadcn add button --path src/components/custom

# Add all components (interactive)
npx shadcn add --all

Exit Codes:

• 0 - Success
• 1 - General error (network, file system, etc.)
• 2 - Configuration error (missing components.json)
• 3 - Registry error (item not found, network error, authentication failure)
• 4 - Validation error (invalid component name, circular dependency)

Agent Usage: Always use --yes flag to skip prompts. Always specify component names explicitly for programmatic use. Use --overwrite if you want to update existing components. Check exit codes to handle errors appropriately.

Edge Cases:

• If component already exists and --overwrite is not used, command will prompt (use --yes --overwrite to skip)
• If component name is invalid or not found, exit code 3 is returned
• If registry requires authentication and credentials are missing, exit code 3 is returned
• If circular dependencies are detected, exit code 4 is returned
• If file system permissions prevent writing, exit code 1 is returned
• If package manager installation fails, exit code 1 is returned
• If multiple components are specified and some fail, the command may partially succeed (check output)

Error Handling Example:

# Check if command succeeded
if npx shadcn add button --yes --overwrite; then
  echo "Component added successfully"
else
  exit_code=$?
  case $exit_code in
    2) echo "Error: components.json not found. Run: npx shadcn init" ;;
    3) echo "Error: Registry error. Check component name and registry configuration" ;;
    4) echo "Error: Validation error. Check component name format" ;;
    *) echo "Error: Unknown error (exit code: $exit_code)" ;;
  esac
fi

diff

Checks for updates against the registry. Compares your local components with their registry versions to detect changes and updates.

shadcn diff [component] [options]

Description: Shows differences between local components and registry versions.

What it does:

• Compares local component files with registry versions
• Displays unified diff showing changes
• Helps identify when components need updating
• Useful for tracking customizations

Arguments:

• component - Specific component to check (optional). If omitted, checks all installed components.

Options:

• -c, --cwd <dir> - Working directory

Examples:

# Check all components
npx shadcn diff

# Check specific component
npx shadcn diff button

# Check component from specific registry
npx shadcn diff @shadcn/button

Exit Codes:

• 0 - Success (no differences found or differences displayed)
• 1 - General error (file read error, network error)
• 2 - Configuration error (missing components.json)
• 3 - Registry error (component not found in registry)

Agent Usage: Use this to detect if local components have been modified and need updates or if customizations exist. The command outputs a diff format that can be parsed programmatically.

Edge Cases:

• If component file doesn't exist locally but is in registry, shows as new file
• If component exists locally but not in registry, shows error (exit code 3)
• If component file is identical to registry version, no output (exit code 0)
• Network errors during registry fetch result in exit code 3

view

Views items from the registry. Displays component information including description, type, files, and code.

shadcn view [items...] [options]

Description: Fetches and displays detailed information about registry items.

What it does:

• Fetches item metadata from registry
• Shows item description, type, and categories
• Lists all files included in the item
• Displays file contents
• Shows dependencies and registry dependencies

Arguments:

• items - Registry item(s) to view (e.g., @shadcn/button). Required. Can specify multiple items.

Options:

• -c, --cwd <dir> - Working directory

Examples:

# View single item
npx shadcn view @shadcn/button

# View multiple items
npx shadcn view @shadcn/button @shadcn/card

# View from custom registry
npx shadcn view @acme/special-button

# View without registry prefix (uses default)
npx shadcn view button

Exit Codes:

• 0 - Success
• 1 - General error
• 2 - Configuration error (missing components.json)
• 3 - Registry error (item not found, network error)

Agent Usage: Use programmatic getRegistryItems or view_items_in_registries MCP tool for structured data access. CLI output is formatted for human reading and may be difficult to parse programmatically.

Edge Cases:

• If item name doesn't include registry prefix and multiple registries are configured, uses first matching registry
• If item is not found in any registry, exit code 3 is returned
• If multiple items are specified and some fail, the command may partially succeed
• Network timeouts result in exit code 3

search

Searches items from registries using fuzzy matching. Finds components based on name and description.

shadcn search <registries...> [options]
shadcn list <registries...> [options]  # alias

Description: Searches for components in specified registries.

What it does:

• Performs fuzzy search across component names and descriptions
• Searches in the specified registries
• Returns paginated results
• Displays component names, types, and descriptions

Arguments:

• registries - Registry names or URLs to search (e.g., @shadcn, @acme). Required. Must start with @ for namespace-based registries.

Options:

• -c, --cwd <dir> - Working directory
• -q, --query <query> - Search query string (optional - omit to list all items)
• -l, --limit <number> - Maximum number of items to display (default: 100, max: 1000)
• -o, --offset <number> - Number of items to skip for pagination (default: 0, min: 0)

Examples:

# List all components from @shadcn registry
npx shadcn search @shadcn

# Search for specific component
npx shadcn search @shadcn --query button

# Search with query (alternative)
npx shadcn search @shadcn -q "input form"

# Search multiple registries
npx shadcn search @shadcn @acme

# With pagination
npx shadcn search @shadcn --limit 20 --offset 0

# Search with limit and offset for pagination
npx shadcn search @shadcn -q "card" --limit 10 --offset 10

Exit Codes:

• 0 - Success (results found or empty results)
• 1 - General error
• 2 - Configuration error (missing components.json)
• 3 - Registry error (registry not found, network error)
• 4 - Validation error (invalid registry name format, invalid limit/offset)

Agent Usage: Use programmatic searchRegistries function for structured results. CLI output is formatted for human reading. For programmatic use, prefer the API.

Edge Cases:

• If no query is provided, lists all items (may be slow for large registries)
• If limit exceeds maximum (1000), it's clamped to 1000
• If offset is negative, exit code 4 is returned
• If registry name doesn't start with @, exit code 4 is returned
• If registry is not configured, exit code 3 is returned
• Empty search results return exit code 0 (not an error)

migrate

Runs migrations for upgrading components. Supports migrating between icon libraries and updating to newer Radix UI versions.

shadcn migrate <command> [options]

Description: Performs automated code migrations for component upgrades.

Available Subcommands:

migrate icons

Migrates components between icon libraries.

shadcn migrate icons [from] [to] [options]

What it does:

• Transforms icon imports from one library to another
• Updates icon component usage patterns
• Updates package.json dependencies
• Supports: lucide, tabler, hugeicons, phosphor

Arguments:

• from - Source icon library name (optional for interactive mode)
• to - Target icon library name (optional for interactive mode)

Options:

• -c, --cwd <dir> - Working directory
• -y, --yes - Skip confirmation prompts

Examples:

# Interactive migration
npx shadcn migrate icons

# Migrate from lucide to phosphor
npx shadcn migrate icons lucide phosphor

# Non-interactive migration
npx shadcn migrate icons lucide phosphor --yes

Exit Codes:

• 0 - Success
• 1 - General error (file read/write error, transformation error)
• 2 - Configuration error (missing components.json, invalid icon library)
• 4 - Validation error (invalid library names)

Agent Usage: Specify both from and to parameters for non-interactive use. Use --yes to skip prompts. This modifies files in place - ensure version control is available.

Edge Cases:

• If icon library name is invalid, exit code 4 is returned
• If no components use icons, command succeeds with no changes
• If transformation fails for a file, that file is skipped and error is logged
• If package.json update fails, exit code 1 is returned

migrate radix

Migrates components to newer Radix UI versions.

shadcn migrate radix [options]

What it does:

• Updates Radix UI component imports and APIs
• Handles breaking changes in Radix UI updates
• Updates package.json dependencies

Options:

• -c, --cwd <dir> - Working directory
• -y, --yes - Skip confirmation prompts

Example:

npx shadcn migrate radix

# Non-interactive
npx shadcn migrate radix --yes

Exit Codes:

• 0 - Success
• 1 - General error
• 2 - Configuration error

Agent Usage: Run this when upgrading Radix UI versions. Check component compatibility first. Use --yes for non-interactive use.

Edge Cases:

• If no Radix UI components are found, command succeeds with no changes
• If migration rules are not available for target version, exit code 1 is returned

info

Displays project information including configuration, paths, and dependencies.

shadcn info [options]

Description: Shows comprehensive project information for debugging and verification.

What it does:

• Displays components.json configuration
• Shows resolved paths (components, utils, ui, lib, hooks)
• Lists installed component dependencies
• Shows Tailwind CSS configuration
• Displays icon library selection
• Shows registry configuration

Options:

• -c, --cwd <dir> - Working directory

Example:

npx shadcn info

Exit Codes:

• 0 - Success
• 2 - Configuration error (missing components.json)

Agent Usage: Use programmatic getRegistriesConfig for structured configuration access. CLI output is formatted for human reading.

Edge Cases:

• If components.json is missing, exit code 2 is returned
• If paths cannot be resolved, they are shown as null or error

build

Builds components for a shadcn registry. Used for creating custom registries.

shadcn build [options]

Description: Builds and packages components for registry distribution.

What it does:

• Compiles components for registry
• Generates registry metadata
• Creates component bundles
• Prepares components for sharing

Options:

• Configuration depends on build setup

Example:

npx shadcn build

Agent Usage: This is for registry creators, not typical component consumers. Requires specific project structure and configuration.

Exit Codes:

• 0 - Success
• 1 - General error (build failure)
• 2 - Configuration error

mcp

Starts the Model Context Protocol server for AI assistant integration.

shadcn mcp [options]

Description: Launches an MCP server that AI assistants can connect to for component management.

What it does:

• Starts MCP server on stdio
• Exposes 7 tools for AI assistants
• Enables AI-driven component discovery and addition
• Provides component search and viewing capabilities

Available MCP Tools:

• get_project_registries - Get configured registries
• list_items_in_registries - List all registry items
• search_items_in_registries - Search for components
• view_items_in_registries - View component details
• get_item_examples_from_registries - Get usage examples
• get_add_command_for_items - Get add command
• get_audit_checklist - Get post-addition checklist

Options:

• -c, --cwd <dir> - Set working directory

Example:

npx shadcn mcp

Exit Codes:

• 0 - Server started successfully (runs until terminated)
• 1 - General error (server startup failure)
• 2 - Configuration error (missing components.json)

Agent Usage: This is the primary interface for AI assistants. The server communicates via stdio using MCP protocol. The server runs until terminated (Ctrl+C or process termination). Ensure components.json exists before starting.

Edge Cases:

• If components.json is missing, server may start but tools will return errors
• Server reads from stdin and writes to stdout - ensure proper stdio handling
• If registry configuration is invalid, tools will return appropriate errors

mcp init

Initializes MCP configuration for AI clients.

shadcn mcp init [options]

Description: Configures the shadcn MCP server for use with AI assistants like Claude, Cursor, VS Code, and Codex.

What it does:

• Detects or prompts for AI client selection
• Installs required dependencies
• Configures client-specific MCP settings
• Creates appropriate configuration files

Options:

• --client <client> - AI client to configure (claude, cursor, vscode, codex). Required for non-interactive use.
• -c, --cwd <dir> - Set working directory

Supported Clients:

• claude - Claude Desktop
• cursor - Cursor IDE
• vscode - Visual Studio Code
• codex - Codex

Example:

# Interactive mode - prompts for client
npx shadcn mcp init

# Specify client directly
npx shadcn mcp init --client claude
npx shadcn mcp init --client cursor

Exit Codes:

• 0 - Success
• 1 - General error (configuration file write failure, dependency installation failure)
• 4 - Validation error (invalid client name)

Agent Usage: Specify --client flag for non-interactive setup. This configures the MCP client, not the server. The command creates configuration files in client-specific locations.

Edge Cases:

• If client name is invalid, exit code 4 is returned
• If configuration directory doesn't exist, it may be created
• If dependencies cannot be installed, exit code 1 is returned

registry:build

Builds registry items (internal registry command). Used for building official shadcn/ui registry.

shadcn registry:build [options]

Description: Internal command for building the shadcn/ui registry.

Example:

npx shadcn registry:build

Agent Usage: This is an internal command for registry maintainers, not for general use. Requires specific project structure and access to registry source.

Exit Codes:

• 0 - Success
• 1 - General error

registry:mcp

Starts registry MCP server (internal registry command). Internal server for registry operations.

shadcn registry:mcp [options]

Description: Internal MCP server for registry management.

Example:

npx shadcn registry:mcp

Agent Usage: This is an internal command for registry maintainers, not for general use.

Exit Codes:

• 0 - Success (server runs until terminated)
• 1 - General error

Global Options

All commands support these common options:

• -h, --help - Display help for command
• -v, --version - Display version number
• -c, --cwd <dir> - Set working directory

Configuration File

Commands read configuration from components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide",
  "menuColor": "default",
  "menuAccent": "subtle",
  "registries": {
    "@shadcn": "https://ui.shadcn.com/r/{name}.json",
    "@acme": {
      "url": "https://registry.acme.com/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    }
  }
}

Configuration Discovery:

• Commands search for components.json in the current directory and parent directories
• Uses cosmiconfig for configuration discovery
• Supports workspace/monorepo configurations

Command Exit Codes

For programmatic use, commands return standard exit codes:

• 0 - Success
• 1 - General error (file system, network, package manager, etc.)
• 2 - Configuration error (missing components.json, invalid configuration)
• 3 - Registry error (network error, item not found, authentication failure, parse error)
• 4 - Validation error (invalid input, invalid component name, circular dependency)

Exit Code Handling Example:

#!/bin/bash
# Example script for handling exit codes

npx shadcn add button --yes --overwrite
exit_code=$?

case $exit_code in
  0)
    echo "Success: Component added"
    ;;
  1)
    echo "Error: General error occurred"
    exit 1
    ;;
  2)
    echo "Error: Configuration error. Run: npx shadcn init"
    exit 1
    ;;
  3)
    echo "Error: Registry error. Check component name and network connection"
    exit 1
    ;;
  4)
    echo "Error: Validation error. Check component name format"
    exit 1
    ;;
  *)
    echo "Error: Unknown exit code: $exit_code"
    exit 1
    ;;
esac

Agent Integration Notes

1. Non-Interactive Usage: Always use --yes flag with add and migrate commands to skip prompts
2. Error Handling: Check exit codes and parse error messages for structured error handling
3. Configuration: Ensure components.json exists before running commands that require it (use init first)
4. Registry Access: For programmatic access, prefer the API functions over CLI commands for better error handling and structured data
5. File Operations: CLI commands modify files in place. Use version control for safety. Use --overwrite flag to update existing components
6. Dependency Management: The add command automatically installs npm dependencies. Ensure package manager (npm/yarn/pnpm) is available
7. Working Directory: Use -c, --cwd option to specify working directory for commands
8. Batch Operations: When adding multiple components, if one fails, the command may partially succeed. Check output for individual component status
9. Network Resilience: Registry operations may fail due to network issues. Implement retry logic for production use
10. Authentication: For private registries, ensure environment variables are set before running commands that access registries

Common Error Scenarios

Missing Configuration

# Error: components.json not found
# Solution: Run npx shadcn init first
npx shadcn init

Component Not Found

# Error: Component not found in registry
# Solution: Search for correct component name
npx shadcn search @shadcn --query button

Network Errors

# Error: Failed to fetch from registry
# Solution: Check network connection, retry, or check registry URL
npx shadcn info  # Verify registry configuration

Authentication Errors

# Error: Unauthorized access to registry
# Solution: Check environment variables and registry headers in components.json
echo $ACME_TOKEN  # Verify token is set

Circular Dependencies

# Error: Circular dependency detected
# Solution: Review component dependencies, may indicate registry configuration issue
npx shadcn view @shadcn/button  # Check component dependencies