Using the CLI

Basic Usage

dispersa build

The CLI discovers your configuration automatically and builds all configured outputs.

Config File

The CLI looks for a config file named dispersa.config.ts (or .js, .mts, .mjs, .cts, .cjs) in your project root. Use defineConfig for type safety:

import { defineConfig } from 'dispersa/config'
import { css, json } from 'dispersa'
import { colorToHex } from 'dispersa/transforms'

export default defineConfig({
  resolver: './tokens.resolver.json',
  buildPath: './dist',
  outputs: [
    css({
      name: 'css',
      file: 'tokens.css',
      preset: 'bundle',
      selector: ':root',
      transforms: [colorToHex()],
    }),
    json({
      name: 'json',
      file: 'tokens-{theme}.json',
      preset: 'standalone',
      structure: 'flat',
    }),
  ],
})

Custom Config Path

To use a config file in a different location:

dispersa build --config ./my-config.ts

Lint Command

Run linting independently of the build:

dispersa lint

The lint command requires a lint configuration in your config file:

import { defineConfig } from 'dispersa/config'
import { dispersaPlugin } from 'dispersa/lint'

export default defineConfig({
  resolver: './tokens.resolver.json',
  lint: {
    plugins: { dispersa: dispersaPlugin },
    rules: {
      'dispersa/require-description': 'warn',
    },
  },
})

Lint Options

Flag	Description
`--config <path>`	Path to config file (same as build)
`--format <format>`	Output format: `stylish` (default), `json`, `compact`
`--verbose`, `-v`	Show detailed output

Output Formats

stylish (default) — Human-readable output with color-coded issues
json — JSON output for CI pipelines
compact — Single-line output with issue counts

How It Works

The CLI uses jiti for dynamic ESM imports, so you can use TypeScript config files (dispersa.config.ts) without precompiling them.

Project Structure Recommended directory layouts for organizing tokens, resolver, and build configuration.