> ## Documentation Index
> Fetch the complete documentation index at: https://aerojs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Validate templates, check types, and diagnose your project with the Aero CLI.

Install the Aero CLI as a dev dependency in your project:

```bash theme={"theme":"github-dark-default"}
pnpm add -D @aero-js/cli
```

Once installed, run any command from your project root using `pnpm exec aero <command>`. Use the `--root` flag if your app lives in a subdirectory:

```bash theme={"theme":"github-dark-default"}
pnpm exec aero check --root packages/my-app
```

## Commands

### aero check

`aero check` validates your project without starting a dev server or running a full build. It checks your Aero config, content collections, and compiles every `.html` template to catch parse and codegen errors.

```bash theme={"theme":"github-dark-default"}
pnpm exec aero check
```

Add `--types` to also run configured TypeScript/JavaScript checking against live build, state,
bundled, inline, and blocking scripts plus `{ }` expression sites:

```bash theme={"theme":"github-dark-default"}
pnpm exec aero check --types
```

With `--types`, the CLI writes `.aero/cache/types/components.d.ts` so cross-file component references resolve correctly during the check. Resolution uses your workspace `tsconfig.json`, including path aliases and `strict` mode.

#### Exit codes

| Code | Meaning                                 |
| ---- | --------------------------------------- |
| `0`  | No error-level diagnostics              |
| `10` | Config error                            |
| `12` | Compile, resolve, or build-script error |
| `13` | Content schema error                    |
| `14` | Route error                             |

### aero doctor

`aero doctor` prints a short environment checklist for your project:

* Node.js version (exits `1` if below the minimum, currently Node 18)
* `vite` presence in `package.json`
* `@aero-js/core` or `@aero-js/core/vite` presence in `package.json`
* `@aero-js/cli` version
* A reminder about the Aero VS Code extension

Each line is prefixed with one of `[ok]`, `[warn]`, `[info]`, or `[fail]`. Warnings still exit `0`.

```bash theme={"theme":"github-dark-default"}
pnpm exec aero doctor
```

### aero build

`aero build` runs `vite build` using your project's Aero Vite config. Use `--incremental` to enable [incremental builds](/tooling/incremental-builds) for that run:

```bash theme={"theme":"github-dark-default"}
pnpm exec aero build
pnpm exec aero build --incremental
```

## CI usage

Use `aero check` in CI to catch template and content errors before deploying. Add `--types` to also fail the pipeline on TypeScript errors.

<CodeGroup>
  ```yaml aero check theme={"theme":"github-dark-default"}
  - run: pnpm install
  - run: pnpm exec aero check
  ```

  ```yaml aero check --types theme={"theme":"github-dark-default"}
  - run: pnpm install
  - run: pnpm exec aero check --types
  ```
</CodeGroup>

Use `--root` when your CI job's working directory is not the app root:

```yaml theme={"theme":"github-dark-default"}
- run: pnpm exec aero check --root packages/my-app
```

<Note>
  `aero check` validates config, content, and template compilation. It does not execute SSR, Nitro,
  or a full Vite build, so it runs faster than `vite build` in CI.
</Note>

## Why the CLI is a separate package

The CLI lives in `packages/cli`, depends on `@aero-js/core` (including `@aero-js/core/config` and `@aero-js/core/compile-check` subpaths) and `@aero-js/content`, and publishes the `aero` binary. Keeping check/doctor/build out of core avoids coupling the runtime package to CLI orchestration.

## How `aero check` works (summary)

* **Config** — `loadAeroConfig(root)` from `@aero-js/core/config` loads `aero.config.ts`, `.js`, or `.mjs` with the same behavior as Vite. If the config is missing or fails to load in some edge cases, behavior may fall back to default `dirs`; use `vite build` or `DEBUG=aero` if templates under a custom client directory seem skipped.
* **Content** — When `aero.content` is enabled or a `content.config.ts` exists, collections are loaded and validated. See [Content](/getting-started/content).
* **Templates** — Every `.html` under `client/pages`, `client/components`, and `client/layouts` (per `dirs`) is passed through `compileTemplate` for parse and codegen checks, **without** a full Vite build.

`vite.config.ts` should import `createViteConfig` from `@aero-js/core/vite-config` so `aero.config.ts` can load without pulling Vite into the config entrypoint.

<AccordionGroup>
  <Accordion title="Programmatic APIs for tooling">
    **`@aero-js/cli`** — The `aero` binary is the supported entry. `runAeroCheck` and `runAeroDoctor`
    implement `aero check` and `aero doctor`; they are not necessarily exported as stable
    programmatic APIs for apps — prefer invoking the CLI in CI.

    **`@aero-js/core/config`** — `loadAeroConfig(root)` loads project config. Effect-based loaders exist for
    stricter failure handling where you need them.

    **`@aero-js/content`** — `loadContentConfigFileSync`, `loadAllCollections`, and
    `contentSchemaIssuesToAeroDiagnostics` support the same content pipeline as the CLI.

    **`@aero-js/core/compile-check`** — `compileTemplate` for Node-only tooling that needs compile
    checks without browser-oriented entrypoints.

    **`@aero-js/diagnostics`** — `formatDiagnosticsTerminal`, `unknownToAeroDiagnostics`,
    `AeroDiagnostic`, and related helpers; `aero check` uses the same diagnostics contract as other
    tooling surfaces.
  </Accordion>
</AccordionGroup>