---
title: CLI
description: Command-line interface — init, build, doctor, audit, and mcp.
canonical_url: https://next-ai-ready.vercel.app/en/docs/api-reference/cli
url: https://next-ai-ready.vercel.app/en/docs/api-reference/cli
last_updated: 2026-08-01
updated: 2026-08-01
author: next-ai-ready team
summary: Command-line interface — init, build, doctor, audit, and mcp.
topics: [api, reference]
---

# CLI

`next-ai-ready` provides commands for building, validating, auditing, and running your AI-ready site.

## Commands

### `next-ai-ready init`

Scaffolds handler stubs and config into your project.

```bash
npx next-ai-ready init
```

Creates:

- `ai-ready.config.mjs` — site configuration with placeholder values.
- `app/%5Fai-ready/` — route handler stubs (one-line re-exports).
- `app/api/actions/[name]/route.ts` — action execution endpoint.
- `app/api/mcp/[transport]/route.ts` — MCP server endpoint.
- `actions/index.mjs` — starter action file with a `ping` health check.

Use `--force` to overwrite existing files.

### `next-ai-ready build`

Scans content, compiles the semantic graph, and emits all artifacts.

```bash
npx next-ai-ready build
```

What it produces:

- `.next-ai-ready/graph.json` — the SemanticGraph.
- `.next-ai-ready/actions.manifest.json` — action manifest with JSON Schemas.
- `public/llms.txt` — site-wide LLM index.
- `public/llms-full.txt` — full content dump (page bodies plus `## FAQ` when `questions` exist in frontmatter).
- `public/openapi.json` — OpenAPI 3.1 spec.
- `public/tools.json` — tool definitions.
- `public/.well-known/ai-plugin.json` — plugin manifest.
- `public/robots.txt` — AI-bot policy.

Use `--silent` to suppress console output (useful in CI).

Typical `package.json` setup:

```json
{
  "scripts": {
    "build": "next-ai-ready build && next build"
  }
}
```

### `next-ai-ready doctor`

Validates your config, action exposure rules, and route wiring.

```bash
npx next-ai-ready doctor
npx next-ai-ready doctor --score   # 0–100 AI-readiness score + top fixes
npx next-ai-ready doctor --json    # machine-readable report (includes actionItems)
```

Checks include:

1. **Config** — `ai-ready.config.mjs` with required `site.name`, `site.baseUrl`, and `site.description`.
2. **Actions** — public vs private counts; warns if public actions lack `whenToUse`.
3. **Build artifacts** — graph, OpenAPI, `package.json` prebuild script.
4. **Route stubs** — `app/%5Fai-ready/*` handler files and `withAiReady()` in `next.config`.
5. **Robots** — static `public/robots.txt` **or** `app/robots.ts` (when `emit.robots: false`, doctor does not warn about a missing static file).
6. **MCP** — warns if `NEXT_AI_READY_MCP_TOKEN` is unset in production.
7. **Content quality** — `noai` meta, JSON-LD helpers, `updatedAt` / `author` coverage in the graph.

Exits with code 1 if any **errors** are found. Warnings do not cause a non-zero exit.

With `--score`, the CLI prints **Top fixes** (e.g. add prebuild, set MCP token, add `updatedAt` to frontmatter).

Use in CI:

```yaml
# .github/workflows/ci.yml
- run: npx next-ai-ready doctor --score
```

### `next-ai-ready audit <url>`

Audits a deployed page as browsers, crawlers, and AI agents actually receive it.

```bash
npx next-ai-ready audit https://example.com/about
npx next-ai-ready audit https://example.com/about --json
npx next-ai-ready audit https://example.com/about --version 2 --json
npx next-ai-ready audit https://example.com/about --version 3 --json
```

The 100-point report checks the HTML response, `llms.txt`, both sitemap formats,
`robots.txt`, Markdown content negotiation, known AI User-Agents, explicit `.md`
URLs, canonical and response metadata, frontmatter, JSON-LD, description, H1,
browser `404` semantics, and agent Markdown recovery. Each check includes its
evidence URL and a concrete message.

Browser and agent missing-page behavior are deliberately separate: browser-style
HTML requests must return `404`, while an agent requesting Markdown should receive
a useful `200 text/markdown` recovery document. The audit also accepts equivalent
standards-compatible discovery metadata instead of requiring one framework-specific
combination of `Vary`, `Link`, and `Content-Location` headers.

Audit v1 remains the default. Its JSON fields, score calculation, and error-based
exit behavior are unchanged, and agent missing-page recovery remains an advisory
zero-weight check. This keeps existing parsers and CI thresholds compatible.

Pass `--version 2` to opt into the stable `next-ai-ready.audit.v2` schema. It
groups the same deployed checks into five independently scored dimensions:

| Dimension          | Overall weight |
| ------------------ | -------------: |
| `discovery`        |            20% |
| `content-citation` |            25% |
| `structured-data`  |            15% |
| `agent-access`     |            30% |
| `capabilities`     |            10% |

Every v2 warning or failure includes a targeted `recommendation`; passing checks
set it to `null`. The top-level score is the weighted total of the five dimension
scores. Select v2 explicitly in CI until you have adopted its schema and rubric.

Pass `--version 3` for the `next-ai-ready.audit.v3` schema. It reports Agent
Readability, Semantic/AEO Quality, and Agent Capability separately, gives no
partial credit to warnings, and marks each check as either `external-standard` or
`next-ai-ready-enhancement`. The top-level compatibility score is the local
Readability preflight score; run the pinned `pnpm audit:vercel:site` command for
the official external Vercel score. V3 is intentionally a smaller local preflight,
not a reimplementation of all 25 official checks.

For missing pages, v3 scores the Vercel-compatible `200 text/markdown` behavior
in Agent Readability. The stricter `noindex` plus recovery-link guidance is a
separate `next-ai-ready-enhancement` in Semantic/AEO Quality, so it cannot create
a false failure against the external standard.

The command exits with code 1 when a required check fails, so the JSON form can
act as a post-deployment CI gate. Warnings reduce the score without failing CI.

### `next-ai-ready mcp`

Starts an MCP server over stdio for local desktop clients.

```bash
npx next-ai-ready mcp
```

Options:

| Flag             | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `--no-resources` | Skip graph-backed page resources and discovery tools (faster startup). |

Use with Claude Desktop:

```json
{
  "mcpServers": {
    "my-site": {
      "command": "npx",
      "args": ["next-ai-ready", "mcp"]
    }
  }
}
```

## Exit codes

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| `0`  | Success.                                                |
| `1`  | Error (missing config, invalid actions, build failure). |
| `2`  | Unknown command.                                        |