CLI

Last updated Oct 14, 2026Harlan Wilton

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:

npx nuxt-ai-ready <command>

Or add a script to your package.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:

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.

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 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.

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:

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.

# 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:

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.

# 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:

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

prune

Remove stale routes that are no longer in the sitemap.

# 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):

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.

# 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:

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.

# 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

# 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:

.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:

nuxi dev
# or
nuxi build

Connection Refused

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

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

Wrong Working Directory

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

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

Was this page helpful?

Edit page Report an issue

Runtime Sync

Configuration

On this page

Was this page helpful?

Edit page Report an issue

CLI

Installation

Authentication

Commands

audit

status

poll

restore

prune

reindex

Workflow Examples

Development Workflow

Production Deployment

CI/CD Integration

Troubleshooting

"No secret found" Error

Connection Refused

Wrong Working Directory

Related