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]
Init command
The init command helps you scaffold a new project with Untitled UI components and configurations pre-installed.
Create a new project
Run this command in your root folder to create a new Next.js project:
npx untitledui@latest init --nextjs
While running the command, you'll be asked a few questions to set up your project:
? What is your project named? › untitled-ui ? Which color would you like to use as the brand color? › ❯ brand error warning success ↓ gray-neutral
This will create a new Next.js project in the untitled-ui directory with all the necessary configurations and components pre-installed.
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 pages.
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> | Specify a brand color for the project |
-o, --overwrite | Overwrite existing files |
--colors-list | Show the available colors list |
Add command
The add command allows you to add specific Untitled UI components to your existing project.
Add components
To add a specific component:
npx untitledui@latest add button
You can add multiple components at once:
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:
npx untitledui@latest add
This will display a type selection interface:
? 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:
? 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.
PRO components
For PRO components, you need to be authenticated:
npx untitledui@latest login npx untitledui@latest add pro-component
Customization options
The add command offers several options:
# 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
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) |
--lib-version <version> | Component library version to pull (7 or 8). Auto-detected from components.json if not specified. |
Login command
The login command allows you to authenticate with Untitled UI to access PRO components through the CLI.
Interactive authentication
To authenticate with your Untitled UI account:
npx untitledui@latest login
This will:
- Open your browser automatically
- Check if you're already signed in to Untitled UI
- If already signed in: Authenticate immediately and return to CLI
- If not signed in: Redirect to the sign-in page, send a magic link to your email, and authenticate after you click the link
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.
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 — 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.
Search for anything
Describe what you need in plain language. The search runs across components, templates, and icons simultaneously:
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"
Filter by type
You can narrow your search to a specific type:
# 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
More options
# 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
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. |
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.
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
Add specific examples
You can directly specify an example to add:
# 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
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
Customization options
The example command offers several options for customization:
# Specify where to add the example page npx untitledui@latest example dashboard-01/05 --example-path src/app/dashboard # Specify where to add the components npx untitledui@latest example dashboard-01/05 --path components/ui # Overwrite existing files npx untitledui@latest example dashboard-01/05 --overwrite # Non-interactive mode (for AI agents/CI) npx untitledui@latest example dashboard-01/05 --yes
What gets added
When you add an example, the CLI will:
- Add the main example page to your specified directory (default:
app/orpages/) - Install required components that the example uses
- Install dependencies needed for the example
- Configure imports to match your project structure
- Prompt for component selection if multiple components are needed
The example will be fully functional and ready to use in your project.
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. |
--include-all-components | Automatically include all components from the example without prompting. |
-y, --yes | Non-interactive mode - use defaults for all prompts (for AI agents/CI). |
--lib-version <version> | Component library version to pull (7 or 8). Auto-detected from components.json if not specified. |
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 CLI reads the version field in your project's components.json to determine which version to pull:
"version": "7"incomponents.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 on any command:
npx untitledui@latest add button --lib-version 7 npx untitledui@latest example dashboards-01/05 --lib-version 7
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 --nextjs # Navigate to your new project cd untitledui-app # Start the development server npm run dev
FAQs
Please refer to our frequently asked questions page for more.
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.
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'.
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.