Project setup
Create, inspect, repair and upgrade a Sketchbook 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 starting point (--start), or set the brand.
sketchbook init
[--name <value>]
[--primary <value>]
[--font <value>]
[--radius <value>]
[--density <value>]
[--danger <value>]
[--design <value>]
[--file <value>]
[--prefix <value>]
[--start <starter>]
[--components <a,b>]
[--from <file>]
[--yes]
[--dir <folder>]
[--adopt]
[--engine <spec>]
[--no-install]
[--agent <profiles>]
[--with <groups>]
[--detach-catalog]
[--dry-run]
[--json]
Changes files; supports --dry-run.
| Option | Meaning |
|---|---|
--name |
Brand or system name |
--primary |
Primary color as #RRGGBB, or "neutral" for the shadcn default |
--font |
Font family name (falls back to the system stack) |
--radius |
sharp | soft | round | pill-heavy (sketchbook presets radius) |
--density |
compact | comfortable | spacious |
--danger |
Destructive color as #RRGGBB |
--design |
Design-file adapter: figma | none |
--file |
Figma file key (when design is figma) |
--prefix |
Element and CSS prefix, e.g. acme (acme-button, --acme-*); rewrites sources (see sketchbook prefix) |
--start |
Starting point: blank | foundations | library (default) | library+kits | pick | import | from-codebase (harness/starters) |
--components |
With --start: the components to have (pick needs it; all | none also work); dependencies come along |
--from |
With --start import: the tokens file; with --start from-codebase: the CSS path or glob to audit |
--yes |
Confirm what would lose work: with --start, removing components or kits the starter does not include; with brand options or a starter that patches foundations, letting the brand links overwrite hand-edited linked tokens. It never detaches the catalog |
--dir |
Create the project in this folder (new or empty), e.g. a design-system folder inside an existing repository; default: here |
--adopt |
In an existing project: add the design system in its own folder (design-system/, or --dir) without changing your files; your package.json gets one script that runs its checks |
--engine |
For new projects, override the engine dependency with an npm version or tag, a local tarball, or a Git URL. A published CLI uses its version range by default. Relative local paths are resolved from the directory where init starts |
--no-install |
New project only: skip npm install and the Chromium download (init lists them as next steps) |
--agent |
Install selected agent profiles (comma-separated): claude, codex, gemini, copilot, trae, jetbrains, generic. New projects default to core only |
--with |
Select the Claude profile and add optional groups (comma-separated): forge. Forge adds the forge-me-a-skill skill |
--detach-catalog |
With --start in the catalog source repo (catalog.source true): stop tracking harness/catalog; the components become the team's own |
Examples
sketchbook initsketchbook init --agent claudesketchbook init --agent codex,trae --dry-runsketchbook init --dir design-system --start librarysketchbook init --start librarysketchbook init --with forgesketchbook init --start blank --yessketchbook init --start pick --components card,buttonsketchbook init --start from-codebase --from "../app/**/*.css"sketchbook init --primary "#2563EB" --font Inter --radius roundsketchbook init --density compact --dry-run
status
Show the prefix, brand summary, components by status, overrides and design sync state (read-only).
sketchbook status [--json]
Read-only.
Examples
sketchbook statussketchbook status --json
doctor
Health report (read-only): starter, harness version, installed vs catalog components, kits, brands, overrides, design sync, failing checks, selected agent integrations and the commit gate. Exits like check (0 pass, 1 a check fails, 2 pass with overrides).
sketchbook doctor [--json]
Read-only.
Examples
sketchbook doctorsketchbook doctor --json
upgrade
Update harness-owned files. In a project that runs the engine from node_modules: from the installed engine (after npm update), no --from. Elsewhere: from a newer Sketchbook folder or git URL (harness-owned in both manifests); team-owned, shared, reclassified and protected files (the manifest itself, configs, package files) are listed, never touched; writing anything needs --yes (a dry run first shows what).
sketchbook upgrade [--from <path|git-url>] [--yes] [--dry-run] [--json]
Changes files; supports --dry-run.
| Option | Meaning |
|---|---|
--from |
A newer Sketchbook: a folder, or a git URL (cloned shallowly; its commit is printed) |
--yes |
Confirm writing the upstream harness code (required whenever files would change), then run the checks with it |
Examples
sketchbook upgrade --from ../sketchbook --dry-runsketchbook upgrade --from ../sketchbook --yessketchbook upgrade --from https://example.com/sketchbook.git --dry-run
propagate
Carry a Foundations or harness change to every output: rebuild the tokens and components, build the engine, sync the design file scripts (tokens and foundations), and record what the outputs were built from. --maintainer also builds Storybook and the docs site (maintainers only).
sketchbook propagate [--maintainer] [--json]
Changes files.
| Option | Meaning |
|---|---|
--maintainer |
Also build Storybook and the docs site, and record them for check --maintainer |
Examples
sketchbook propagatesketchbook propagate --maintainer
generate
Rebuild every generated output from the spec: token CSS, component tokens, component styles, the barrel, brand CSS and the token interface (what npm run generate runs in a project).
sketchbook generate [--json]
Changes files.
Examples
sketchbook generatesketchbook generate --json
prefix
Rename the element and CSS prefix everywhere (sources, contracts, tests, docs), rebuild, then check.
sketchbook prefix <new> [--dry-run] [--json]
Changes files; supports --dry-run.
| Argument | Meaning |
|---|---|
new |
Lowercase letters and digits, e.g. acme |
Examples
sketchbook prefix acmesketchbook prefix acme --dry-run
swap
Replace an adapter (token build or design tool) without touching the spec, then rebuild and check.
sketchbook swap <output> <adapter> [--file <id>] [--dry-run] [--json]
Changes files; supports --dry-run.
| Argument | Meaning |
|---|---|
output |
What to swap: tokens |
adapter |
tokens: style-dictionary |
| Option | Meaning |
|---|---|
--file |
Design file key (design figma) |
Examples
sketchbook swap tokens plainsketchbook swap design none