# Overview

Every harness action is a command: scriptable with --json, and previewable with --dry-run where it changes files.

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.

In a terminal, run `npx sketchbook` without a command to explore the interactive menu. Enter a number to select an item, provide the requested values, and optionally review settings. Where available, examples show what to type. Mutating commands show a preview when supported; type `y` and press Enter to apply, or press Enter to cancel.

Use `sketchbook help <command> --details` for the full command reference. Terminal views may summarize long results; add `--details` to show the full output. For scripts and agents, use `--json` for the structured response.

```terminal
sketchbook help <command>
sketchbook check --json
sketchbook tokens set color.primary "#0F766E" --dry-run
```

## Conventions

- Bare `sketchbook` in a terminal opens an interactive menu built from this registry: enter a number to pick a group and command, provide arguments, and optionally review settings. Mutating commands show a dry run where supported; type y and press Enter to confirm, or press Enter to cancel. Piped input or `--json` prints help instead.
- `--details` shows full human-readable output where a terminal view is abbreviated.
- `--json` on 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 |
| `--details` | Show the full human-readable output |

## 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 help`
- `sketchbook help init`

## Project setup

Create, inspect, repair and upgrade a Sketchbook project.

| Command | What it does |
| --- | --- |
| [`init`](/cli/project/#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`](/cli/project/#status) | Show the prefix, brand summary, components by status, overrides and design sync state (read-only). |
| [`doctor`](/cli/project/#doctor) | Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks,… |
| [`upgrade`](/cli/project/#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`](/cli/project/#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`](/cli/project/#generate) | Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what… |
| [`prefix`](/cli/project/#prefix) | Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check. |
| [`swap`](/cli/project/#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`](/cli/foundations/#tokens) | Change foundations and semantic tokens through the harness: set, preset, presets, diff, impact, add, remove, rename, import, scratch, overrides. |
| [`presets`](/cli/foundations/#presets) | List the standards catalog: families, or one family's presets with sources (read-only). |
| [`brand`](/cli/foundations/#brand) | Several brands over one semantic interface: brands/<name>.brand.json; add, list, use (copy into brand.config.json and regenerate) and build… |
| [`audit-css`](/cli/foundations/#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`](/cli/components/#add) | Install a component from the catalog (contract, code, stories, specs; dependencies first), or --blank to scaffold a new contract (status draft,… |
| [`remove`](/cli/components/#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`](/cli/components/#list) | List catalog components (installed or available) with what each needs, plus template kits (read-only). |
| [`kits`](/cli/components/#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`](/cli/components/#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`](/cli/design-file/#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`](/cli/design-file/#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`](/cli/design-file/#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`](/cli/quality/#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`](/cli/quality/#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`](/cli/quality/#check) | Run the deterministic checks (exit 0 pass, 1 fail, 2 pass with flagged overrides). |
| [`selftest`](/cli/quality/#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`](/cli/quality/#explain) | Explain a token, CSS variable, component, tag or decision from the spec. |
