CLI

node src/cli.mjs <command> [--flags]
# or
facet <command> [--flags]   # when `facet` binary is available

Supported commands:

• build
• check
• theme
• remap
• graph
• export
• import
• validate
• init
• mcp
• playground
• ramp
• types
• tailwind
• styledict

build

facet build <resolver> [--out dist] [--format rgb|oklch] [--minify]

Writes all standard artifacts under --out.

check

facet check <resolver>
facet check <resolver> --json

Runs contrast + switch-safety checks and authored-style validation. Returns non-zero on failure.

theme

facet theme <resolver> --brief "calm natural growth" --name verdant --write
facet theme <resolver> --seed "0.62,0.17,150"

Generates a contrast-correct brand token set from brief/seed. --write stores to brands/<name>.facet.json.

ramp

facet ramp --brief "energetic orange" --name accent
facet ramp --seed "#ff8a3d"

Generates a 50→950 tone ramp as DTCG JSON.

remap

facet remap <resolver> #5a67e8 #ff8a3d

Maps each input hex to nearest token by ΔEOK.

graph

facet graph <resolver>
facet graph <resolver> color.action

Without a token path: prints graph dependencies. With token path: prints per-mode value, deps, dependents.

export

facet export <resolver>
facet export <resolver> --out tokens.dtcg.json
facet export <resolver> --figma --out figma.json

Outputs pure DTCG by default, or Figma Variables payload with --figma.

import

facet import legacy.tokens.json

Converts legacy / Tokens-Studio style JSON to Facet .facet.json.

validate

facet validate <resolver> '{"bg":"action"}'
facet validate <resolver> '[{"bg":"action"},{"bg":"missing"}]'

Checks one or more fx objects for off-system values.

types

facet types <resolver>
facet types <resolver> --out facet.d.ts

Generates token-strict TypeScript declarations for the current graph.

tailwind and styledict

facet tailwind <resolver>
facet styledict <resolver>

Generate cross-tooling presets/JSON for interop.

playground and mcp

facet playground <resolver> --out pg.html
facet mcp <resolver>

playground writes a self-contained mode explorer. mcp starts the tool server on stdio.

init

facet init [dir]

Creates scaffold files for a starter project.

Script shortcuts (package scripts)

In the source package root, these are equivalent:

• npm run build → node src/cli.mjs build tokens/app.resolver.json --out dist
• npm run check → node src/cli.mjs check tokens/app.resolver.json
• npm run typecheck regenerates types via build and runs tsc