How to use Shadcn CLI

Learn how to use Shadcn CLI to install our components, blocks, and themes into your project seamlessly.

Overview

shadcn/studio uses the shadcn/ui CLI, offering an easy way to install our components, blocks, and themes. The CLI is designed to help you quickly add ready-to-use assets without the need for NPM packages, following a simple "copy-and-paste" approach. Please refer to the official shadcn/ui CLI documentation for more details on its core functionality.

Setup

Before using the shadcn/studio CLI, make sure that you've installed shadcn in your project by following the official installation guide.

shadcn CLI Support

There are two CLI versions available to accommodate different user preferences and workflows:

shadcn CLI v3

Recommended

Ground-up rewrite focused on registries at scale (namespaces, auth, private/pro) and AI/automation (MCP).

Registry Structure Explanation

We provide multiple registries to organize content by type and access level. Here's why each registry exists:

Namespace	Content Type
`@shadcn-studio`	Free components, blocks, themes
`@ss-components`	Free + premium components
`@ss-blocks`	Free + premium blocks
`@ss-themes`	Free + premium + user-generated themes

Key Benefits of Multiple Registries:

Simplified Access: Use @shadcn-studio for quick access to any free content
Category Organization: Category-specific registries (@ss-components, @ss-blocks, @ss-themes) provide better content management
Premium Support: Category-specific registries support both free and premium content with proper authentication
User Content: @ss-themes also includes user-generated themes alongside official content

Configuring CLI v3

To use CLI v3 with our custom content, you need to configure the components.json file in your project.

For Free Content Only

Access all free components, blocks, and themes without authentication using the free registry.

For Free + Premium Content

Access both free and premium content. Free content works without authentication, premium content requires your credentials:

Environment Variables Setup

You must create or update your .env file to store your shadcn/studio credentials.

Finding Your Credentials

Email Address: Your email address used during registration (found in your account settings).
License Key: Your license key will be found in your billing page.

Important:

Ensure .env is added to your .gitignore to prevent accidental commits of your credentials.
The EMAIL and LICENSE_KEY will automatically be replaced by the CLI.

Security Tip:

Never commit your credentials to a repository. Always use environment variables for CLI v3, or be cautious with URL parameters in CLI v2 commands.

shadcn CLI v2

Legacy

Legacy shadcn CLI version. CLI v2 requires direct URLs for installation:

For Free Content Only

Access all free components, blocks, and themes without authentication using direct URLs.

For Free + Premium Content

Access premium content by adding your credentials as URL parameters to the installation command. The free content works without authentication as mentioned above.

Installation

You can install components, blocks, and themes using the CLI commands below.

Note:

See the next section for how to use these commands with different package managers.

Installing Components

Components are enhanced versions of shadcn/ui components, with added functionality and styling. You can refer to the components documentation for more information.

Free Components Only

Premium Components

Installing Blocks

You can refer to the blocks documentation for more information.

Free Blocks Only

Premium Blocks

Installing Themes

You can refer to the themes documentation for more information.

Important:

You need to manually install the font dependencies and add them to your layout file, as they are not included in the themes. You can find the fonts from Google Fonts.

Free Themes Only

Premium Themes

User-Generated Themes

Package Managers

The Shadcn CLI supports different package managers for your project:

Advanced Usage

Installing Multiple Items

You can install multiple items at once by listing them:

Force Overwriting Existing Files

If you want to overwrite existing files during installation:

Troubleshooting

1. Block/Component/Theme Not Found

Error: Block/Component/Theme not found

"The requested block/component/theme could not be found. Please check the block/component/theme name and try again."

Solution:

Verify the spelling of the block/component/theme name.
Ensure that the block/component/theme exists in the registry.

2. Access Denied - Missing Credentials

Error: Access denied

"License key and email are required. Please refer to our documentation for authentication."

Solution:

For CLI v3: Ensure your .env file contains EMAIL and LICENSE_KEY.
For CLI v2: Include ?email={YOUR_EMAIL}&license_key={YOUR_LICENSE_KEY} in the URL.

3. Invalid Credentials

Error: Access denied

"Your license key or email is invalid. Please check your credentials and try again."

Solution:

Double-check your email (it must match your registered account).
Verify your license key (check your purchase email).

Best Practices

Use CLI v3 for simplicity and ease of use.
Keep credentials secure by using environment variables or ensuring they aren't saved in command history.
Regularly update your Shadcn CLI to stay up to date with new features.
Customize components after installation to ensure they match your project's design requirements.