CLI tool

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.

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:

npx untitledui@latest [command]

Commands

The Untitled UI CLI offers several commands to help you work with the library more efficiently.

Init command

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

1

Create a new project

To create a new project with Next.js (default):

npx untitledui@latest init untitledui-app

For Vite:

npx untitledui@latest init untitledui-app --vite
2

Configuration options

During initialization, you'll be asked a few questions to customize your project:

? What is your project named? › untitledui-app
? Which color would you like to use as the brand color? ›
❯   brand
    error
    warning
    success
  ↓ gray-neutral

This will create all necessary files and configurations in your specified directory.

Add command

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

1

Add components

To add a specific component:

npx untitledui@latest add button

You can add multiple components at once:

npx untitledui@latest add button card dropdown

If you run the command without specifying any components, you'll first be asked to select a component type:

npx untitledui@latest add

This will display a type selection interface:

? What type of component are you adding? ›
❯ shared
  marketing
  shared-assets
  application
  foundations

After selecting a type, you'll see available components in that category:

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

2

PRO components

For PRO components, you need to be authenticated:

npx untitledui@latest login
npx untitledui@latest add pro-component
3

Customization options

The add command offers several options:

# Specify component type directly
npx untitledui@latest add button --type shared
 
# 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

Login command

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

1

Interactive authentication

To authenticate with your Untitled UI account:

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
2

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.

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.

1

Interactive example selection

To browse and add an example interactively:

npx untitledui@latest example

This will prompt you to select from available example categories:

? 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:

? Where would you like to add the dashboard-01 example? › app
? Where would you like to add the components? › components
2

Add specific examples

You can directly specify an example to add:

# Add a specific application example
npx untitledui@latest example application
 
# Add a specific dashboard example
npx untitledui@latest example dashboards-01

For nested examples, you can specify the full path:

npx untitledui@latest example dashboards-01/01
3

PRO examples

Many examples require PRO access. If you try to access a PRO example without authentication, you'll see:

🔒 The dashboard-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:

npx untitledui@latest login
npx untitledui@latest example dashboard-01
4

Customization options

The example command offers several options for customization:

# Specify where to add the example page
npx untitledui@latest example dashboard-01 --example-path src/app/dashboard
 
# Specify where to add the components
npx untitledui@latest example dashboard-01 --path components/ui
 
# Overwrite existing files
npx untitledui@latest example dashboard-01 --overwrite
5

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.

Usage examples

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

# Create a new Next.js project with Untitled UI
npx untitledui@latest init untitledui-app
 
# Navigate to your new project
cd untitledui-app
 
# Start the development server
npm run dev

FAQs

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.

No, you only need to login once per machine. Your authentication credentials are saved locally and will persist across CLI sessions.

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.

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.

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.

Yes, when you add an example, the CLI automatically installs all required dependencies and components. The example will be fully functional immediately after installation.

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.

The add command only adds new files to your project. It won't modify your existing code unless you use the --overwrite flag to replace existing files.

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.

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.

You can re-run the add command with the --overwrite flag to update components to their latest versions: npx untitledui@latest add button --overwrite.

TypographyIcons