---
title: "CLI"
description: "Check public agent readiness and manage runtime sync from the command line."
canonical_url: "https://nuxtseo.com/docs/ai-ready/guides/cli"
---

> Index of every page on this site: [llms.txt](https://nuxtseo.com/llms.txt)

Use the `nuxt-ai-ready` CLI to check a public page or manage stored pages.
Enable `runtimeSync` or `cron` before calling `status`, `poll`, `restore`, `prune`, or `reindex`.

## Installation

The CLI is included with the module. Run it via npx:

```bash
npx nuxt-ai-ready <command>
```

Or add a script to your `package.json`:

```json [package.json]
{
  "scripts": {
    "ai-ready": "nuxt-ai-ready"
  }
}
```

## Authentication

The `audit` command uses public GET requests. It needs no project, secret, or runtime sync configuration.

Set `NUXT_APP_SECRET` to the deployed site's application secret, with at least 32 characters.
The CLI derives the runtime sync token from it. Environment values take precedence over the local cache.
AI Ready and OG Image share this root secret, but derive separate tokens for their own purposes.

The legacy `NUXT_AI_READY_RUNTIME_SYNC_SECRET` remains supported with a deprecation warning.
Without an application secret, the CLI sends that legacy value unchanged.
A non-empty application secret takes precedence. Invalid application secrets fail instead of using the legacy token.

Without an environment value, commands read `node_modules/.cache/nuxt/ai-ready/secret` relative to `--cwd`.
Module setup caches the derived token when runtime sync is enabled and an application secret is available.
Nuxt generates a development root secret. Production builds require a configured secret, either during setup or at runtime.

For an external scheduler, print the derived bearer token:

```bash
pnpm exec nuxt-ai-ready token
```

Send that token in the `Authorization: Bearer <token>` header. Keep the root secret out of request headers.
If Vercel invokes your cron route, set its `CRON_SECRET` to this derived token.

## Commands

### audit

Check one deployed HTML page, Markdown negotiation, its direct `.md` URL, cache separation, and HTTP Content Signals.
The command also checks `robots.txt`, one sitemap, and an unknown route.

```bash
pnpm exec nuxt-ai-ready audit https://mysite.com/about
pnpm exec nuxt-ai-ready audit https://mysite.com/docs/about --base /docs/ --json
pnpm exec nuxt-ai-ready audit https://mysite.com/about --capabilities llms,mcp,skills
```

Declare optional features with `--capabilities`. Unselected features appear as `skip` and receive no failure penalty.
An advertised `api-catalog` Link header also enables its discovery check.
These checks inspect discovery documents. They do not invoke MCP tools or verify browser-side WebMCP registration.

| Option           | Default  | Description                                                          |
| ---------------- | -------- | -------------------------------------------------------------------- |
| `url`            | Required | One public page URL                                                  |
| `--base`         | `/`      | Application base path for discovery URLs                             |
| `--capabilities` | None     | Comma-separated `llms`, `api-catalog`, `ai-catalog`, `mcp`, `skills` |
| `--json`         | `false`  | Print a JSON report with `schemaVersion`, `url`, and `checks`        |

Each check reports `pass`, `warn`, `fail`, or `skip` with a reason.
The command exits with code `1` when any check fails. Warnings and skipped features allow code `0`.
Each request permits five redirects, ten seconds, and two MiB of response data.

If [Cloudflare](https://cloudflare.com) returns a challenge, inspect the site's crawler access rules.
The audit uses an ordinary HTTP client. It cannot prove that a named crawler can access every page.
Inspect crawler-specific rules in `robots.txt` separately. The sitemap check does not crawl child sitemaps or all listed pages.

### status

Show indexing and sync progress.

```bash
npx nuxt-ai-ready status
npx nuxt-ai-ready status --url https://mysite.com
```

**Options:**

| Option  | Alias | Default                 | Description       |
| ------- | ----- | ----------------------- | ----------------- |
| `--url` | `-u`  | `http://localhost:3000` | Site URL          |
| `--cwd` |       | `.`                     | Working directory |

**Example output, shortened:**

```text
AI Ready Status
Total pages: 50
Indexed: 45
Pending: 5
```

### poll

Index pending pages. `--all` uses the server’s batch size, capped at 50 pages, with a timeout check.
It does not drain the whole index in one request. If pages remain, run it again. This command does not mark healthy indexed pages pending because they are old.

```bash
# Index up to 10 pages (default)
npx nuxt-ai-ready poll

# Index up to 50 pages
npx nuxt-ai-ready poll --limit 50

# Use the server batch size, capped at 50 pages
npx nuxt-ai-ready poll --all
```

**Options:**

| Option    | Alias | Default                 | Description                                    |
| --------- | ----- | ----------------------- | ---------------------------------------------- |
| `--url`   | `-u`  | `http://localhost:3000` | Site URL                                       |
| `--limit` | `-l`  | `10`                    | Max pages to process                           |
| `--all`   | `-a`  | `false`                 | Use the server batch size with a timeout check |
| `--cwd`   |       | `.`                     | Working directory                              |

**Example output, shortened:**

```text
Triggering poll at http://localhost:3000...
Indexed: 10 pages
Remaining: 25
Duration: 1234ms
```

### restore

Restore the prerendered dump. By default, this deletes existing stored pages before importing the dump.
Use `--no-clear` to merge instead. The `cleared` response is a boolean, not a deleted-page count.

```bash
# Restore and clear existing pages
npx nuxt-ai-ready restore

# Restore without clearing (merge)
npx nuxt-ai-ready restore --no-clear
```

**Options:**

| Option    | Alias | Default                 | Description                |
| --------- | ----- | ----------------------- | -------------------------- |
| `--url`   | `-u`  | `http://localhost:3000` | Site URL                   |
| `--clear` |       | `true`                  | Clear existing pages first |
| `--cwd`   |       | `.`                     | Working directory          |

**Example output, shortened:**

```text
Restoring database at http://localhost:3000...
Restored: 50 pages
Cleared: true existing pages
```

### prune

Remove stale routes that are no longer in the sitemap.

```bash
# Preview what would be pruned (dry run)
npx nuxt-ai-ready prune --dry

# Prune routes older than 7 days
npx nuxt-ai-ready prune --ttl 604800

# Preview with custom TTL
npx nuxt-ai-ready prune --dry --ttl 86400
```

**Options:**

| Option  | Alias | Default                 | Description                            |
| ------- | ----- | ----------------------- | -------------------------------------- |
| `--url` | `-u`  | `http://localhost:3000` | Site URL                               |
| `--dry` | `-d`  | `false`                 | Preview without deleting               |
| `--ttl` |       | `pruneTtl` config       | Prune routes older than this (seconds) |
| `--cwd` |       | `.`                     | Working directory                      |

**Example output (dry run):**

```text
Previewing stale routes at http://localhost:3000...
Would prune: 5 routes
  • /old-page-1
  • /old-page-2
  • /removed-feature
  ... and 2 more
```

### reindex

Reindex a single route. Useful right after a CMS publish, without a full poll cycle.

```bash
# Reindex one route
npx nuxt-ai-ready reindex /about

# Skip indexing when the page is still fresh
npx nuxt-ai-ready reindex /about --no-force

# Reindex on a deployed site
npx nuxt-ai-ready reindex /about --url https://mysite.com
```

**Options:**

| Option    | Alias | Default                 | Description                             |
| --------- | ----- | ----------------------- | --------------------------------------- |
| `route`   |       | -                       | Route to reindex. Required              |
| `--url`   | `-u`  | `http://localhost:3000` | Site URL                                |
| `--force` |       | `true`                  | Index even when the page is still fresh |
| `--cwd`   |       | `.`                     | Working directory                       |

**Example output, shortened:**

```text
Reindexing /about at http://localhost:3000...
✔ Indexed: /about
Content changed: yes
```

## Workflow Examples

### Development Workflow

Dev mode can verify command connectivity and authentication, but query helpers return empty indexed data.
Test actual indexing against a built server.

```bash
# Start dev server
nuxi dev

# In another terminal, check status
npx nuxt-ai-ready status

# Manually trigger indexing
npx nuxt-ai-ready poll --all
```

### Production Deployment

```bash
# After deployment, process pending pages
npx nuxt-ai-ready poll --all --url https://mysite.com

# Clean up old routes weekly
npx nuxt-ai-ready prune --ttl 604800 --url https://mysite.com
```

### CI/CD Integration

Give the indexing step the same `NUXT_APP_SECRET` as the deployed server.
The CLI can derive its token without a build-time cache:

```yaml [.github/workflows/deploy.yml]
- name: Index pages
  env:
    NUXT_APP_SECRET: ${{ secrets.NUXT_APP_SECRET }}
    SITE_URL: ${{ vars.SITE_URL }}
  run: npx nuxt-ai-ready poll --all --url "$SITE_URL"
```

## Troubleshooting

### "No secret found" Error

Set `NUXT_APP_SECRET` for a deployed site. For local development, enable runtime sync and run module setup:

```bash
nuxi dev
# or
nuxi build
```

### Connection Refused

Ensure the dev server or production site is running and accessible at the specified URL:

```bash
# Check if server is running
curl http://localhost:3000/__ai-ready/status
```

### Wrong Working Directory

If running from a different directory, specify `--cwd`:

```bash
npx nuxt-ai-ready status --cwd /path/to/project
```

## Sitemap

See the full [sitemap](https://nuxtseo.com/sitemap.md) for all pages.
