# CLI overview

The `shadcn-maestro` CLI maps a web application, records what each screen does and stores independent reviews of that reading. The `design-apply` agent drives it, and you can run it yourself.

## Install

The CLI needs Node.js `>=24.2`. `agent-browser` and `shadcn` are prerequisites: install them first, at their latest versions.

```sh
npm i -g agent-browser@latest shadcn@latest
npm i -g shadcn-maestro
```

This puts `shadcn-maestro` on your PATH. Chrome is never downloaded; without it the browser review is reported as not done.

## Usage

```
shadcn-maestro <command> [--cwd <path>] [--json]
```

| Command | What it does |
| --- | --- |
| `shadcn-maestro help` | Show usage |
| [`shadcn-maestro reviewer [--screen <id>]`](/cli/reviewer) | Map the whole application; print a summary or one screen |
| [`shadcn-maestro reviewer annotate --input <file\|->`](/cli/annotate) | Submit a semantic annotation (JSON); it is saved as pending review |
| [`shadcn-maestro reviewer review --input <file\|->`](/cli/review) | Record an independent verdict (JSON) for an exact annotation revision |

| Flag | Meaning |
| --- | --- |
| `--cwd <path>` | Application directory (default: the current one) |
| `--json` | Print one [JSON envelope](/cli/json-envelope) on stdout |
| `--screen <id>` | Print one screen instead of the summary |
| `--input <file\|->` | Read the annotation or review JSON from a file or from stdin (`-`) |

## Exit codes

| Exit code | Status | Meaning |
| --- | --- | --- |
| `0` | `ok` | Completed |
| `2` | `error` | Invalid input or failed operation |
| `3` | `pending` | Blocked pending a condition, such as outdated prerequisites or a disputed annotation |

Diagnostics always go to stderr. Stdout carries the JSON envelope with `--json`, or the readable text otherwise; an `error` prints no text on stdout.

## Where the map lives

The map is written to `.shadcn-maestro/map/` in the application: `index.json` plus one record per file, screen and component. Every reference carries a file path, a SHA-256 hash and a line and column span, and the map is refreshed from those hashes, so a stale reading is detected instead of trusted.

## Supported stacks

Routes are resolved by one adapter per framework: Next.js App Router, Next.js Pages Router, React entry (`createRoot`), React Router, React Router framework mode, TanStack Start and Laravel with Inertia. The package manager (npm, pnpm, yarn or bun) is detected from the lockfiles and `packageManager`. Astro projects are rejected with `astro_not_supported`.