---
kind: wp-cli
area: tools-addons
tier: premium
summary: The wp kimaai command of KimaAI Pro, with every subcommand, its options and an example.
---

# WP-CLI commands

KimaAI Pro adds the `wp kimaai` command to WP-CLI. `wp help kimaai <subcommand>` shows the same synopsis on a site. Each entry starts with the synopsis WP-CLI reads from the command; a subcommand without options in its synopsis takes none that WP-CLI checks.

Commands that answer with the chatbot or run evaluations send requests to the AI provider, which cost tokens.

## wp kimaai db status

- Tier: premium

Shows the version of KimaAI's database tables, the version the code expects and the migration steps still pending.

```sh
wp kimaai db status
```

## wp kimaai db migrate

- Tier: premium

Runs the migrator: the table schema and the queued migration steps, until none is pending.

```sh
wp kimaai db migrate [--one-step]
```

| Option         | Description                     |
| -------------- | ------------------------------- |
| `[--one-step]` | Run only the next pending step. |

Example:

```sh
wp kimaai db migrate
wp kimaai db migrate --one-step
```

## wp kimaai db scenario

- Tier: premium

Switches a test scenario of a migration class on or off, for testing migrations. Only migrations that read scenarios use them.

Test-only: registered only on KimaAI's own test sites, so a site with KimaAI Pro installed does not have it.

```sh
wp kimaai db scenario --class=<fqcn> [--scenario=<name>] [--enable] [--disable] [--reset]
```

| Option                | Description                                       |
| --------------------- | ------------------------------------------------- |
| `--class=<fqcn>`      | The migration class, fully qualified.             |
| `[--scenario=<name>]` | The scenario; required unless `--reset` is given. |
| `[--enable]`          | Switch the scenario on (the default).             |
| `[--disable]`         | Switch the scenario off.                          |
| `[--reset]`           | Remove every scenario of the class.               |

Example:

```sh
wp kimaai db scenario --class="KimaAI\Database\Migrations\Version2026012702" --reset
```

## wp kimaai db run

- Tier: premium

Runs one migration step now, without waiting for WP-Cron, optionally with a scenario switched on first.

Test-only: registered only on KimaAI's own test sites, so a site with KimaAI Pro installed does not have it.

```sh
wp kimaai db run --version=<int> [--scenario=<name>] [--reset-scenarios]
```

| Option                | Description                                                     |
| --------------------- | --------------------------------------------------------------- |
| `--version=<int>`     | The migration's version key, as `Migrator::updates()` lists it. |
| `[--scenario=<name>]` | A scenario to switch on for the migration's class first.        |
| `[--reset-scenarios]` | Remove the class's scenarios first.                             |

Example:

```sh
wp kimaai db run --version=2026111303
```

## wp kimaai eval run

- Tier: premium

Runs evaluation cases through the chatbot and reports which pass; the run is stored in the eval history. Each case is a chatbot request to the AI provider.

```sh
wp kimaai eval run [--file=<file>] [--stored] [--only=<category>] [--limit=<n>] [--lang=<lang>] [--judge] [--log=<file>]
```

| Option                | Description                                                         |
| --------------------- | ------------------------------------------------------------------- |
| `[--file=<file>]`     | A JSONL file with the cases.                                        |
| `[--stored]`          | Use the eval cases of the admin instead of a file.                  |
| `[--only=<category>]` | Only cases of this category.                                        |
| `[--limit=<n>]`       | Only the first n cases.                                             |
| `[--lang=<lang>]`     | The language sent with each request.                                |
| `[--judge]`           | Also grade the answers with an AI judge against the expected facts. |
| `[--log=<file>]`      | Append a JSONL line per case to this file.                          |

Example:

```sh
wp kimaai eval run --stored --only=shipping --limit=10
```

## wp kimaai eval history

- Tier: premium

Shows the stored eval runs.

```sh
wp kimaai eval history [--limit=<n>]
```

| Option          | Description                     |
| --------------- | ------------------------------- |
| `[--limit=<n>]` | The last n runs; 10 by default. |

Example:

```sh
wp kimaai eval history --limit=5
```

## wp kimaai gaps report

- Tier: premium

Builds the knowledge gap report from recent conversations: the questions visitors ask, in clusters, ranked by negative feedback and volume.

```sh
wp kimaai gaps report [--days=<n>] [--min-cluster=<n>] [--format=<format>]
```

| Option                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `[--days=<n>]`        | Days to look back; 30 by default.                              |
| `[--min-cluster=<n>]` | Only clusters with at least this many questions; 2 by default. |
| `[--format=<format>]` | `table` (the default) or `json`.                               |

Example:

```sh
wp kimaai gaps report --days=14 --format=json
```

## wp kimaai run

- Tier: premium

Runs one generation of the AI service from the command line: a chat answer, an image or an embedding, with an AI environment of Connections.

```sh
wp kimaai run <type> [<input>...] [--provider=<env>] [--model=<model>] [--payload=<json>] [--file=<path>] [--param=<key-value>] [--<field>=<value>] [--raw] [--pretty]
```

| Option                  | Description                                                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `<type>`                | `chat`, `image` or `embed`.                                                                                                     |
| `[<input>...]`          | The prompt for chat and image, or the text to embed.                                                                            |
| `[--provider=<env>]`    | The AI environment: provider, slug or ID. Chat uses the first AI environment, embed the embedding environment; image needs one. |
| `[--model=<model>]`     | The model.                                                                                                                      |
| `[--payload=<json>]`    | A JSON object merged into the request.                                                                                          |
| `[--file=<path>]`       | A JSON file merged into the request.                                                                                            |
| `[--param=<key-value>]` | A value as `key=value`, repeatable; values are read as JSON, booleans, numbers or strings.                                      |
| `[--<field>=<value>]`   | Another option of the request, such as `--temperature` or `--dimensions`.                                                       |
| `[--raw]`               | Print the whole response as JSON.                                                                                               |
| `[--pretty]`            | Pretty-print the JSON.                                                                                                          |

Example:

```sh
wp kimaai run chat "Say hello" --provider=default
wp kimaai run embed "Text to vectorize" --provider=openai --model=text-embedding-3-small --raw
```

## wp kimaai chat

- Tier: premium

Chats with the chatbot as a visitor would, through the same pipeline as the chat route (settings, knowledge, tools). `wp kimaai chat history` prints a session, `wp kimaai chat clear-history` starts a new one.

```sh
wp kimaai chat [<prompt>...] [--session-id=<id>] [--post-id=<id>] [--lang=<locale>] [--provider=<provider>] [--model=<model>] [--command=<json>] [--force-tool=<tool_name>] [--parallel-tool-calls] [--callback=<name>] [--callback-args=<json>] [--stream] [--raw] [--pretty]
```

| Option                       | Description                                                |
| ---------------------------- | ---------------------------------------------------------- |
| `[<prompt>...]`              | The message.                                               |
| `[--session-id=<id>]`        | A session to continue.                                     |
| `[--post-id=<id>]`           | The post the chat runs on.                                 |
| `[--lang=<locale>]`          | The language of the request.                               |
| `[--provider=<provider>]`    | Not supported here; `wp kimaai run chat` takes a provider. |
| `[--model=<model>]`          | Not supported here; `wp kimaai run chat` takes a model.    |
| `[--command=<json>]`         | A command as the chat route takes it.                      |
| `[--force-tool=<tool_name>]` | Make the model call this tool.                             |
| `[--parallel-tool-calls]`    | Allow parallel calls of forced tools.                      |
| `[--callback=<name>]`        | Run a registered chatbot command callback.                 |
| `[--callback-args=<json>]`   | The callback's arguments.                                  |
| `[--stream]`                 | Stream the answer.                                         |
| `[--raw]`                    | Print the answer as the chat route returns it.             |
| `[--pretty]`                 | Pretty-print the JSON.                                     |

Example:

```sh
wp kimaai chat "Hello"
wp kimaai chat "And the shipping costs?" --session-id=3f9c2a
wp kimaai chat history --session-id=3f9c2a --raw --pretty
```

## wp kimaai mcp token create

- Tier: premium

Issues a token for the MCP endpoint and prints it once. WP-CLI's global `--user` chooses the user the token acts as, who needs the `kimaai_mcp` capability; the first administrator otherwise.

```sh
wp kimaai mcp token create [--label=<label>] [--scopes=<scopes>]
```

| Option                | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `[--label=<label>]`   | A name for the token; `MCP token` by default.                                     |
| `[--scopes=<scopes>]` | Scopes, comma-separated: `read`, `read:raw`, `write`, `admin`; `read` by default. |

Example:

```sh
wp kimaai mcp token create --label="Claude Code" --scopes=read,write --user=editor-anna
```

## wp kimaai mcp token list

- Tier: premium

Lists the MCP tokens: ID, label, scopes, when each was created and last used, never the token itself.

```sh
wp kimaai mcp token list
```

## wp kimaai mcp token revoke

- Tier: premium

Revokes an MCP token.

```sh
wp kimaai mcp token revoke <id>
```

| Option | Description                                             |
| ------ | ------------------------------------------------------- |
| `<id>` | The token's ID, as `wp kimaai mcp token list` shows it. |

Example:

```sh
wp kimaai mcp token revoke 7d1e4c2a-90b3-4f6e-8a51-2c3d4e5f6a7b
```

## wp kimaai usage report

- Tier: premium

Shows the AI tokens the chatbot used per day and in the current month.

```sh
wp kimaai usage report [--days=<n>]
```

| Option         | Description                     |
| -------------- | ------------------------------- |
| `[--days=<n>]` | The last n days; 30 by default. |

Example:

```sh
wp kimaai usage report --days=7
```

## wp kimaai vectors sync

- Tier: premium

Syncs posts into the vector database in this process: splits them into chunks, embeds them and uploads them in batches, as the sync of the admin does.

```sh
wp kimaai vectors sync [--env=<env>] [--collection=<name>] [--namespace=<ns>] [--post_type=<types>] [--post_id=<id>] [--modified_after=<date>] [--limit=<n>] [--force] [--dry_run]
```

| Option                      | Description                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| `[--env=<env>]`             | The embedding environment; `default` by default.                               |
| `[--collection=<name>]`     | Another collection (index) than the environment's.                             |
| `[--namespace=<ns>]`        | Another namespace than the environment's (Pinecone).                           |
| `[--post_type=<types>]`     | Post types, comma-separated.                                                   |
| `[--post_id=<id>]`          | Only this post.                                                                |
| `[--modified_after=<date>]` | Only posts modified after this date (`Y-m-d` or anything `strtotime()` reads). |
| `[--limit=<n>]`             | At most this many posts; 50 by default.                                        |
| `[--force]`                 | Embed chunks again even when their content did not change.                     |
| `[--dry_run]`               | Do everything but the upload.                                                  |

Example:

```sh
wp kimaai vectors sync --post_type=post
wp kimaai vectors sync --post_id=123 --force
```

## wp kimaai vectors query

- Tier: premium

Searches the vector database with a text, which is embedded first, or with a vector.

```sh
wp kimaai vectors query [--collection=<name>] [--namespace=<ns>] [--text=<q>] [--vector=<json>] [--top=<k>] [--include_values] [--include_metadata] [--filter=<json>] [--env=<env>] [--format=<format>]
```

| Option                  | Description                                 |
| ----------------------- | ------------------------------------------- |
| `[--collection=<name>]` | Another collection than the environment's.  |
| `[--namespace=<ns>]`    | Another namespace than the environment's.   |
| `[--text=<q>]`          | The text to search for.                     |
| `[--vector=<json>]`     | A vector to search with instead.            |
| `[--top=<k>]`           | The number of hits.                         |
| `[--include_values]`    | Print the hits' vectors.                    |
| `[--include_metadata]`  | Print the hits' metadata.                   |
| `[--filter=<json>]`     | A metadata filter in the database's syntax. |
| `[--env=<env>]`         | The embedding environment.                  |
| `[--format=<format>]`   | `table`, `json`, `csv` or `yaml`.           |

Example:

```sh
wp kimaai vectors query --text="return policy" --top=3
```

## wp kimaai vectors fetch

- Tier: premium

Reads vectors from the vector database by ID.

```sh
wp kimaai vectors fetch --ids=<csv> [--collection=<name>] [--namespace=<ns>] [--format=<format>]
```

| Option                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `--ids=<csv>`           | The vectors' IDs, comma-separated.         |
| `[--collection=<name>]` | Another collection than the environment's. |
| `[--namespace=<ns>]`    | Another namespace than the environment's.  |
| `[--format=<format>]`   | The output format.                         |

Example:

```sh
wp kimaai vectors fetch --ids=post-123-chunk-0,post-123-chunk-1
```

## wp kimaai vectors delete

- Tier: premium

Deletes vectors in the vector database by ID, by filter or all of them, and KimaAI's rows of them. A filter clears the local rows of the whole target, so the next sync uploads all its posts again.

```sh
wp kimaai vectors delete [--ids=<csv>] [--filter=<json>] [--all] [--collection=<name>] [--namespace=<ns>]
```

| Option                  | Description                                 |
| ----------------------- | ------------------------------------------- |
| `[--ids=<csv>]`         | The vectors' IDs, comma-separated.          |
| `[--filter=<json>]`     | A metadata filter in the database's syntax. |
| `[--all]`               | Every vector of the target.                 |
| `[--collection=<name>]` | Another collection than the environment's.  |
| `[--namespace=<ns>]`    | Another namespace than the environment's.   |

Example:

```sh
wp kimaai vectors delete --ids=post-123-chunk-0
```

## wp kimaai vectors stats

- Tier: premium

Prints the vector database's statistics of a collection as JSON. It reads `--env` and `--collection`, which the command does not declare, so WP-CLI does not check them.

```sh
wp kimaai vectors stats
```

Example:

```sh
wp kimaai vectors stats --env=default
```

## wp kimaai vectors health

- Tier: premium

Checks an embedding environment (settings, embedding model, the collection and its dimension) and prints the report as JSON; fails when it is unhealthy. It reads `--env`, which the command does not declare.

```sh
wp kimaai vectors health
```

Example:

```sh
wp kimaai vectors health --env=default
```

## wp kimaai vectors freshness

- Tier: premium

Reports how fresh the index is: chunks per post type, posts in the index that no longer exist, chunks without access tokens, posts modified after their last embedding and posts without section links, with the command that fixes each.

```sh
wp kimaai vectors freshness
```

## wp kimaai vectors backfill-access

- Tier: premium

Stores the access tokens with chunks uploaded before the index kept them, without embedding again. Members-only posts keep their chunks only with "Include members-only content" on; chunks of posts nobody may see are removed.

```sh
wp kimaai vectors backfill-access
```

## wp kimaai vectors reconcile

- Tier: premium

Removes the chunks of posts that were deleted or unpublished from the index.

```sh
wp kimaai vectors reconcile
```

## wp kimaai vectors collections list

- Tier: premium

Lists the collections (indexes) of the vector database: name, dimension, status and host.

```sh
wp kimaai vectors collections list [--format=<format>]
```

| Option                | Description                                     |
| --------------------- | ----------------------------------------------- |
| `[--format=<format>]` | `table` (the default), `json`, `csv` or `yaml`. |

Example:

```sh
wp kimaai vectors collections list --format=json
```

## wp kimaai vectors collections create

- Tier: premium

Creates a collection (index) in the vector database. It reads `--env`, `--name`, `--dimension` and `--metric`, which the command does not declare; without them it uses the environment's collection, its dimension and `cosine`.

```sh
wp kimaai vectors collections create
```

Example:

```sh
wp kimaai vectors collections create --name=kimaai-docs --dimension=1536
```

## wp kimaai vectors collections delete

- Tier: premium

Deletes a collection (index) in the vector database, with every vector in it.

```sh
wp kimaai vectors collections delete --name=<name> [--env=<env>]
```

| Option          | Description                                      |
| --------------- | ------------------------------------------------ |
| `--name=<name>` | The collection.                                  |
| `[--env=<env>]` | The embedding environment; `default` by default. |

Example:

```sh
wp kimaai vectors collections delete --name=kimaai-docs
```

## wp kimaai vectors config get

- Tier: premium

Shows the configuration the REST routes and the commands use for an embedding environment, API keys masked.

```sh
wp kimaai vectors config get [--env=<env>] [--all] [--format=<format>]
```

| Option                | Description                                               |
| --------------------- | --------------------------------------------------------- |
| `[--env=<env>]`       | The environment: alias, slug or ID; `default` by default. |
| `[--all]`             | Every environment (ignores `--env`).                      |
| `[--format=<format>]` | `table` (the default), `json`, `csv` or `yaml`.           |

Example:

```sh
wp kimaai vectors config get --all --format=json
```

## wp kimaai vectors items list

- Tier: premium

Lists the chunks KimaAI stored, from its own table.

```sh
wp kimaai vectors items list [--namespace=<ns>] [--search=<term>] [--orderby=<field>] [--order=<asc|desc>] [--page=<n>] [--per-page=<n>] [--fields=<fields>] [--format=<table|csv|json>]
```

| Option                | Description                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | -------------------------------------- |
| `[--namespace=<ns>]`  | Only this namespace.                                                                                                                       |
| `[--search=<term>]`   | Search in the vector ID, namespace, model, heading path and post ID.                                                                       |
| `[--orderby=<field>]` | One of `post_id`, `chunk_index`, `namespace`, `status`, `model`, `dim`, `token_count`, `updated_at`, `vector_id`; `updated_at` by default. |
| `[--order=<asc        | desc>]`                                                                                                                                    | The direction; `desc` by default. |
| `[--page=<n>]`        | The page; 1 by default.                                                                                                                    |
| `[--per-page=<n>]`    | Items per page, 1 to 200; 100 by default.                                                                                                  |
| `[--fields=<fields>]` | The columns, comma-separated.                                                                                                              |
| `[--format=<table     | csv                                                                                                                                        | json>]`                           | The output format; `table` by default. |

Example:

```sh
wp kimaai vectors items list --search=post-123 --per-page=50
```

## wp kimaai vectors items get

- Tier: premium

Shows one stored chunk.

```sh
wp kimaai vectors items get --id=<vector_id> [--format=<table|json>]
```

| Option             | Description      |
| ------------------ | ---------------- | ------------------------------------- |
| `--id=<vector_id>` | The vector's ID. |
| `[--format=<table  | json>]`          | The output format; `json` by default. |

Example:

```sh
wp kimaai vectors items get --id=post-123-chunk-0
```

## wp kimaai vectors items delete

- Tier: premium

Deletes chunks in the vector database and in KimaAI's table.

```sh
wp kimaai vectors items delete --ids=<ids> [--collection=<name>] [--namespace=<ns>] [--local-only]
```

| Option                  | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| `--ids=<ids>`           | The vectors' IDs, comma-separated.                          |
| `[--collection=<name>]` | The collection, when the database needs it.                 |
| `[--namespace=<ns>]`    | The namespace (Pinecone).                                   |
| `[--local-only]`        | Delete only KimaAI's rows, not the vectors in the database. |

Example:

```sh
wp kimaai vectors items delete --ids=post-1-chunk-0,post-1-chunk-1 --local-only
```
