export const title = "CLI tool"
export const description = "The Untitled UI CLI tool helps you quickly scaffold projects and add components to your existing projects. This guide will help you understand how to use the CLI effectively."
export const metaDescription = "Quickly scaffold projects and add components with our custom CLI. Untitled UI React is the world's largest collection of open-source React components."


<Divider />

## Installation

The `untitledui` CLI tool is available directly as a command-line utility and doesn't require any installation. You can run it using either npx or bunx:

<CodeTabs>
  <CodeTabList items={[
    { id: "npx", label: "npx" },
    { id: "bunx", label: "bunx" }
  ]}/>
  <CodeTabPanel id="npx">
    ```bash
    npx untitledui@latest [command]
    ```
  </CodeTabPanel>
  <CodeTabPanel id="bunx">
    ```bash
    bunx untitledui@latest [command]
    ```
  </CodeTabPanel>
</CodeTabs>

<Divider />

## Init command

The `init` command helps you scaffold a new project with Untitled UI components and configurations pre-installed.


<Tabs className="w-full mt-8">
    <TabList type="underline" items={[{ id:'next', label:'Next.js' }, { id:'vite', label:'Vite' }]} />

    <TabPanel id="next">
        <Steps>
            <Step title="Create a new project">
                Run this command in your root folder to create a new Next.js project:

                ```bash
                npx untitledui@latest init --nextjs
                ```

                While running the command, you'll be asked a few questions to set up your project:

                ```bash
                ? What is your project named? › untitled-ui
                ? Which color would you like to use as the brand color? ›
                ❯   brand
                    red
                    orange
                    amber
                    yellow
                    lime
                    green
                    ...
                    zinc
                    neutral
                    stone
                ```

                This will create a new Next.js project in the `untitled-ui` directory with all the necessary configurations and components pre-installed. The choices are Tailwind's built-in palettes; picking one points the `--color-brand-*` variables in `theme.css` at it, and `brand` keeps the default purple. You can change the brand color at any time later (see [Theming](/docs/theming)).
            </Step>
            <Step title="Ready to go!">
                Great! You're all set to start using Untitled UI components.

                If something is missing, you can copy/paste what you need into your project directly from individual [components](/components) pages.
            </Step>
        </Steps>
    </TabPanel>

    <TabPanel id="vite">
        <Steps>
            <Step title="Create a new project">
                Run this command in your root folder to create a new Vite project:

                ```bash
                npx untitledui@latest init --vite
                ```

                While running the command, you'll be asked a few questions to set up your project:

                ```bash
                ? What is your project named? › untitled-ui
                ? Which color would you like to use as the brand color? ›
                ❯   brand
                    red
                    orange
                    amber
                    yellow
                    lime
                    green
                    ...
                    zinc
                    neutral
                    stone
                ```

                This will create a new Vite project in the `untitled-ui` directory with all the necessary configurations and components pre-installed. The choices are Tailwind's built-in palettes; picking one points the `--color-brand-*` variables in `theme.css` at it, and `brand` keeps the default purple. You can change the brand color at any time later (see [Theming](/docs/theming)).
            </Step>
            <Step title="Ready to go!">
                Great! You're all set to start using Untitled UI components.

                If something is missing, you can copy/paste what you need into your project directly from individual [components](/components) pages.
            </Step>
        </Steps>
    </TabPanel>
</Tabs>

### Command options

These are the available options for the `init` command:

| Option | Description |
| --- | --- |
| `--nextjs` | Initialize a Next.js project |
| `--vite` | Initialize a Vite project |
| `-c, --color <color-name>` | Tailwind palette to use as the brand color, e.g. `blue` or `emerald`. See [Theming](/docs/theming) for the full list |
| `-o, --overwrite` | Overwrite existing files |
| `--colors-list` | Show the available colors list |
| `-y, --yes` | Non-interactive mode — skip all prompts and use defaults (for AI agents/CI). Falls back to the project's existing brand color, or `brand` if none is set. Combine with `-c, --color` to pick a different one explicitly. |
| `--license <key>` | API key for PRO access (alternative to the key stored by `login`) |
| `--lib-version <version>` | Component library version to set up (`7` or `8`). Auto-detected from `components.json` if not specified. |

<Divider />

## Add command

The `add` command allows you to add specific Untitled UI components to your existing project.

<Steps>
  <Step title="Add components">
    To add a specific component:
    
    ```bash
    npx untitledui@latest add button
    ```
    
    You can add multiple components at once:
    
    ```bash
    npx untitledui@latest add button toggle avatar
    ```
    
    If you run the command without specifying any components, you'll first be asked to select a component type:
    
    ```bash
    npx untitledui@latest add
    ```
    
    This will display a type selection interface:
    
    ```bash
    ? What type of component are you adding? ›
    ❯ base
      marketing
      shared-assets
      application
      foundations
    ```
    
    After selecting a type, you'll see available components in that category:
    
    ```bash
    ? Which components would you like to add? ›
    ❯ ◯ button
      ◯ card
      ◯ dropdown
      ◯ input
      ◯ modal
      ◯ table
      ◯ tabs
      ◯ toast
      ◯ toggle
      ◯ tooltip
    ```
    
    You can navigate through the list using arrow keys, select components with the spacebar, and confirm your selection with Enter.
  </Step>
  <Step title="PRO components">
    For PRO components, you need to be authenticated:
    
    ```bash
    npx untitledui@latest login
    npx untitledui@latest add pro-component
    ```
  </Step>
  <Step title="Customization options">
    The add command offers several options:

    ```bash
    # Specify where to add components
    npx untitledui@latest add button --path src/components

    # Specify project directory
    npx untitledui@latest add button --dir ./my-project

    # Overwrite existing files
    npx untitledui@latest add button --overwrite

    # Non-interactive mode (for AI agents/CI)
    npx untitledui@latest add button --yes
    ```
  </Step>
</Steps>

### Command options

These are the available options for the `add` command:

| Option | Description |
| --- | --- |
| `-a, --all` | Add all available components |
| `-o, --overwrite` | Overwrite existing files |
| `-p, --path <path>` | The path to add the component to |
| `-d, --dir <directory>` | The directory where the project is located |
| `-t, --type <type>` | The type of the component to add (`base`, `marketing`, `shared-assets`, `application`, `foundations`) |
| `--include-all-components` | Automatically include all base components without prompting |
| `-y, --yes` | Non-interactive mode — use defaults for all prompts (for AI agents/CI). Implies `--include-all-components` and `--overwrite`. |
| `--license <key>` | API key for PRO access (alternative to the key stored by `login`) |
| `--lib-version <version>` | Component library version to pull (`7` or `8`). Auto-detected from `components.json` if not specified. |

<Divider />

## Login command

The `login` command allows you to authenticate with Untitled UI to access PRO components through the CLI.

<Steps>
  <Step title="Interactive authentication">
    To authenticate with your Untitled UI account:
    
    ```bash
    npx untitledui@latest login
    ```
    
    This will:
    1. Open your browser automatically
    2. Check if you're already signed in to Untitled UI
    3. **If already signed in**: Authenticate immediately and return to CLI
    4. **If not signed in**: Redirect to the sign-in page, send a magic link to your email, and authenticate after you click the link

    Login only succeeds for accounts that hold a React license, either purchased directly or through a team seat. Other accounts see a "No PRO license found" error in the terminal.
  </Step>
  <Step title="What happens after login">
    Once authenticated, you can access PRO components without authenticating again.
    
    Your authentication is saved locally and will persist across CLI sessions.
  </Step>
</Steps>

<Divider />

## Search command

The `search` command lets you find components, page templates, and icons using natural language. It uses the same semantic search that powers our [MCP server](/integrations/mcp) — it understands both the text description and visual appearance of every component, so you can search for things like "login page with customer reviews" and get accurate results.

<Steps>
  <Step title="Search for anything">
    Describe what you need in plain language. The search runs across components, templates, and icons simultaneously:

    ```bash
    npx untitledui@latest search "login page with customer reviews"
    ```

    Results are grouped by type, with the install command for the top match:

    ```
    Components (5)

    1. login-split-quote-image-01  PRO  (marketing)
       Split-layout login page with customer testimonial quote,
       portrait photo, and carousel navigation arrows.
       carousel-navigation  image-display

    2. login-split-mockup-quote  PRO  (marketing)
       Split-layout login page with five-star rating, customer
       testimonial quote, and app dashboard screenshot mockup.
       app-mockup

    Install: npx untitledui@latest add login-split-quote-image-01 --yes

    Templates (5)

    1. landing-pages/14  (landing · full-width)
       Stacked landing page with testimonials, newsletter signup,
       metrics, and contact form with star ratings.

    Install: npx untitledui@latest example landing-pages/14 --yes

    Icons (5)

    1. Star01  (general)
       import { Star01 } from "@untitledui/icons"
    ```
  </Step>
  <Step title="Filter by type">
    You can narrow your search to a specific type:

    ```bash
    # Only search components
    npx untitledui@latest search "dark pricing table" --type components

    # Only search templates
    npx untitledui@latest search "fintech dashboard" --type templates

    # Only search icons
    npx untitledui@latest search "arrow" --type icons
    ```
  </Step>
  <Step title="More options">
    ```bash
    # Get more results
    npx untitledui@latest search "modal file upload" --limit 10

    # With PRO access
    npx untitledui@latest search "split login testimonial" --key YOUR_API_KEY
    ```
  </Step>
</Steps>

### Command options

These are the available options for the `search` command:

| Option | Description |
| --- | --- |
| `-t, --type <type>` | Filter results by type: `components`, `templates`, `icons`, `all` (default: `all`) |
| `-l, --limit <number>` | Maximum results per category (default: 5) |
| `-k, --key <key>` | API key for PRO component access |
| `--lib-version <version>` | Component library version (`7` or `8`). Defaults to `8`. |

<Divider />

## Adding example pages

The `example` command allows you to add complete example pages to your project or initialize new projects based on example pages. These example pages include fully functional pages with all necessary components, styling, and functionality.

<Steps>
  <Step title="Interactive example selection">
    To browse and add an example interactively:
    
    ```bash
    npx untitledui@latest example
    ```
    
    This will prompt you to select from available example categories:
    
    ```bash
    ? Select which type of example you want to add ›
    ❯ Application
      Marketing
    ```
    
    After selecting a category, you'll see specific examples available in that category, and then be prompted for where to place the files:
    
    ```bash
    ? Where would you like to add the dashboards-01 example? › app
    ? Where would you like to add the components? › components
    ```
  </Step>
  <Step title="Add specific examples">
    You can directly specify an example to add:
    
    ```bash
    # Add a specific dashboard example
    npx untitledui@latest example dashboards-01
    ```
    
    For nested examples, you can specify the full path:
    
    ```bash
    npx untitledui@latest example dashboards-01/01
    ```
  </Step>
  <Step title="PRO examples">
    Many examples require PRO access. If you try to access a PRO example without authentication, you'll see:
    
    ```bash
    🔒 The dashboards-01 example requires PRO access.

    To access PRO examples:
      → If you've already purchased: npx untitledui@latest login
      → To purchase PRO examples: https://www.untitledui.com/buy/react
    ```
    
    Simply authenticate first, then add the example:
    
    ```bash
    npx untitledui@latest login
    npx untitledui@latest example dashboards-01
    ```
  </Step>
  <Step title="Customization options">
    The example command offers several options for customization:

    ```bash
    # Specify where to add the example page
    npx untitledui@latest example dashboards-01/05 --example-path src/app/dashboard

    # Specify where to add the components
    npx untitledui@latest example dashboards-01/05 --path components/ui

    # Overwrite existing files
    npx untitledui@latest example dashboards-01/05 --overwrite

    # Non-interactive mode (for AI agents/CI)
    npx untitledui@latest example dashboards-01/05 --yes
    ```
  </Step>
  <Step title="What gets added">
    When you add an example, the CLI will:
    
    1. **Add the main example page** to your specified directory (default: `app/` or `pages/`)
    2. **Install required components** that the example uses
    3. **Install dependencies** needed for the example
    4. **Configure imports** to match your project structure
    5. **Prompt for component selection** if multiple components are needed
    
    The example will be fully functional and ready to use in your project.
  </Step>
</Steps>

### Command options

These are the available options for the `example` command:

| Option | Description |
| --- | --- |
| `-o, --overwrite` | Overwrite existing files. |
| `-p, --path <path>` | The path to add the components to. |
| `-e, --example-path <path>` | The path to add the example file to. |
| `-c, --color <color-name>` | Brand color for the project. Forwarded to `init`, used when the project doesn't already have one set. |
| `--include-all-components` | Automatically include all components from the example without prompting. |
| `-y, --yes` | Non-interactive mode — skip every prompt (brand color, framework, paths, overwrite confirmations) and use defaults. Implies `--include-all-components` and `--overwrite`. |
| `--license <key>` | API key for PRO access (alternative to the key stored by `login`). |
| `--lib-version <version>` | Component library version to pull (`7` or `8`). Auto-detected from `components.json` if not specified. |

<Divider />

## Upgrade command

The `upgrade` command migrates a v7 project to v8: it replaces `theme.css` while keeping your brand colors, renames utility classes and Badge colors, updates dependencies and config files, and writes `upgrade-report.json` (plus `UPGRADE-INSTRUCTIONS.md` when manual review is needed). See the [upgrade guide](/docs/upgrade) for the full walkthrough.

```bash
npx untitledui@latest upgrade --dry-run
npx untitledui@latest upgrade
```

| Option | Description |
| --- | --- |
| `--dry-run` | Preview changes without writing files |
| `--skip-theme` | Skip the `theme.css` replacement |
| `--skip-deps` | Skip dependency updates |
| `--skip-config` | Skip config file updates |
| `--path <dir>` | Directory to scan for source files |
| `-y, --yes` | Skip prompts and use defaults |

<Divider />

## Migrate command

The `migrate` command converts physical Tailwind classes (`ml-`, `pl-`, `left-`, …) to logical ones (`ms-`, `ps-`, `start-`, …) and swaps directional icons so your project works in RTL layouts. It works on v7 and v8 projects. See the [RTL guide](/docs/rtl) for what gets converted.

```bash
npx untitledui@latest migrate --dry-run
npx untitledui@latest migrate
npx untitledui@latest migrate src/components
```

| Option | Description |
| --- | --- |
| `[path]` | Path to migrate (defaults to the current directory) |
| `--dry-run` | Preview changes without writing files |
| `--skip-icons` | Skip directional icon swapping |
| `-y, --yes` | Skip prompts and use defaults |

<Divider />

## Version support

The CLI supports both v7 and v8 of the component library. By default, it pulls the latest version (v8). If your project is still on v7, you can keep pulling v7 components without upgrading.

### Auto-detection

The `init`, `add` and `example` commands read the `version` field in your project's `components.json` to determine which version to pull:

- `"version": "7"` in `components.json` — pulls v7 components
- `"version": "8"` or no version field — pulls v8 components (default)

### Manual override

You can override the detected version with the `--lib-version` flag. The `search` command does not read `components.json`; it searches v8 unless you pass `--lib-version 7`:

```bash
npx untitledui@latest add button --lib-version 7

npx untitledui@latest example dashboards-01/05 --lib-version 7
```

<Divider />

## Usage examples

Here are some common usage patterns for the Untitled UI CLI:

<Tabs className="w-full mt-8">
  <TabList type="underline" items={[{ id:'next', label:'Next.js' }, { id:'vite', label:'Vite' }]} />
  
  <TabPanel id="next" className="mt-8">
    <CodeTabs>
      <CodeTabList items={[
        { id: "initialize", label: "Create a new project" },
        { id: "authenticate", label: "Authentication" },
        { id: "add", label: "Add components" },
        { id: "search", label: "Search" },
        { id: "examples", label: "Add examples" }
      ]}/>
      <CodeTabPanel id="initialize">
        ```bash
        # Create a new Next.js project with Untitled UI
        npx untitledui@latest init untitledui-app --nextjs

        # Navigate to your new project
        cd untitledui-app

        # Start the development server
        npm run dev
        ```
      </CodeTabPanel>
      <CodeTabPanel id="authenticate">
        ```bash
        # Authenticate with Untitled UI for PRO components
        npx untitledui@latest login
        
        # You only need to do this once per machine
        # Your authentication will be saved locally
        ```
      </CodeTabPanel>
      <CodeTabPanel id="add">
        ```bash
        # Add free components to existing project
        npx untitledui@latest add button toggle avatar
        
        # Add PRO components (requires authentication)
        npx untitledui@latest login
        npx untitledui@latest add charts-base
        
        # The components will be added to your project's components directory
        ```
      </CodeTabPanel>
      <CodeTabPanel id="search">
        ```bash
        # Search for components, templates, and icons
        npx untitledui@latest search "modal with file upload"

        # Search only templates
        npx untitledui@latest search "dark landing page with pricing" --type templates

        # Search only icons
        npx untitledui@latest search "arrow" --type icons
        ```
      </CodeTabPanel>
      <CodeTabPanel id="examples">
        ```bash
        # Add a complete page example to your project
        npx untitledui@latest example
        
        # Add a specific dashboard example
        npx untitledui@latest example dashboards-01/05
        
        # Add example to specific directory
        npx untitledui@latest example landing-pages/01 --example-path src/app/landing
        ```
      </CodeTabPanel>
    </CodeTabs>
  </TabPanel>
  
  <TabPanel id="vite" className="mt-8">
    <CodeTabs>
      <CodeTabList items={[
        { id: "initialize", label: "Create a new project" },
        { id: "authenticate", label: "Authentication" },
        { id: "add", label: "Add components" },
        { id: "search", label: "Search" },
        { id: "examples", label: "Add examples" }
      ]}/>
      <CodeTabPanel id="initialize">
        ```bash
        # Create a new Vite project with Untitled UI
        npx untitledui@latest init untitledui-app --vite
        
        # Navigate to your new project
        cd untitledui-app
        
        # Start the development server
        npm run dev
        ```
      </CodeTabPanel>
      <CodeTabPanel id="authenticate">
        ```bash
        # Authenticate with Untitled UI for PRO components
        npx untitledui@latest login
        
        # You only need to do this once per machine
        # Your authentication will be saved locally
        ```
      </CodeTabPanel>
      <CodeTabPanel id="add">
        ```bash
        # Add free components to existing project
        npx untitledui@latest add button toggle avatar
        
        # Add PRO components (requires authentication)
        npx untitledui@latest login
        npx untitledui@latest add charts-base
        
        # The components will be added to your project's components directory
        ```
      </CodeTabPanel>
      <CodeTabPanel id="search">
        ```bash
        # Search for components, templates, and icons
        npx untitledui@latest search "modal with file upload"

        # Search only templates
        npx untitledui@latest search "dark landing page with pricing" --type templates

        # Search only icons
        npx untitledui@latest search "arrow" --type icons
        ```
      </CodeTabPanel>
      <CodeTabPanel id="examples">
        ```bash
        # Add a complete page example to your project
        npx untitledui@latest example
        
        # Add a specific dashboard example
        npx untitledui@latest example dashboards-01/05
        
        # Add example to specific directory
        npx untitledui@latest example landing-pages/01 --example-path src/app/landing
        ```
      </CodeTabPanel>
    </CodeTabs>
  </TabPanel>
</Tabs>

<Divider />

<FAQ
  faqs={[
    {
      question: "How do I access PRO components?",
      answer: "You can access PRO components by authenticating with the `npx untitledui@latest login` command. This will open your browser for a one-time authentication process."
    },
    {
      question: "Do I need to login every time I use the CLI?",
      answer: "No, you only need to login once per machine. Your authentication credentials are saved locally and will persist across CLI sessions."
    },
    {
      question: "Can I use the CLI with an existing project?",
      answer: "Yes, you can use the `add` command to add Untitled UI components to your existing project. The CLI will automatically detect your project structure and configure imports accordingly."
    },
    {
      question: "What's the difference between components and examples?",
      answer: "Components are individual UI elements (like `button`, `avatars`, `tables`), while examples are complete, functional pages that showcase how multiple components work together in real-world scenarios."
    },
    {
      question: "How does the search command work?",
      answer: "The search command uses semantic search powered by multimodal AI embeddings. It understands both text descriptions and the visual appearance of components, so you can search naturally — for example, 'login page with customer reviews' will find split-layout login pages that include testimonial quotes, even though the component name doesn't mention 'reviews'."
    },
    {
      question: "Can I customize examples after adding them?",
      answer: "Absolutely! Once an example is added to your project, you own the code completely. You can modify, extend, or customize it however you need for your specific use case."
    },
    {
      question: "Do examples include their dependencies?",
      answer: "Yes, when you add an example, the CLI automatically installs all required dependencies and components. The example will be fully functional immediately after installation."
    },
    {
      question: "What frameworks are supported?",
      answer: "Currently, the CLI supports Next.js and Vite projects. You can specify the framework during initialization or the CLI will auto-detect your project type."
    },
    {
      question: "Does the CLI modify my existing code?",
      answer: "The `add` command writes new component files and, if your `tsconfig.json` has no path alias yet, adds a `paths` entry for the alias you choose (`@/*` by default). It does not touch other existing files. If a component file already exists you are asked whether to overwrite it (the prompt defaults to Yes); `--overwrite` skips the prompt, and `--yes` implies `--overwrite`. The `init` command additionally adds the `globals.css` import to your root layout or entry file."
    },
    {
      question: "Can I customize the installation directory?",
      answer: "Yes, you can use the `--path` flag to specify where components should be installed. For example: `npx untitledui@latest add button --path src/components/ui`."
    },
    {
      question: "What if the browser doesn't open during login?",
      answer: "If the browser doesn't open automatically during the login process, the CLI will display a URL that you can manually copy and paste into your browser."
    },
    {
      question: "How do I update components to the latest version?",
      answer: "You can re-run the `add` command with the `--overwrite` flag to update components to their latest versions: `npx untitledui@latest add button --overwrite`."
    }
  ]}
/>