How to use CLI

Learn how to use the shadcn/studio CLI to install components, blocks, and themes into your project seamlessly.

Overview

shadcn/studio enhances the original shadcn/ui CLI, offering an easy way to install custom 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.

Setup

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

CLI Versions

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

CLI v3

Recommended

CLI v3 allows namespaced registry for easier access:

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.

CLI v2

Legacy

CLI v2 requires direct URLs for installation:

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.

1. Installing Components

Components are enhanced versions of shadcn/ui components, with added functionality and styling.

Note: Components are available in both free and pro registries. Use @shadcn-studio for free components only, or @ss-components for access to both free and premium components (premium ones require authentication).

2. Installing Blocks

Free Blocks Only

Free + Premium Blocks

3. Installing Themes

Note: Themes are available in both free and pro@shadcn-studio for free themes only, or @ss-themes for access to both free and premium themes (premium ones require authentication).

Free Themes Only

Free + Premium Themes

User-Generated Themes

Package Managers

The Shadcn CLI supports different package managers for your project:

pnpmRecommended

npm

yarn

bun

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

Recommended 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.