# 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 init`
- `sketchbook init --agent claude`
- `sketchbook init --agent codex,trae --dry-run`
- `sketchbook init --dir design-system --start library`
- `sketchbook init --start library`
- `sketchbook init --with forge`
- `sketchbook init --start blank --yes`
- `sketchbook init --start pick --components card,button`
- `sketchbook init --start from-codebase --from "../app/**/*.css"`
- `sketchbook init --primary "#2563EB" --font Inter --radius round`
- `sketchbook 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 status`
- `sketchbook 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 doctor`
- `sketchbook 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-run`
- `sketchbook upgrade --from ../sketchbook --yes`
- `sketchbook 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 propagate`
- `sketchbook 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 generate`
- `sketchbook 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 acme`
- `sketchbook 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 | design |
| `adapter` | tokens: style-dictionary | plain; design: figma | none |

| Option | Meaning |
| --- | --- |
| `--file` | Design file key (design figma) |

**Examples**

- `sketchbook swap tokens plain`
- `sketchbook swap design none`
