---
title: "CLI"
description: "Command-line interface for managing runtime sync."
canonical_url: "https://nuxtseo.com/docs/ai-ready/guides/cli"
last_updated: "2026-09-25T17:50:04.923Z"
---

Use the `nuxt-ai-ready` CLI to inspect stored pages, index pending routes, or reindex one changed page.
Enable `runtimeSync` or `cron` in the running site before calling these commands.

## 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 CLI reads `node_modules/.cache/nuxt/ai-ready/secret` relative to `--cwd`.
Module setup writes this file when you configure a secret, or when runtime sync generates one.

For a deployed site, the cached secret must match the server. Set `NUXT_AI_READY_RUNTIME_SYNC_SECRET` during its build/setup.
Use that same value when preparing the local project used by the CLI. Changing an environment variable for the CLI alone does not override the cache file.

::note
Enable runtime sync, then run `nuxi dev` or `nuxi build` to write the secret cache.
A generated local secret will not match a different build’s generated secret.
::

## Commands

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

Run this after the same job builds and deploys the site with a stable `NUXT_AI_READY_RUNTIME_SYNC_SECRET`.
That build writes the matching secret cache used by the CLI:

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

## Troubleshooting

### "No secret found" Error

Enable runtime sync or configure a secret. Then run module setup from the project selected by `--cwd`:

```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](/sitemap.md) for all pages.