Gui CLI

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

Installation

Install the CLI as a development dependency:

yarn
npm
bun
pnpm
yarn add -D @hanzogui/cli
Copy

Commands

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.

Terminal
# 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
Copy

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:

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
Copy

Integration Examples:

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

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

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):

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

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:

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

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

For more details, see the Compiler Installation guide.

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

yarn
npm
bun
pnpm
yarn dlx hanzogui check
Copy

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.

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

yarn
npm
bun
pnpm
yarn dlx hanzogui generate
Copy

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 the hanzogui.generated.css file from your configuration. Useful for build pipelines or when you need to regenerate CSS without running a full build.

yarn
npm
bun
pnpm
yarn dlx hanzogui generate-css
Copy

Flags:

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

Example:

yarn
npm
bun
pnpm
yarn dlx hanzogui generate-css --output ./public/styles/hanzogui.generated.css
Copy

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

yarn
npm
bun
pnpm
yarn dlx hanzogui generate-themes <input-path> <output-path>
Copy

Example:

yarn
npm
bun
pnpm
yarn dlx hanzogui generate-themes ./themes/input.ts ./themes/generated.ts
Copy

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 pre-configured fonts and icons from Gui’s curated collections. This includes Google Fonts and Iconify icon packs.

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

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

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 an LLM-friendly markdown file from your Gui configuration. This creates comprehensive documentation of your design system for use with AI assistants.

yarn
npm
bun
pnpm
yarn dlx hanzogui generate-prompt
Copy

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

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

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

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

{
  "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"
  }
}
Copy

Troubleshooting

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

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

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.