CLI Reference

The aplica-theme-engine CLI is the primary interface for generating and building design tokens. All commands run against the current consumer workspace — the engine reads your configuration from aplica-theme-engine.config.mjs and writes all output inside your project root.

Installation

npm install @aplica/aplica-theme-engine

After installation, the CLI is available as theme-engine (or via npx theme-engine).

Command groups

Group	Purpose
Build	Transform `data/` into `dist/`
Generate	Generate `data/` from config
Architecture	Sync token references across layers
Validate	Validate `data/` contract before build
Setup	Scaffold consumer workspace and schemas
AI Skills	Inject AI editor integrations into consumer workspace
Migration	Migrate monolithic projects to package model

Build commands

`build` (recommended default)

Runs the full generation + build pipeline in a single command. This is the recommended command for CI and day-to-day use.

theme-engine build

Pipeline executed:

ensure:data — validates / creates data/ directory structure
themes:generate — decomposes brand colors into OKLCh palettes
dimension:generate — generates the spatial scale (minor / normal / major)
sync:architecture — propagates token references across all layers
foundations:generate — generates Foundation aliases from Semantic tokens
figma:generate — generates Tokens Studio / Figma scaffolding files
build:all — transforms data/ into dist/ via Style Dictionary

build and build:themes are aliases for the same command.

`build:all`

Transforms the existing data/ into dist/ without regenerating data/. Use this when the token data is already correct and you only need to rebuild the output artifacts.

theme-engine build:all

Useful for iterating on output format changes without re-running the full generation pipeline.

`build:semantic`

Builds only the Semantic layer output.

theme-engine build:semantic

`build:foundation`

Builds only the Foundation layer output.

theme-engine build:foundation

`build:components`

Builds only the Components layer output. Skipped with an informational message if data/components does not exist.

theme-engine build:components

Generate commands

These commands produce or update data/ from your configuration. Run them individually when you need to regenerate a specific pipeline stage.

`themes:generate`

Decomposes all brand color configurations into the full OKLCh token palette. Writes to data/brand/, data/mode/, and data/surface/.

theme-engine themes:generate

`themes:single <brand>`

Generates the token data for a single brand. Useful during brand development when you don't want to regenerate all brands.

theme-engine themes:single my-brand

`dimension:generate`

Generates the spatial scale (spacing, sizing, border radius) for all three dimension variants (minor, normal, major). Writes to data/dimension/.

theme-engine dimension:generate

`foundations:generate`

Generates Foundation token aliases from the Semantic layer. Writes to data/foundation/.

theme-engine foundations:generate

`figma:generate`

Generates (or merges) the three files Tokens Studio needs to understand which token sets belong to which theme variant. Writes to data/.

theme-engine figma:generate

Files produced:

File	Purpose
`data/$themes.json`	Active theme entries imported by Tokens Studio. Preserves Figma-owned fields on merge (`id`, `$figmaStyleReferences`, variable IDs).
`data/$themes.engine.json.template`	Engine-owned template with the same structure and empty Figma fields. Use as a reset reference.
`data/$metadata.json`	Token-set load order for the active workspace.

Use this command standalone when you added or renamed a theme, surface, or mode and want to update the Tokens Studio files without running a full build. In a full build (theme-engine build), this step runs automatically between foundations:generate and build:all.

Do not delete data/$themes.json. If it is deleted, Figma style references stored in it are lost.

`ensure:data`

Validates the data/ directory structure and creates any missing directories. Run before generation commands when setting up a new workspace.

theme-engine ensure:data

Architecture commands

`sync:architecture`

Propagates token references across all layers (Brand → Mode → Surface → Semantic → Foundation). Run after themes:generate and before foundations:generate.

theme-engine sync:architecture

`sync:architecture:test`

Runs architecture sync in test mode — reports what would change without writing to data/.

theme-engine sync:architecture:test

`sync:architecture:schema`

Runs architecture sync in schema mode — validates the token structure contract.

theme-engine sync:architecture:schema

Validate commands

`validate:data`

Validates the current data/ directory against:

The active consumer generation schemas
The data-output contract schemas
Foundation and typography style contracts

theme-engine validate:data

Run this before build:all in CI to catch generation errors before the Style Dictionary build.

validate:data and data:validate are aliases.

Setup commands

`init`

Scaffolds a new consumer workspace. Run this once after installing the package.

theme-engine init

Offers two onboarding paths:

Load starter template — ready-to-run workspace with one starter theme
Create using the wizard — same base + generates theme-engine/schemas/architecture.mjs from guided answers

init and consumer:init are aliases.

`schemas:helper`

Interactively generates a theme-engine/schemas/architecture.mjs scaffold. Use this when you need to customize the token structure contract beyond what the starter template provides.

theme-engine schemas:helper

The helper asks about:

Brand items
Intensity / decomposition levels
Interface function items
Feedback items and variants
Product categories and variants
Gradient names

schemas:helper and schemas:init are aliases.

AI Skills commands

`ai:init`

Injects AI editor integration files into the consumer workspace. Run once after installing or upgrading the package to give your AI coding assistant (Cursor, Claude Code, GitHub Copilot) structured knowledge of the token contract.

theme-engine ai:init

Files injected:

Destination	Purpose
`docs/context/aplica-ui-integration.md`	Agnostic UI integration guide for any AI surface
`.cursor/rules/aplica-ui-integration.mdc`	Cursor-specific rule activating token-aware code generation
`.claude/skills/aplica-ui-integration/SKILL.md`	Claude Code skill for sanctioned token consumption patterns
`.github/instructions/aplica-ui.instructions.md`	GitHub Copilot instructions for token-aware completions

All files are copied from the package's versioned templates/ai-skills/ directory. Re-running the command overwrites existing files — safe to run after every package upgrade to keep AI guidance in sync with the current token contract.

ai:init, ai:setup, skills, and skills:init are all aliases for the same command.

Migration commands

`migrate:legacy-consumer`

Migrates a monolithic (pre-package) project to the consumer workspace model. Validates parity between the migrated output and the original project.

Recommended: run the full migration in one step

theme-engine migrate:legacy-consumer run --source <path-to-legacy-project>

This command:

Analyzes the legacy project structure
Selects the appropriate migration profile
Converts the workspace
Runs the build for the chosen profile
Compares the converted data/ and dist/ against the legacy reference

Run phases separately (for inspection or debugging)

# Analyze only — no changes made
theme-engine migrate:legacy-consumer analyze --source <path>

# Convert only
theme-engine migrate:legacy-consumer convert --source <path>

# Compare only (after a conversion has already been run)
theme-engine migrate:legacy-consumer compare --source <path>

Options

Flag	Description
`--source <path>`	Path to the legacy project root
`--force`	Overwrite an existing converted workspace (for repeated migration tests)
`--profile <name>`	Migration profile (auto-detected when omitted)

Parity meaning:

Data parity — the converted workspace reproduces the same data/ as the original
Dist parity — the converted workspace reproduces the same dist/ as the original
Metadata-only drift does not fail parity

Migration artifacts are written to temp/outputs/legacy-migration/ — source fixtures remain unchanged.

migrate:legacy-consumer and legacy:migrate are aliases.

Common workflows

First build in a new project

npm install @aplica/aplica-theme-engine
npx theme-engine init
npm run tokens:build

Rebuild after changing brand colors

npm run tokens:themes   # regenerate brand + mode + surface data
npm run tokens:sync     # propagate references
npm run tokens:foundations
npm run tokens:build:all

Or simply:

npm run tokens:build    # full pipeline — always safe

Rebuild output formats only (no color changes)

npm run tokens:build:all

Regenerate Figma scaffolding only

npm run tokens:figma

Use after adding or renaming a theme, surface, or mode when token values have not changed.

Validate before publishing

npx theme-engine validate:data && npm run tokens:build:all

Installation​

Command groups​

Build commands​

build (recommended default)​

build:all​

build:semantic​

build:foundation​

build:components​

Generate commands​

themes:generate​

themes:single <brand>​

dimension:generate​

foundations:generate​

figma:generate​

ensure:data​

Architecture commands​

sync:architecture​

sync:architecture:test​

sync:architecture:schema​

Validate commands​

validate:data​

Setup commands​

init​

schemas:helper​

AI Skills commands​

ai:init​

Migration commands​

migrate:legacy-consumer​

Common workflows​

First build in a new project​

Rebuild after changing brand colors​

Rebuild output formats only (no color changes)​

Regenerate Figma scaffolding only​

Validate before publishing​