Prototyper UI

CLI Reference

Complete reference for the Prototyper UI CLI — init, add, search, update, browse, diff, inspect, props, suggest, audit, scaffold, migrate, registry, theme, mcp, doctor, and machine-mode commands.

The Prototyper UI CLI (@prototyperco/cli) is your gateway into the ecosystem — components, registries, AI skills, themes, and more.

bunx @prototyperco/cli <command> [options]

The CLI is built on Bun for the best experience. Running without a subcommand opens the full-screen terminal app with mouse support, component browser, and health dashboard.

Note: The CLI also works via npx under Node.js, but the interactive terminal app requires Bun.

create

Scaffold a brand new project with Prototyper UI pre-configured.

npx @prototyperco/cli create my-app

What it does

  1. Runs create-next-app with TypeScript, Tailwind, ESLint, App Router, and src directory
  2. Runs init inside the new project (tokens, utils, config)
  3. Installs starter components: button, input, card, dialog, field
  4. Runs a single install at the end

Options

FlagDescription
--template <name>Project template (nextjs, vite, remix, astro — default: nextjs)
--demoInclude a demo page showcasing the starter components

Example

# Default Next.js project
npx @prototyperco/cli create my-app --demo
cd my-app
pnpm dev

# Vite project
npx @prototyperco/cli create my-app --template vite

# Remix project
npx @prototyperco/cli create my-app --template remix

# Astro project
npx @prototyperco/cli create my-app --template astro

init

Add design tokens, utilities, and base styles to your project.

npx @prototyperco/cli init

What it does

  1. Finds your globals.css (checks app/globals.css, src/app/globals.css, styles/globals.css, src/styles/globals.css)
  2. Merges OKLCH design tokens into it (or replaces existing tokens)
  3. Creates lib/utils.ts with the cn() utility (clsx + tailwind-merge)
  4. Writes a .prototyper-ui.json manifest with your project config
  5. Optionally installs AI skills for Claude Code or Cursor

Options

FlagDescription
--css <path>Path to your globals.css file (skips auto-detection)
--forceSkip confirmation prompts
--dry-runPreview changes without writing files
--skillsInstall Claude Code / Cursor skills
--no-skillsSkip skills installation
--composeScaffold Compose integration files
--jsonOutput JSON (for LLM-driven setup)

Examples

# Standard setup
npx @prototyperco/cli init

# Custom CSS path
npx @prototyperco/cli init --css src/styles/globals.css

# Non-interactive with Compose
npx @prototyperco/cli init --force --compose

# Preview what would change
npx @prototyperco/cli init --dry-run

add

Add components or integrations to your project.

npx @prototyperco/cli add [components...]

Behavior

  • With arguments: installs the named components and their dependencies
  • Without arguments: opens an interactive picker (grouped by category)
  • With --all: installs every available component

Components are written to components/ui/ (or src/components/ui/ if a src/ directory exists). Use --dir to override.

Options

FlagDescription
--dir <path>Components directory (default: components/ or src/components/)
--allInstall all available components
--forceOverwrite existing files without asking
--dry-runPreview changes without writing files
--no-installSkip automatic dependency installation
--provider <provider>AI provider for compose scaffold (anthropic or openai)
--jsonOutput JSON (for LLM-driven setup)

Examples

# Add a single component
npx @prototyperco/cli add button

# Add multiple components
npx @prototyperco/cli add button card dialog select text-field

# Add a component from another registry
npx @prototyperco/cli add @acme/fancy-card

# Interactive picker
npx @prototyperco/cli add

# Install everything
npx @prototyperco/cli add --all

# Preview without writing
npx @prototyperco/cli add button --dry-run

# Scaffold Compose endpoint
npx @prototyperco/cli add compose --provider anthropic

Dependency resolution

When you install a component, the CLI automatically resolves and installs any registry dependencies. For example, text-field depends on field — both will be installed.

After writing files, the CLI prompts to install npm dependencies (like @base-ui/react) unless --no-install is passed.

update

Check installed components for updates and apply them.

npx @prototyperco/cli update

Behavior

  1. Scans your components/ui/ directory for installed .tsx files
  2. Fetches the latest version of each from the registry
  3. Compares local content against the registry version
  4. Prompts to update each changed component (or updates all with --force)

Options

FlagDescription
--dir <path>Components directory
--forceUpdate all without prompting
--dry-runPreview changes without writing
--jsonOutput JSON

Examples

# Interactive update
npx @prototyperco/cli update

# Update all without prompting
npx @prototyperco/cli update --force

# Check what would change
npx @prototyperco/cli update --dry-run

Note: If you've customized a component, updating will overwrite your changes. Use --dry-run first to see what would change.

Search for components across registries by name or description.

npx @prototyperco/cli search [query...]

Behavior

  • Fuzzy matches against component name and description
  • Shows name, description, category, registry, and an installed marker for components already in your project
  • By default, searches your configured registries. Use --all to search all known registries.

Options

FlagDescription
--allSearch all known registries, not just configured ones
--jsonOutput JSON

Examples

# Search for button components
npx @prototyperco/cli search button

# Search a specific registry
npx @prototyperco/cli search @acme button

# Search all registries
npx @prototyperco/cli search --all button

doctor

Check your project health and configuration.

npx @prototyperco/cli doctor

Checks

The doctor command verifies:

CheckWhat it verifies
globals.cssCSS file exists and is found
Tailwind v4@import "tailwindcss" is present
TokensPrototyper UI token block is installed
lib/utils.tsUtility file exists
Dependencies@base-ui/react, clsx, tailwind-merge, class-variance-authority are in package.json
ComponentsCount of installed components (info only)

Options

FlagDescription
--jsonOutput JSON

Example

npx @prototyperco/cli doctor
 ✓ Found globals.css at app/globals.css
 ✓ Tailwind v4 detected
 ✓ Tokens installed
 ✓ lib/utils.ts exists
 ✓ All peer dependencies installed
 ℹ 12 components installed

 4 of 5 checks passed

browse

Interactive component catalog browser. Opens a full-screen TUI with a component list and detail panel.

npx @prototyperco/cli browse

Example

npx @prototyperco/cli browse

diff

Show differences between your local components and the latest registry versions.

npx @prototyperco/cli diff [components...]

Behavior

  • With arguments: diffs only the named components
  • Without arguments: diffs all installed components

Options

FlagDescription
--dir <path>Components directory
--jsonOutput JSON

Example

# Diff all installed components
npx @prototyperco/cli diff

# Diff specific components
npx @prototyperco/cli diff button dialog

inspect

Deep analysis of a single component — variants, props, tokens, Base UI primitive, exports, and reverse dependencies.

npx @prototyperco/cli inspect <component>

Options

FlagDescription
--jsonOutput JSON

Example

npx @prototyperco/cli inspect button
Button
  Category: actions
  Base UI: @base-ui/react — Button
  Variants: variant (solid, outline, ghost, link), size (sm, md, lg)
  Exports: Button
  Used by: alert-dialog, dialog, form

props

Quick reference for a component's props, variants, events, and import path.

npx @prototyperco/cli props <components...>

Options

FlagDescription
--jsonOutput structured JSON

Example

# Single component
npx @prototyperco/cli props button

# Multiple components
npx @prototyperco/cli props button select dialog

suggest

Scan your source code for raw HTML patterns that could be replaced with Prototyper UI components.

npx @prototyperco/cli suggest

Behavior

Scans files in src/ for common patterns (e.g. <button>, <input>, <dialog>) and suggests matching Prototyper UI components.

Options

FlagDescription
--jsonOutput JSON

Example

npx @prototyperco/cli suggest

audit

Scan page or component files and check which Prototyper UI imports are installed. Optionally auto-install missing components.

npx @prototyperco/cli audit <files...>

Options

FlagDescription
--fixAuto-install missing components
--jsonOutput structured JSON results

Example

# Audit a page file
npx @prototyperco/cli audit app/settings/page.tsx

# Audit and auto-fix
npx @prototyperco/cli audit app/settings/page.tsx --fix

scaffold

Scaffold a full page from a template with pre-selected Prototyper UI components.

npx @prototyperco/cli scaffold [template]

Templates

TemplateDescription
form-pageForm page with validation and field components
dashboardDashboard layout with cards and data display
settingsSettings page with grouped form sections

Options

FlagDescription
--output <path>Custom output path for the page file
--jsonOutput JSON

Example

# Interactive template picker
npx @prototyperco/cli scaffold

# Scaffold a specific template
npx @prototyperco/cli scaffold form-page

# Custom output path
npx @prototyperco/cli scaffold dashboard --output app/dashboard/page.tsx

migrate

Run automated transforms on installed components.

npx @prototyperco/cli migrate <transform>

Transforms

TransformDescription
iconsSwitch icon library on installed components
rtlMap physical CSS properties to logical (ml- to ms-, text-left to text-start)
prefixAdd Tailwind prefix to all utility classes
css-varsMap hardcoded Tailwind colors to token classes

Options

FlagDescription
--forceApply transform without prompting
--dry-runPreview changes without writing files
--jsonOutput JSON

Examples

# Switch to a different icon library
npx @prototyperco/cli migrate icons

# Preview RTL migration
npx @prototyperco/cli migrate rtl --dry-run

# Add Tailwind prefix to all components
npx @prototyperco/cli migrate prefix --force

# Convert hardcoded colors to CSS tokens
npx @prototyperco/cli migrate css-vars

registry

Manage component registries and create your own.

registry add / remove / list

Configure which registries you install components from.

npx @prototyperco/cli registry add <alias>=<url>
npx @prototyperco/cli registry remove <alias>
npx @prototyperco/cli registry list

Options for registry add

FlagDescription
--header <key>=<value>Add an authorization header for private registries

Examples

# Add a third-party registry
npx @prototyperco/cli registry add @acme=https://registry.acme.com/r/{name}.json

# Add a private registry with auth
npx @prototyperco/cli registry add @acme=https://registry.acme.com/r/{name}.json --header "Authorization=Bearer ${TOKEN}"

# Remove a registry
npx @prototyperco/cli registry remove @acme

# List configured registries
npx @prototyperco/cli registry list

registry init / validate / build

Create and publish your own component registry.

npx @prototyperco/cli registry init
npx @prototyperco/cli registry validate [registry.json]
npx @prototyperco/cli registry build [registry.json] --output public/r

Examples

# Initialize a new registry manifest
npx @prototyperco/cli registry init

# Validate a registry manifest
npx @prototyperco/cli registry validate

# Validate a specific file
npx @prototyperco/cli registry validate custom-registry.json

# Build registry JSON files for distribution
npx @prototyperco/cli registry build --output public/r

export:context

Generate a single AI context file containing your project's installed components, theme, and structure.

npx @prototyperco/cli export:context

Options

FlagDescription
--output <path>Write to a file instead of stdout
--jsonOutput structured JSON
--clipboardCopy to clipboard (macOS)

Example

# Print to stdout
npx @prototyperco/cli export:context

# Write to file
npx @prototyperco/cli export:context --output context.md

# Copy to clipboard
npx @prototyperco/cli export:context --clipboard

theme export

Generate OKLCH CSS tokens from theme parameters.

npx @prototyperco/cli theme export

Options

FlagDescription
--output <path>Write tokens to a CSS file (e.g. app/globals.css)
--jsonOutput JSON with params and CSS

Example

# Print tokens to stdout
npx @prototyperco/cli theme export

# Write to globals.css
npx @prototyperco/cli theme export --output app/globals.css

mcp init

Auto-configure the Prototyper UI MCP server in Claude Code, Cursor, and VS Code.

npx @prototyperco/cli mcp init

Options

FlagDescription
--jsonOutput JSON

Example

npx @prototyperco/cli mcp init

machine-mode init

Scaffold machine mode for a Next.js App Router project. Machine mode provides URL-driven endpoints for programmatic component rendering.

npx @prototyperco/cli machine-mode init

Options

FlagDescription
--dir <path>Project directory (default: current directory)
--machine-base-path <path>Base route path for machine endpoints (default: machine)
--forceSkip confirmation prompts
--dry-runPreview changes without writing files
--jsonOutput JSON (for LLM-driven setup)

See the Machine Mode guide for full documentation.

JSON mode

Every command supports a --json flag that outputs structured JSON instead of interactive prompts. This is designed for LLM-driven workflows where an AI agent runs CLI commands programmatically.

# List available components as JSON
npx @prototyperco/cli add --json

# Install and get structured result
npx @prototyperco/cli add button --json

# Check project health as JSON
npx @prototyperco/cli doctor --json

Configuration

.prototyper-ui.json

The init command creates a .prototyper-ui.json manifest in your project root:

{
  "version": "0.1.2",
  "css": "app/globals.css",
  "componentsDir": "components",
  "iconLibrary": "lucide",
  "preset": "default",
  "tailwind": {
    "prefix": ""
  },
  "registries": {
    "@prototyper": "https://prototyper-ui.com/r/{name}.json"
  },
  "endpoints": {
    "docs": "https://prototyper-ui.com/docs",
    "llms": "https://prototyper-ui.com/llms.txt",
    "components": "https://prototyper-ui.com/llms-components.txt"
  }
}
FieldDescription
versionCLI version that created the manifest
cssRelative path to your globals.css file
componentsDirBase directory for component installation
iconLibraryIcon library used in components (lucide, tabler, phosphor, heroicons, remix)
presetDesign preset name
tailwind.prefixCustom Tailwind prefix applied to all utility classes
registriesMap of registry aliases to URL templates for multi-registry support
endpointsRegistry and documentation URLs

Package manager detection

The CLI auto-detects your package manager by checking for lock files in the current directory:

Lock filePackage manager
pnpm-lock.yamlpnpm
yarn.lockyarn
bun.lockbbun
package-lock.jsonnpm

The detected package manager is used for dependency installation commands.

Using with shadcn CLI

Prototyper UI components are compatible with the shadcn CLI. You can install any component directly:

npx shadcn@latest add https://prototyper-ui.com/r/button.json

This works because Prototyper UI publishes registry JSON at prototyper-ui.com/r/{component}.json in the shadcn registry format.

Installation

How to set up Prototyper UI in your Next.js project with Tailwind CSS v4 and Base UI.

Machine Mode Package

Add an LLM-friendly plain text view to any Next.js App Router site.

On this page

createWhat it doesOptionsExampleinitWhat it doesOptionsExamplesaddBehaviorOptionsExamplesDependency resolutionupdateBehaviorOptionsExamplessearchBehaviorOptionsExamplesdoctorChecksOptionsExamplebrowseExamplediffBehaviorOptionsExampleinspectOptionsExamplepropsOptionsExamplesuggestBehaviorOptionsExampleauditOptionsExamplescaffoldTemplatesOptionsExamplemigrateTransformsOptionsExamplesregistryregistry add / remove / listOptions for registry addExamplesregistry init / validate / buildExamplesexport:contextOptionsExampletheme exportOptionsExamplemcp initOptionsExamplemachine-mode initOptionsJSON modeConfiguration.prototyper-ui.jsonPackage manager detectionUsing with shadcn CLI