> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crust.moumen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Every command, every flag.

Commands that analyze a build accept:

| Flag               | Default           | Meaning                                      |
| ------------------ | ----------------- | -------------------------------------------- |
| `--cwd <dir>`      | Current directory | Directory containing the Next.js application |
| `--dist-dir <dir>` | `.next`           | Build-output directory, relative to `cwd`    |

This keeps monorepo usage explicit: point `--cwd` at the app, while snapshots and budgets are stored
at the detected workspace root.

## analyze

Analyse a production build and record a snapshot.

```bash theme={null}
npx @moumensoliman/crust analyze [--json [file]] [--no-save]
```

| Flag            | Meaning                                                    |
| --------------- | ---------------------------------------------------------- |
| `--json [file]` | Emit the snapshot as JSON. With no path, prints to stdout. |
| `--no-save`     | Do not write into `.perf/`.                                |

## diff

Compare this build against a stored snapshot. Exits non-zero if no baseline is found.

```bash theme={null}
npx @moumensoliman/crust diff [ref]
```

`ref` accepts a build id, a git SHA, a branch name, or `HEAD~3`. Defaults to `HEAD~1`.

## ci

Check automatic regressions and configured budgets, then print a PR comment. **Exits non-zero on a
breach.**

```bash theme={null}
npx @moumensoliman/crust ci [ref] [--comment <file>]
```

Defaults to comparing against `main`.

Without `.perf/budgets.json`, rendering-mode drops, newly uncached reads, and shell disappearance
still fail when the baseline is comparable. A budget file adds byte, growth, and shell-ratio
ceilings. See [regressions](/docs/concepts/regressions) and
[budgets](/docs/reference/budgets).

If no baseline exists, crust analyzes and snapshots the current build but warns that regressions
cannot be detected. Absolute ceilings still apply.

## report

Write a self-contained HTML report.

```bash theme={null}
npx @moumensoliman/crust report [--out crust-report.html] [--open]
```

No external requests: styles, script and data are inlined.

## manifest

Write the snapshot where the [in-app panel](/docs/guides/widget) can fetch it.

```bash theme={null}
npx @moumensoliman/crust manifest [--out public/crust-manifest.json]
```

<Warning>
  The manifest lists every route, source path and component name in your app. Generate it in analyze
  builds only.
</Warning>

## history

Sync snapshots with the orphan `perf-history` branch.

```bash theme={null}
npx @moumensoliman/crust history push [--remote origin]
npx @moumensoliman/crust history fetch [--remote origin]
```

`push` reports and exits cleanly when the remote rejects it - a fork PR's token is read-only on the
base repository, and that is not a failure worth breaking the check over.

## prune

Apply the retention ladder.

```bash theme={null}
npx @moumensoliman/crust prune [--dry-run]
```

Newest 50 builds at full fidelity → one per commit → module detail dropped after 90 days. Route
totals and shell ratios are kept forever.

## synthetic

Measure routes against a running deployment. Needs Playwright as an optional peer.

```bash theme={null}
npx @moumensoliman/crust synthetic <baseUrl> [...routes] \
  [--iterations 5] [--cpu 4] [--network fast-3g|slow-3g|none]
```

## list

List stored snapshots, newest first.

```bash theme={null}
npx @moumensoliman/crust list
```

## Exit codes

| Code | Meaning                                                             |
| ---- | ------------------------------------------------------------------- |
| `0`  | Success; no automatic regression or configured ceiling was breached |
| `1`  | Regression or budget breach, or `diff` found no baseline            |

Any unsupported project - Next outside 15–16, a dev-only build, a Pages Router app - throws with a
message naming the reason rather than emitting numbers it cannot stand behind.