ui8kit CLI

Official CLI for bootstrapping and managing UI8Kit component workflows in Vite React projects.

Requirements

• Node.js >=18
• A Vite React project (for init and add)

Quick Start

bunx ui8kit@latest init

Initialize with defaults (non-interactive):

bunx ui8kit@latest init --yes

Commands

init

Initialize UI8Kit structure and config in the current project.

bunx ui8kit@latest init
bunx ui8kit@latest init --yes
bunx ui8kit@latest init --registry ui

Options:

• -y, --yes Skip prompts and use defaults
• -r, --registry <type> Registry type (default: ui)
• --registry-url <url> Override registry CDN base URL
• --registry-version <version> Replace @latest in default URLs with a pinned version
• --strict-cdn Disable fallback CDN providers when an explicit URL is set
• --import-style <alias|package> Choose installed component import style (alias or package barrel @ui8kit/core; default: alias)

When running without --yes, init now asks for:

• Global CSS file path (default: src/index.css)
• Import alias for components (default: @/components)
• Import style for installed components (alias or package)

typescript is always set to true and framework is fixed to vite-react. init now writes configuration and core utilities/variants. Empty category folders are created during bulk install (add --all).

add

Install one or more components from the registry.

bunx ui8kit@latest add button
bunx ui8kit@latest add button card
bunx ui8kit@latest add --all
bunx ui8kit@latest add badge --force
bunx ui8kit@latest add button --dry-run
bunx ui8kit@latest add --all --retry
bunx ui8kit@latest --no-cache add button --dry-run

Calling add without component arguments opens an interactive multiselect list grouped by component type. Resolved registry dependencies are installed in dependency order automatically. add now prints progress counters for multi-component installs in the format [n/total]. --dry-run now also shows:

• full target file paths
• overwrite/create status for each file
• registry dependency tree
• compact diff preview for files that already exist locally

Options:

• -a, --all Install all available components
• -f, --force Overwrite existing files
• -r, --registry <type> Registry type (default: ui)
• --dry-run Show planned actions without writing files
• --all also creates base install directories before fetching and writing components:
  • src/lib
  • src/components
  • src/components/ui
  • src/blocks
  • src/layouts
  • src/variants
• --retry Enable retry logic for unstable connections
• --no-cache (root option) bypasses cache for this run.
• --registry-url <url> Override registry CDN base URL
• --registry-version <version> Replace @latest in default URLs with a pinned version
• --strict-cdn Disable fallback CDN providers when an explicit URL is set

list

List available components from the registry. Grouped by component type and sorted alphabetically.

bunx ui8kit@latest list
bunx ui8kit@latest list --registry ui
bunx ui8kit@latest list --json

Options:

• -r, --registry <type> Registry type (default: ui)
• --json Print JSON output instead of table
• --registry-url <url> Override registry CDN base URL
• --registry-version <version> Replace @latest in default URLs with a pinned version
• --strict-cdn Disable fallback CDN providers when an explicit URL is set

diff

Show differences between local components and registry versions using unified diff output. Useful to check which installed components are outdated.

bunx ui8kit@latest diff
bunx ui8kit@latest diff button
bunx ui8kit@latest diff --json

Options:

• [component] Optional component name
• -r, --registry <type> Registry type (default: ui)
• --json Print diff summary as JSON
• --registry-url <url> Override registry CDN base URL
• --registry-version <version> Replace @latest in default URLs with a pinned version
• --strict-cdn Disable fallback CDN providers when an explicit URL is set

Examples:

bunx ui8kit@latest diff button

cache

Manage local registry cache.

bunx ui8kit@latest cache clear

info

Show local environment and configuration diagnostics.

bunx ui8kit@latest info
bunx ui8kit@latest --no-cache info

Use --no-cache in any command to skip reading cached registry data.

bunx ui8kit@latest info --cdn

Use --cdn to print resolved CDN URL order, active cache override, and registry override settings.

bunx ui8kit@latest --no-cache diff
bunx ui8kit@latest --no-cache list --json

registry (utility)

Commands to maintain local CLI artifacts.

bunx ui8kit@latest registry clean
bunx ui8kit@latest registry clean --all --dry-run

reset

Remove local UI8Kit-generated project state for a full clean re-install.

bunx ui8kit@latest reset
bunx ui8kit@latest reset --yes
bunx ui8kit@latest reset --dry-run

Options:

• --dry-run Show what will be removed
• -y, --yes Skip prompts
• -f, --force Skip confirmation prompt
• --with-cache Also clear local cache

Reset removes:

• ui8kit.config.json (project config)
• src/registry.json manifest if present
• Component install directories (src/components, src/lib, src/variants, src/layouts, src/blocks)
• Generated registry artifacts (packages/registry/..., ui8kit.map.json)

get-cdn (diagnostics utility)

Check registry availability for each CDN source and compare payload metadata without touching installed project files.

npm run get-cdn
npm run get-cdn -- --url https://raw.githubusercontent.com/ui8kit/core/refs/heads/main/packages/registry/r
npm run get-cdn -- --path components/variants/index.json --url https://cdn.jsdelivr.net/npm/@ui8kit/registry@latest/r

Use this before init/add when you suspect CDN propagation lag, stale @latest caches, or provider-specific outages.

scan

Scan source files and generate a registry manifest.

bunx ui8kit@latest scan
bunx ui8kit@latest scan --source ./src --output ./src/registry.json

Options:

• -r, --registry <type|path> Registry type/path (default: ui)
• -o, --output <file> Output registry file
• -s, --source <dir> Source directory to scan

build

Build a publishable registry from a registry JSON file.

bunx ui8kit@latest build
bunx ui8kit@latest build ./src/registry.json
bunx ui8kit@latest build ./src/registry.json --output ./packages/registry/r

Options:

• [registry] Path to registry JSON (default: ./src/registry.json)
• -o, --output <path> Output directory (default: ./packages/registry/r)

The build command also generates packages/registry/ui8kit.map.json when src/lib/utility-props.map.ts is available.

Generated map shape:

{
  "version": "1.0.0",
  "generatedAt": "2026-03-06T12:00:00.000Z",
  "map": [
    "block",
    "display-block",
    "display-flex",
    "m-2",
    "m-4"
  ]
}

map keeps the existing top-level envelope, but the value is now a flat string array of Tailwind classes. The generation reads both:

• src/lib/utility-props.map.ts — grouped whitelist map by utility prefix.
• src/lib/utility-props.ts — runtime rule source used for special expansions (for example flex direction handling and semantic gap aliases).

Global options

These options work for all commands and are defined at the CLI root:

• -c, --cwd <dir> Working directory for command execution (default: current directory)
• -v, --verbose Enable verbose output including debug logs from registry/CDN operations
• --no-cache Bypass local filesystem cache for registry lookups

Typical Flow

# 1) Initialize project
bunx ui8kit@latest init --yes

# 2) Add a component
bunx ui8kit@latest add button

# 3) Add everything from registry (optional)
bunx ui8kit@latest add --all

Local Development (this package)

From packages/cli:

npm install
npm run dev

Build once:

npm run build

Run compiled CLI locally:

node dist/index.js --help