Overview
Every harness action is a command: scriptable with --json, and previewable with --dry-run where it changes files.
On this page
The sketchbook CLI is the deterministic half of the harness. Run sketchbook <command>, or node harness/cli.mjs <command>. This section is split by topic and generated from the command modules by npm run generate, so it matches the CLI as of the last build.
sketchbook help <command>
sketchbook check --json
sketchbook tokens set color.primary "#0F766E" --dry-run
Conventions
- Bare
sketchbookin a terminal opens an interactive menu built from this registry: pick a group and a command, answer prompts (current values shown), see the dry run, then confirm. Piped input or--jsonprints help instead. --jsonon every command prints one envelope:{ ok, command, changed[], warnings[], errors[{file, msg, fix}], next, data? }.- Exit codes: 0 ok, 1 failed, 2 ok with flags (for example overrides kept in spec/tokens/overrides.json).
- Read-only commands never write. Mutating commands say what they change; those marked "dry run" accept
--dry-run. - Conventions (one registry, introspect before mutate, JSON envelope) are adapted from CLI-Anything (HKUDS, Apache-2.0, https://github.com/HKUDS/CLI-Anything); no code is used.
| Global option | Meaning |
|---|---|
--json |
Print one JSON envelope instead of human output |
--dry-run |
Show what would change without writing (mutating commands that support it) |
--help |
Show help for the command |
Getting help
help
List commands, or show one command's arguments, options and examples.
sketchbook help [command] [--json]
Read-only.
| Argument | Meaning |
|---|---|
command (optional) |
A command name |
Examples:
sketchbook helpsketchbook help init
Project setup
Create, inspect, repair and upgrade a Sketchbook project.
| Command | What it does |
|---|---|
init |
In a new or empty folder: install the core harness and any selected agent integrations. In a project: add or repair integrations (--agent), pick a… |
status |
Show the prefix, brand summary, components by status, overrides and design sync state (read-only). |
doctor |
Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks,… |
upgrade |
Update harness-owned files. In a project that runs the engine from node_modules: from the installed engine (after npm update), no --from.… |
propagate |
Carry a Foundations or harness change to every output: rebuild the tokens and components, build the engine, sync the design file scripts (tokens… |
generate |
Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what… |
prefix |
Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check. |
swap |
Replace an adapter (token build or design tool) without touching the spec, then rebuild and check. |
Tokens and brand
Change foundations, presets and brands, and import or audit existing styles.
| Command | What it does |
|---|---|
tokens |
Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides. |
presets |
List the standards catalog: families, or one family's presets with sources (read-only). |
brand |
Several brands over one semantic interface: brands/ |
audit-css |
Audit an existing product's CSS: cluster its colors (OKLCH distance), font sizes, spacing, radii and shadows into a foundations proposal… |
Components and kits
Install, remove and list components and kits, and read the naming standard.
| Command | What it does |
|---|---|
add |
Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft,… |
remove |
Uninstall a component: refuses while another component or a kit needs it, and without --yes when it is team-made or customized; else removes its… |
list |
List catalog components (installed or available) with what each needs, plus template kits (read-only). |
kits |
Template kits (harness/kits/index.json): list them, add one (its components come from the catalog first) or remove one (--yes when it was edited). |
api |
The API vocabulary (spec/api.json): list every component prop, event and state against it (canonical, alias, extension), check that nothing is… |
Design file
Sync variables, styles and docs to the design file, and manage icons.
| Command | What it does |
|---|---|
icons |
The icons the system uses (spec/icons.json, Lucide): list them, add one or more from Lucide (--category) or remove them. The design adapters draw… |
sync |
Write the Figma MCP (use_figma) scripts for the design file (tokens: variable collections, modes and styles), read the file back ("sync verify",… |
docs |
Show a component's or a pattern's documentation, tool-neutral: the same doc a design file draws (variants and states grids, elements, anatomy,… |
Quality and checks
Run the deterministic checks, self-test the harness and trace where a value comes from.
| Command | What it does |
|---|---|
audit-page |
Check a complete HTML page using this design system for a level-one heading and main landmark. This static check is not a full accessibility audit. |
audit-decisions |
Compare the decision log with a trusted earlier copy or Git revision and report changes to settled entries. This read-only audit does not replace… |
check |
Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides). |
selftest |
Run the harness's own tests against the installed engine: they prove every check can still reject and that the CLI, starters and generators work… |
explain |
Explain a token, CSS variable, component, tag or decision from the spec. |