CLI Reference

The localhost.io CLI is built on the shadcn registry system and gives you complete control over your components.

Unlike traditional UI libraries that hide code in node_modules, our CLI copies source code directly into your project — fully editable, debuggable, and yours to own.

Quick Start

Get up and running in 2 steps:

1. Initialize your project (one-time setup)
2. Add components as you need them

# Step 1: Initialize
npx shadcn@latest init

# Step 2: Add a component
npx shadcn@latest add https://localhost.io/r/button.json

That's it. The component is now in your codebase, ready to customize.

init

The init command prepares your project to work with localhost.io components.

Run this once per project before adding any components.

What init does

Running init will:

• ✅ Create a components.json configuration file
• ✅ Install required base dependencies (clsx, tailwind-merge, etc.)
• ✅ Add the cn() utility function for className merging
• ✅ Configure tailwind.config.js for component usage
• ✅ Set up CSS variables for theming (if selected)
• ✅ Prepare registry support for localhost.io components

This ensures all components work consistently across your application.

Run the init command

Choose your package manager:

npx shadcn@latest init

pnpm dlx shadcn@latest init

npx shadcn@latest init

bunx --bun shadcn@latest init

Configuration prompts

During initialization, you'll be asked a few questions:

Which style would you like to use? › New York
Which color would you like to use as base color? › Zinc
Do you want to use CSS variables for colors? › Yes
Where is your global CSS file? › app/globals.css
Would you like to use TypeScript? › Yes

Init options

Example:

# Initialize with defaults, skip prompts
npx shadcn@latest init -d -y

add

The add command installs localhost.io components directly into your project.

Each component is:

• 📦 Copied into your source code (not hidden in node_modules)
• ✏️ Fully editable — modify styles, behavior, anything
• 🔗 Automatically wired with required dependencies
• 🎨 Pre-styled with Tailwind CSS

Add a component

Components are added via their registry URL:

npx shadcn@latest add https://localhost.io/r/button.json

pnpm dlx shadcn@latest add https://localhost.io/r/button.json

npx shadcn@latest add https://localhost.io/r/button.json

bunx --bun shadcn@latest add https://localhost.io/r/button.json

What happens when you add a component

1. Component files are copied into your components/ directory
2. Dependencies are installed automatically (e.g., framer-motion, date-fns)
3. Tailwind styles are applied — no additional CSS imports needed
4. The component is ready to use immediately

No extra configuration required.

Add multiple components at once

You can add multiple components in a single command:

npx shadcn@latest add \
  https://localhost.io/r/button.json \
  https://localhost.io/r/input.json \
  https://localhost.io/r/card.json

Add all components

To add every available component from the localhost.io registry:

npx shadcn@latest add -a https://localhost.io/r

Add options

Examples:

# Add a component, overwrite if it exists
npx shadcn@latest add https://localhost.io/r/button.json -o

# Add a component to a custom path
npx shadcn@latest add https://localhost.io/r/button.json -p ./src/ui

# Add component, skip confirmation
npx shadcn@latest add https://localhost.io/r/button.json -y

How the CLI works

The localhost.io CLI follows a copy-paste-own model, not a traditional package install model.

Traditional UI libraries

npm install some-ui-library
└── node_modules/
    └── some-ui-library/  ← Hidden, not editable

localhost.io approach

npx shadcn@latest add https://localhost.io/r/button.json
└── components/
    └── ui/
        └── button.tsx  ← In your codebase, fully editable

Benefits:

• ✅ Full ownership — modify styles, behavior, anything
• ✅ No runtime lock-in — not tied to package versions
• ✅ Easy debugging — all code is visible in your project
• ✅ Tree-shakeable — only use what you need
• ✅ No breaking updates — components don't change unless you update them

Finding component registry URLs

Every component on localhost.io has a registry URL that you use with the add command.

You can find the URL in two ways:

1. Browse components on the website

Visit localhost.io/components and click any component. The registry URL will be shown in the installation instructions.

2. Check the component page

Each component page has a "Copy CLI command" button that copies the full add command to your clipboard.

Common workflows

Starting a new project

# 1. Create a Next.js project
npx create-next-app@latest my-app

# 2. Navigate into the project
cd my-app

# 3. Initialize localhost.io
npx shadcn@latest init

# 4. Add components as needed
npx shadcn@latest add https://localhost.io/r/button.json
npx shadcn@latest add https://localhost.io/r/input.json

Adding to an existing project

# 1. Initialize (if you haven't already)
npx shadcn@latest init

# 2. Add components
npx shadcn@latest add https://localhost.io/r/card.json

Updating a component

If you've modified a component and want to reset it to the original version:

# Use the --overwrite flag
npx shadcn@latest add https://localhost.io/r/button.json -o

Troubleshooting

components.json not found

Error:

Error: components.json not found. Please run init to create one.

Solution:

npx shadcn@latest init

Run npx shadcn@latest init first. The CLI requires a components.json file to know where to put components.

Component already exists

Error:

Component "button" already exists. Use --overwrite to replace it.

Solution:

Use the -o or --overwrite flag:

npx shadcn@latest add https://localhost.io/r/button.json -o

Tailwind CSS not configured

Error:

Tailwind CSS is not configured in your project.

Solution:

Make sure you have tailwind.config.js and Tailwind CSS installed. The init command should handle this, but if you're adding to an existing project, you may need to configure Tailwind manually.

See the Tailwind CSS installation guide for details.

Wrong working directory

If the CLI isn't detecting your project correctly, use the -c flag to specify the directory:

npx shadcn@latest init -c ./my-project
npx shadcn@latest add https://localhost.io/r/button.json -c ./my-project

Next steps

Now that you've set up the CLI, you're ready to start building:

• Browse all components
• Read the component documentation
• Explore templates
• Join the community

Questions?

If you run into issues or have questions about the CLI, feel free to:

• Open an issue on GitHub
• Ask in our Discord community
• Check the FAQ