How to use the Shadcn CLI

The Shadcn CLI is the primary way to install Shadcn Space components, blocks, and templates into your project. It allows you to add production-ready UI directly into your codebase while preserving full control and customization.

Overview

Shadcn Space CLI is built on top of the official Shadcn UI CLI, so the workflow feels instantly familiar if you’ve used Shadcn before. Instead of installing components as opaque NPM packages, the CLI copies real, readable code directly into your project.

This approach follows the copy-and-paste philosophy of Shadcn UI — giving you complete ownership over styles, logic, and structure. You can modify, extend, or refactor the generated components without worrying about breaking upstream dependencies.

For a deeper understanding of the core CLI mechanics, refer to the official Shadcn UI CLI documentation.

Setup

Before using Shadcn Space with the CLI, you must have Shadcn UI installed and configured in your project. This includes Tailwind CSS, the required path aliases, and the base configuration files.

If you haven’t set this up yet, please follow the below guide.

Using the New “Create Project” Feature

Shadcn now provides a visual Create Project experience that allows you to configure your setup before generating the CLI command. Instead of manually initializing everything, you can select your preferred component library, style system, icon library, theme, and more — then copy the generated command.

  1. Visit ui.shadcn.com/create and open the configuration panel.
  2. Choose your preferred configuration:

    • Select your Component Library: Base UI (recommended)

      Base UI
      Radix UI

    • Select your Visual Style:

      Vega
      The classic shadcn/ui look. Clean, neutral, and familiar.
      Nova
      Reduced padding and margins for compact, data-heavy layouts.
      Maia
      Soft and rounded, featuring generous spacing and curves.
      Lyra
      Boxy and sharp. Pairs exceptionally well with mono fonts.
      Mira
      Ultra-compact. Engineered for dense professional interfaces.

    • Select your Base Color:

      Neutral
      Zinc
      Slate
      Zinc
      Gray

    • Select your Theme:

      Neutral
      Amber
      Blue
      Cyan
      Emerald
      Fuchsia
      Green
      Indigo
      Lime
      Orange
      Pink

    • Select your Icon Library:

      Lucide
      Tabler Icons
      Heroicons
      Phosphor Icons
      Remix Icon

    • Select your Font:

      Inter
      Noto Sans
      Nunito Sans
      Figtree

    • Select your Radius:

      Default
      None
      Small
      Medium
      Large

    • Select your Menu Color:

      Default
      Inverted

    • Select your Menu Accent:

      Subtle
      Bold
  3. Click the Create Project button in the top-right corner.
  4. Copy the generated CLI command shown on the screen or you can use the command below.

    5. Run the following command to create a Next.js + shadcn/ui project.

    npx shadcn@latest create --preset "https://ui.shadcn.com/init?base=base&style=vega&baseColor=neutral&theme=neutral&iconLibrary=lucide&font=inter&menuAccent=subtle&menuColor=default&radius=default&template=next" --template next
  5. Open your terminal inside your project directory and paste the command to complete the setup.

Once the command finishes running, your project will be fully configured with Shadcn UI and ready to use with Shadcn Space.

If you have already set up your project, and want to migrate from Radix UI to Base UI, you can follow the migration guideMigrating from Radix UI to Base UI.

CLI Versions

Shadcn UI provides multiple CLI versions to support different workflows. Shadcn Space works best with the latest version.

Shadcn CLI v3Recommended

Version 3 introduces namespace-based registries, authentication for private registries, and AI-assisted setup tools. These improvements make it easier to manage multiple component sources and automate repetitive setup tasks.

Shadcn Space leverages this namespace system to distribute both free and premium components in a scalable and maintainable way.

RegistryIncludes
@shadcn-spaceFree and premium layout blocks, components, and templates

Configure Shadcn CLI v3

Shadcn CLI v3 supports custom registries through namespaces. By configuring a registry, you can install both free and premium Shadcn Space components directly into your project.

Step 1: Update components.json

Add the @shadcn-space registry to your components.json file. This tells the CLI where to fetch components and how to authenticate premium requests.

Step 2: Set Environment Variables

Premium components require authentication. Store your credentials securely using environment variables instead of hardcoding them.

Find Your Credentials

You’ll need the following details to access premium resources:

  1. Email address: Use the email associated with your Shadcn Space account.
  2. License key: Available in your Dashboard.
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.

Installing Components & Blocks

Shadcn Space supports both Shadcn CLI v3 and v2. We recommend using CLI v3 for new projects, but v2 remains supported for legacy setups.

Using Shadcn CLI v3

Recommended

CLI v3 introduces namespace-based registries. Once you’ve configured the @shadcn-space registry, you can install both free and premium components using simple commands.

Install a component

npx shadcn@latest add @shadcn-space/button

Install a block

npx shadcn@latest add @shadcn-space/hero-section

Using Shadcn CLI v2

Legacy

CLI v2 does not support namespaces. Components and blocks are installed using direct registry JSON URLs. Both free and premium content are available through separate endpoints.

Install free components

npx shadcn@latest add https://shadcnspace.com/r/hero-01.json

Install premium components or blocks

npx shadcn@latest add https://shadcnspace.com/r/hero-01.json
Important :

Shadcn CLI v3 requires authentication details to be configured in components.json. Make sure you have added your email and license key before installing premium components or blocks.

Note: Premium installs via CLI v2 require valid credentials configured in your environment variables. CLI v3 is recommended for a smoother and more secure experience.

Package Managers

Install components and blocks using your preferred package manager. The Shadcn CLI works the same across all managers — choose the one that matches your project setup.

Run the following command to install the selected component directly into your project.

npx shadcn@latest add @shadcn-space/button

Tip: The CLI automatically fetches files from your configured registry in components.json.

Advanced Usage

The Shadcn CLI supports advanced workflows that help you move faster while maintaining full control over your codebase.

Installing Multiple Items

You can install multiple components or blocks in a single command. This is useful when setting up a new page or feature.

npx shadcn@latest add @shadcn-space/button @shadcn-space/card

Force Overwriting Existing Files

If a component already exists, the CLI will prompt before overwriting. You can skip prompts and force updates using the--overwrite flag.

npx shadcn@latest add @shadcn-space/button --overwrite

Troubleshooting

If you encounter issues while installing components, the solutions below should resolve most common problems.

Block / Component / Theme Not Found

This usually means the requested item name is incorrect or the registry is not configured properly.

Solution:

  • Verify the component or block name in the documentation.
  • Ensure components.json includes the @shadcn-space registry.
  • Check your internet connection.

Access Denied – Missing Credentials

Premium components require authentication.

Solution:

  • Add EMAIL and LICENSE_KEY to your .env file.
  • Restart the CLI after updating environment variables.
  • Ensure you are using CLI v3.

Invalid Credentials

This occurs when provided credentials are incorrect or expired.

Solution:

  • Double-check your email and license key in .env.
  • Regenerate your license key from the dashboard if needed.
  • Ensure there are no extra spaces or quotes.

Best Practices

  • Use Shadcn CLI v3 for the simplest setup, namespace support, and secure access to premium registries.
  • Keep credentials secure by storing them in environment variables and ensuring they are not hardcoded or saved in command history.
  • Regularly update the Shadcn CLI to stay up to date with new features, fixes, and improvements.
  • Customize components after installation to ensure they match your project’s design system and functional requirements — you fully own the code.