gui/apps/gui.hanzo.ai/data/docs/guides/cli.mdx

---
title: Gui CLI
description: Command-line tools for building, checking, and managing Gui projects
---

<IntroParagraph>
  The Gui CLI provides a suite of command-line tools for optimizing components, managing
  dependencies, adding fonts and icons, and more.
</IntroParagraph>

<Notice theme="gray">
  **Just starting out?** Skim this section, the CLI is not necessary to get going.
</Notice>

## Installation

Install the CLI as a development dependency:

```bash
yarn add -D @hanzogui/cli
```

## Commands

### build

Pre-compile Gui components in-place for production builds. This is useful
for bundlers that don't have a Gui plugin yet (like Turbopack) or when you
want a simple setup that works with any bundler.

```bash
# Build all components in a directory (web + native by default)
npx hanzogui build ./src

# Build for web only
npx hanzogui build --target web ./src

# Build for native only
npx hanzogui build --target native ./src

# Build a specific file
npx hanzogui build ./src/components/MyComponent.tsx

# Include/exclude patterns
npx hanzogui build --include "components/**" --exclude "**/*.test.tsx" ./src

# Output to a separate directory (source files unchanged)
npx hanzogui build --output ./dist ./src

# Create platform-specific files next to source files (.web.tsx or .native.tsx)
npx hanzogui build --target native --output-around ./src

# Preview changes without writing files
npx hanzogui build --dry-run ./src
```

**Flags:**

- `--target <platform>` - Target platform: `web`, `native`, or `both` (default:
  `both`)
- `--include <pattern>` - Glob pattern to include files
- `--exclude <pattern>` - Glob pattern to exclude files
- `--output <path>` - Output directory for optimized files (preserves directory
  structure). When specified, source files are not modified
- `--output-around` - Create platform-specific files (`.web.tsx` or `.native.tsx`)
  next to source files instead of modifying them. Errors if the file already exists
- `--expect-optimizations <number>` - Fail if fewer than this many components
  are optimized (useful for CI)
- `--dry-run` - Preview what would be optimized without writing any files
- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**Platform-Specific File Handling:**

The CLI automatically handles platform-specific files:

- Files with `.web.tsx` or `.ios.tsx` extensions are optimized for web only
- Files with `.native.tsx` or `.android.tsx` extensions are optimized for native
  only
- Base files (`.tsx`) without platform-specific versions are optimized for all
  platforms
- If both `.web.tsx` and `.native.tsx` exist, the base `.tsx` file is skipped

**Configuration:**

Create a `hanzogui.build.ts` config file in your project root:

```ts
import type { GuiBuildOptions } from '@hanzo/gui'

export default {
  config: './hanzogui.config.ts',
  components: ['@hanzo/gui'],
  importsWhitelist: ['constants.js', 'colors.js'],
  outputCSS: './public/hanzogui.generated.css',
} satisfies GuiBuildOptions
```

**Integration Examples:**

The CLI can wrap your build command using `--`, which optimizes files beforehand
and automatically restores them after:

```json
{
  "scripts": {
    "build": "hanzogui build --target web ./src -- next build"
  }
}
```

The `--` separator tells the CLI to run `next build` after optimization, then
restore your source files automatically. This is the recommended approach as it
keeps your source files unchanged.

Alternatively, run `hanzogui build` separately (files will remain modified):

```json
{
  "scripts": {
    "build": "hanzogui build --target web ./src && next build"
  }
}
```

**Important:** Without the `--` wrapper, files are modified in-place and not
restored. Only use this approach if you're building in a CI environment where
the files are discarded anyway.

Alternatively, use `--output` to write optimized files to a separate directory:

```json
{
  "scripts": {
    "build": "hanzogui build --target web --output ./dist ./src && next build"
  }
}
```

With `--output`, source files are never modified and no restoration is needed.

For more details, see the
[Compiler Installation guide](/docs/intro/compiler-install#cli-based-in-place-compilation).

### check

Check your dependencies for inconsistent versions across your project. This
helps identify version mismatches that can cause issues, especially in
monorepos.

```bash
npx hanzogui check
```

**Flags:**

- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**Example output:**

The command will scan your project and report any packages with mismatched
versions, helping you maintain consistency across your dependencies.

### generate

Build your entire Gui configuration and output CSS. This is useful for
pre-generating your design system's CSS and validating your configuration.

```bash
npx hanzogui generate
```

**Flags:**

- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**What it does:**

1. Loads and validates your Gui configuration
2. Generates CSS for all your tokens, themes, and components
3. Outputs to the `.hanzogui` directory
4. Also generates an LLM-friendly prompt file at `.hanzogui/prompt.md`

### generate-css

Generate the `hanzogui.generated.css` file from your configuration. Useful for build
pipelines or when you need to regenerate CSS without running a full build.

```bash
npx hanzogui generate-css
```

**Flags:**

- `--output <path>` - Custom output path (default: `hanzogui.generated.css`)
- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**Example:**

```bash
npx hanzogui generate-css --output ./public/styles/hanzogui.generated.css
```

### generate-themes

Pre-build your theme configuration for faster runtime performance. This
generates optimized theme objects from your theme definitions.

```bash
npx hanzogui generate-themes <input-path> <output-path>
```

**Example:**

```bash
npx hanzogui generate-themes ./themes/input.ts ./themes/generated.ts
```

**Flags:**

- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**Use case:** If you have complex theme generation logic, this command
pre-computes your themes at build time rather than runtime.

### add

<Notice theme="green">
  **Gui Pro** - This command is available exclusively to Gui Pro members.
</Notice>

Add pre-configured fonts and icons from Gui's curated collections. This
includes Google Fonts and Iconify icon packs.

```bash
# Add a font
npx hanzogui add font [packages-path]

# Add an icon pack
npx hanzogui add icon [packages-path]
```

**Flags:**

- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output

**Interactive selection:**

The command will present an interactive menu where you can search and select
from available fonts or icons:

- **Fonts**: Browse Google Fonts with weight, style, and subset information
- **Icons**: Browse Iconify collections with icon counts and license information

**Default path:** If you don't provide a path, packages are installed to
`./packages` in your current directory.

### generate-prompt

Generate an LLM-friendly markdown file from your Gui configuration. This
creates comprehensive documentation of your design system for use with AI
assistants.

```bash
npx hanzogui generate-prompt
```

**Flags:**

- `--output <path>` - Custom output path (default: `.hanzogui/prompt.md`)
- `--debug` - Enable debug output

**What it includes:**

- All your tokens (colors, sizes, space, etc.)
- Theme definitions and variants
- Component configurations
- Font families and configurations
- Media queries and breakpoints

**Use case:** Share this file with AI assistants like Claude or ChatGPT to get
better suggestions that align with your design system.

## Global Flags

All commands support these flags:

- `--help` - Show help for the command
- `--version` - Show CLI version
- `--debug` - Enable debug output
- `--verbose` - Enable verbose debug output (more detailed than `--debug`)

## Examples

### Production Build Pipeline

```json
{
  "scripts": {
    "build": "hanzogui check && hanzogui build --target web ./src -- next build"
  }
}
```

### CI with Optimization Verification

```json
{
  "scripts": {
    "build": "hanzogui build --target web --expect-optimizations 10 ./src -- next build"
  }
}
```

This fails the build if fewer than 10 components are optimized, helping catch
configuration issues in CI.

### Cross-Platform Mobile App

```json
{
  "scripts": {
    "build:ios": "hanzogui build --target native ./src -- eas build --platform ios",
    "build:android": "hanzogui build --target native ./src -- eas build --platform android",
    "build:web": "hanzogui build --target web ./src -- vite build"
  }
}
```

## Troubleshooting

### Build command fails with "cannot find module"

Make sure you have a `hanzogui.build.ts` config file that correctly points to
your configuration:

```ts
export default {
  config: './hanzogui.config.ts', // Verify this path is correct
  components: ['@hanzo/gui'],
}
```

### Check command reports false positives

The check command is strict about version consistency. If you have a specific
reason for version mismatches (like testing), you can document them in your
README.