# CLI reference

Run from a site root, or pass `--root` (short `-r`) to point at one.

In the Aftercare monorepo, use `npx tsx src/cli.ts …` or the npm scripts (`npm run build:example`, etc.). Installed sites use `npx aftercare …`.

## `aftercare init [name]`

Create a new site by copying the studio starter.

| Argument | Default | Description |
|---|---|---|
| `name` | `my-site` | Directory to create (must be empty or missing) |

```powershell
npx aftercare init my-site
```

## `aftercare sync`

Regenerate the agent surface from theme contracts:

- `AGENTS.md`
- `agent/catalog.toon`, `agent/schemas/*.schema.json`, `agent/README.md`
- `.cursor/skills/aftercare-content/` and `aftercare-theme/`

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |

```powershell
npx aftercare sync --root examples/studio
```

## `aftercare watch`

Watch `theme/`, `content/`, and `public/`. On change: sync, validate, and rebuild HTML.

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `--no-build` | off | Sync and validate without writing HTML |

```powershell
npx aftercare watch
npx aftercare watch --no-build
```

## `aftercare validate`

Validate TOON/JSON content against section contracts (Zod schemas from `defineSection`).

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |

```powershell
npx aftercare validate
```

## `aftercare doctor`

Diagnose theme, content, routes, and image assets. Prints a human-readable report; can also emit JSON for agents.

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `--json` | off | Print agent-readable JSON |
| `--write` | off | Write report to `agent/doctor.json` |

```powershell
npx aftercare doctor
npx aftercare doctor --json --write
```

Typical checks: missing contracts, invalid section props, duplicate slugs, missing local images, empty alt text.

## `aftercare build`

Sync agent files (unless skipped), run doctor, then write static HTML to `outDir` (default `dist/`).

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `--skip-sync` | off | Do not regenerate agent files |

Build fails if doctor reports errors.

```powershell
npx aftercare build
npx aftercare build --skip-sync
```

Environment:

| Variable | Description |
|---|---|
| `AFTERCARE_BASE_PATH` | URL prefix for subpath hosting (overrides `config.basePath`) |

## `aftercare serve`

Build the site, then serve `dist/` locally.

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `-p, --port <number>` | `4173` | Port |

```powershell
npx aftercare serve
npx aftercare serve --port 3000
```

## `aftercare ui`

Open the **local content studio** (shadcn UI) to edit `content/` and upload images into `public/`. Saves are validated with the same Zod/`runDoctor` pipeline as the CLI. This is not a CMS and is not part of the published site.

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `-p, --port <number>` | `4321` | Studio port (bound to `127.0.0.1`) |
| `--no-open` | off | Do not open a browser |

```powershell
npx aftercare ui
npx aftercare ui --root examples/studio --port 4321
```

Requires a built studio UI (`ui/dist`). From the framework repo, `npm run build:ui` once; `aftercare ui` will attempt to build it on first run.

See [Studio](./studio.md).

## `aftercare deploy <provider>`

Write a deployment recipe into the site.

| Argument | Values |
|---|---|
| `provider` | `github` or `netlify` |

| Option | Default | Description |
|---|---|---|
| `-r, --root <path>` | `.` | Site root |
| `--force` | off | Replace an existing recipe file |

```powershell
npx aftercare deploy github
npx aftercare deploy netlify --force
```

- **github** → `.github/workflows/aftercare-pages.yml`
- **netlify** → `netlify.toml`

See [Deploy](./deploy.md).

## Monorepo npm scripts

From the framework repository:

| Script | Command |
|---|---|
| `npm run sync:example` | sync `examples/studio` |
| `npm run watch:example` | watch `examples/studio` |
| `npm run validate:example` | validate example |
| `npm run doctor:example` | doctor example |
| `npm run build:example` | build example |
| `npm run serve:example` | serve example |
| `npm run ui:example` | open content studio for example |
| `npm run build:ui` | build the studio React app (`ui/`) |

## Exit codes

Commands exit non-zero on failure. Aggregate validation errors print one `✗` line per issue.