CLI Reference

Complete reference for the star command-line interface.

The star CLI manages your StarUI components, builds production CSS, and runs the dev server.

star --version

Commands

star init

Initialize a new StarUI project. Creates configuration, component directory, Tailwind input CSS, and a starter app file.

star init

--force

Force initialization even if project already set up

--verbose, -v

Show detailed output

--component-dir DIR

Set the component install directory

--no-interaction

Non-interactive mode for CI environments

In non-interactive mode, all prompts are skipped and sensible defaults are used. Useful for CI pipelines and scripted setups.

star add

Add components and blocks to your project. Dependencies are resolved and installed automatically.

# Add a single component
star add button

# Add multiple components at once
star add button input card tabs

# Add a block
star add user-button-01

# Overwrite existing files
star add button --force

One or more component or block names (required)

--force

Overwrite existing files

--verbose, -v

Show detailed output

--theme THEME

Theme for code highlighting components

--component-dir DIR

Override the component install directory

star dev

Start the development server with dual hot reload: Tailwind CSS rebuilds on class changes, and Python code reloads on file saves.

# Start dev server (default port 5000)
star dev app.py

# Specify a port
star dev app.py --port 8000

# Disable CSS hot reload
star dev app.py --no-css-hot

<app_file>

StarHTML app file to run (required)

--port, -p PORT

Port number (default: 5000)

--css-hot / --no-css-hot

Enable or disable CSS hot reload (default: enabled)

--strict

Fail if the detected port is unavailable instead of auto-finding one

--debug / --no-debug

Enable or disable debug mode (default: enabled)

Port detection reads your app file for patterns like serve(port=...) and uvicorn.run(port=...). If that port is busy and --strict is off, the next available port is used automatically.

star build

Build production CSS. Downloads a standalone Tailwind binary automatically — no Node.js required.

# Build with defaults (minified)
star build

# Custom output path, unminified
star build --output static/css/app.css --no-minify

--output, -o PATH

CSS output path (default: from config or auto-detected)

--minify / --no-minify

Minify the output CSS (default: minified)

--verbose, -v

Show detailed output

The Tailwind binary is downloaded once and cached at ~/.starui/cache/. Subsequent builds reuse the cached binary with zero network overhead.

star list

List all available components and blocks from the registry.

# List everything
star list

# Search by name
star list --search button

# Show only installed components
star list --installed

--search QUERY

Filter components by name

--installed

Show only installed components

--verbose, -v

Show detailed output with descriptions

star status

Show the status of installed components and blocks. Detects local modifications using checksum comparison against the registry version.

star status

Checksums are computed at install time and stored in .starui/manifest.json. Any local edits to component files will be flagged as modified.

star diff

Show a diff between your local component file and the latest registry version. Useful for reviewing what you've changed.

# See what changed in your local button
star diff button

Component or block name to diff (required)

star update

Update installed components and blocks to the latest registry versions. Skips locally modified files unless forced.

# Update all components
star update

# Update specific components
star update button card

# Force-update even if locally modified
star update button --force

Specific components to update (optional — updates all if omitted)

--force

Overwrite locally modified files

--verbose, -v

Show detailed output

star sort

Sort Tailwind classes in Python source files for consistent ordering.

# Sort all Python files in the current directory
star sort

# Sort specific files or directories
star sort components/ app.py

# Check mode for CI (exits code 1 if changes needed)
star sort --check