CLI

The command line interface for UnoCSS: @unocss/cli.

• 🍱 Extract utilities from scoped files
• 👀 Watch mode included
• 🔌 Supports custom configurations via uno.config.ts
• ⚙️ Various options to customize the output
• 🚀 Supports multiple entry patterns

Installation

This package is shipped with the unocss package:

::: code-group

pnpm add -D unocss

yarn add -D unocss

npm install -D unocss

bun add -D unocss

:::

You can also install the standalone package:

::: code-group

pnpm add -D @unocss/cli

yarn add -D @unocss/cli

npm install -D @unocss/cli

bun add -D @unocss/cli

:::

::: info If you are not able to find the binary (e.g. with pnpm and only unocss is installed), you'll need to explicit install @unocss/cli standalone package. :::

Usage

You can also pass multiple glob patterns to @unocss/cli:

unocss "site/snippets/**/*.php" "site/templates/**/*.php"

Example package configuration:

::: info Make sure to add escaped quotes to your npm script glob patterns. :::

{
  "scripts": {
    "dev": "unocss \"site/{snippets,templates}/**/*.php\" --watch",
    "build": "unocss \"site/{snippets,templates}/**/*.php\""
  },
  "devDependencies": {
    "@unocss/cli": "latest"
  }
}

Development

Add the --watch (or -w) flag to enable watching for file changes:

unocss "site/{snippets,templates}/**/*.php" --watch

Production

unocss "site/{snippets,templates}/**/*.php"

The final uno.css will be generated to the current directory by default.

Built-in features

Configurations

Create a uno.config.js or uno.config.ts configuration file the root-level of your project to customize UnoCSS.

::: tip To achieve more granular configuration management, we recommend using a configuration file. It also supports different levels of packaging and rewriting for scanned files. :::

import { defineConfig } from 'unocss'

export default defineConfig({
  cli: {
    entry: {}, // CliEntryItem | CliEntryItem[]
  },
  // ...
})

interface CliEntryItem {
  /**
   * Glob patterns to match files
   */
  patterns: string[]
  /**
   * The output filename for the generated UnoCSS file
   */
  outFile: string
  /**
   * Whether to rewrite the transformed utilities.
   *
   * - For css: if rewrite is true, it will not generate a new file, but directly modify the original file content.
   * - For other files: if rewrite is true, it replaces the original file with the transformed content.
   *
   * @default false
   */
  rewrite?: boolean

  /**
   * Whether to output CSS files scanned from patterns to outFile
   *
   * - false: Do not output CSS files
   * - true: Transform and output scanned CSS file contents to outFile
   * - 'multi': Output each CSS file separately with filename format `${originFile}-[hash]`
   * - 'single': Merge multiple CSS files into one output file named `outFile-merged.css`
   *
   * @default true
   */
  splitCss?: boolean | 'multi' | 'single'
}

Rewrite Source Files

Use the --rewrite flag to update your source files with transformed utilities. This is useful when you want to apply transformers (like Variant Groups or Compile Class) directly to your code.

unocss "src/**/*.vue" --rewrite

CSS Splitting

When CSS files are included in the defined patterns, use the --split-css flag to control the output of CSS.

• false: Do not output CSS files
• true: Transform and output scanned CSS file contents to outFile
• 'multi': Output each CSS file separately with filename format ${originFile}-[hash]
• 'single': Merge multiple CSS files into one output file named outFile-merged.css

unocss "src/**/*.vue" --split-css true|false|multi|single

Default Preset

If no uno.config.ts file is found, the CLI will use a default preset. You can specify which version of the default preset to use with the --preset flag.

• wind4: Use the preset-wind4.
• wind3: Use the preset-wind3.

unocss "src/**/*.vue" --preset wind3|wind4

Note: This option is ignored if a configuration file is present.

::: warning Starting from version v66.6.0, @unocss/cli no longer provides a default preset. Users need to explicitly specify the --preset option or configure the preset in the configuration file. :::

For a list of options, head over to the UnoCSS configurations docs.

Options