> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/contextual-cli.md).

# AI Search CLI Reference

Manage Search Profiles, inspect and maintain indexes, and search tenant records with the Contextual CLI.

Use the Contextual CLI (`ctxl`) to manage Search Profiles, inspect and maintain their indexes, and search their indexed records. This page covers the AI Search commands and the profile payload needed to use them. See [Search Concepts and Configuration](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md) for the configuration choices.

{% hint style="info" %}
This documentation assumes you are running Contextual CLI 0.17.0 or later. Check your installed version with `ctxl --version`.
{% endhint %}

## Before You Start

You need a tenant with AI Search enabled and permissions to manage Search Profiles and read the source Object Type. If AI Search is unavailable or access is denied, [Contact Contextual support](mailto:help@contextual.io) and include the tenant ID.

Follow [Install and Sign In](#install-and-sign-in) to prepare a CLI configuration for that tenant. Replace `<config-id>` in each command with the configuration ID. If you omit `--config-id`, the CLI uses its current configuration.

The examples use profile ID `equipment-help` and named Search Index ID `default`. These IDs are examples; the create payload below defines them. Replace `<object-type-id>` with the ID of the Native Object Type containing your source records.

{% hint style="warning" %}
Creating or changing a profile can start indexing or reprocessing source records. Repair and rebuild commands request that work directly. Deleting a profile removes the configuration used by searches that select it. Check the target tenant and the intended change before running a write command.
{% endhint %}

## Install and Sign In

Install or update the Contextual CLI, then check that the AI Search commands are available:

```sh
npm install -g @contextual-io/cli
ctxl --version
ctxl aisearch --help
```

The `npm install` command adds or updates the CLI in your global npm installation. Make sure `ctxl` is on `PATH` in the terminal where you will run it.

Add a configuration for your tenant, select it, and sign in. Replace `<tenant-id>` with your tenant ID:

```sh
ctxl config add my-config --tenant-id <tenant-id>
ctxl config use my-config
ctxl config login
ctxl config current --json
```

The `config add` command saves a local CLI configuration. The `config use` command changes the default configuration on your machine. Follow the CLI sign-in prompt, then confirm that `config current --json` reports the intended tenant.

To reuse an existing configuration, find its ID with `ctxl config list`, skip `config add`, and use that ID instead of `my-config`. Pass the ID as `--config-id` in the AI Search commands below. If you use a coding agent, it must run commands in the environment where this CLI installation and signed-in configuration are available.

## Understand the AI Search Commands

AI Search uses the dedicated `ctxl aisearch` command group. `ctxl ais` is its shorter alias.

| Command                                                                  | Purpose                                                                                  |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `ctxl aisearch profiles list`                                            | List profiles in the tenant, optionally restricted to a source Object Type.              |
| `ctxl aisearch profiles get <profile-id>`                                | Read a profile's configuration and metadata.                                             |
| `ctxl aisearch profiles add`                                             | Create profiles from a JSONL file. `create` and `import` are aliases for this operation. |
| `ctxl aisearch profiles replace <profile-id>`                            | Replace a profile's complete configuration from a JSON file.                             |
| `ctxl aisearch profiles delete <profile-id>`                             | Delete a profile.                                                                        |
| `ctxl aisearch profiles progress <profile-id>`                           | Read reported build and repair progress.                                                 |
| `ctxl aisearch profiles columns <profile-id>`                            | Inspect stored projection columns. `schema` is an alias.                                 |
| `ctxl aisearch profiles repair <profile-id>`                             | Request an index repair that reuses unchanged embeddings.                                |
| `ctxl aisearch profiles stoprepair <profile-id> --repair-id <repair-id>` | Stop a repair that is queuing records.                                                   |
| `ctxl aisearch profiles rebuild <profile-id>`                            | Request a rebuild into a new index generation.                                           |
| `ctxl aisearch query "<query>"`                                          | Search a profile's indexed records, returning source records or matching text chunks.    |

A Search Profile's `source.objectType` identifies the records to index. Its `indexes` array holds named Search Indexes: query presets that share those indexed records. Manage these presets within the profile payload; select one with `--index` when searching.

## Inspect Search Profiles

List the tenant's profiles:

```bash
ctxl aisearch profiles list \
  --config-id <config-id> \
  --pretty
```

To list only profiles for a source Object Type, add `--type <object-type-id>`. The list command supports pagination with `--page-size` and `--page-token`. Read the returned `nextPageToken` to request another page.

Read one profile:

```bash
ctxl aisearch profiles get equipment-help \
  --config-id <config-id> \
  --pretty
```

## Inspect Index Progress and Columns

Check build and repair progress after creating a profile or requesting maintenance:

```bash
ctxl aisearch profiles progress equipment-help \
  --config-id <config-id> \
  --pretty
```

Each call returns the reported progress at that time. Run it again to check for updates. Use a query against a known source record to verify that the expected content is searchable; see [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md).

Inspect the stored projection columns for the current index and any index being built:

```bash
ctxl aisearch profiles columns equipment-help \
  --config-id <config-id> \
  --pretty
```

Named Search Indexes share these columns. Use the stored types when reviewing projection changes; see [Projection Types and Stored Columns](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#projection-types-and-stored-columns).

## Create a Search Profile

Create the source Object Type and records first. The example below expects fields named `title`, `category`, `symptom`, and `resolution`, as used in the [AI Search Quickstart for Coding Agents](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/quickstart.md#prepare-the-example-records).

`profiles add` reads JSONL: one complete profile object per line. Save this single-line object as `equipment-help.jsonl`, replacing `<object-type-id>`:

```json
{"id":"equipment-help","name":"Equipment Help","source":{"kind":"native-object","objectType":"<object-type-id>"},"template":{"language":"handlebars","body":"Title: {{title}}\nCategory: {{category}}\n{{#if symptom}}Symptom: {{symptom}}{{/if}}\nResolution: {{resolution}}"},"chunking":{"splitterId":"plain-text-window","size":1600,"overlap":10,"preserveBoundaries":true},"embedding":{"model":"voyage-4","dimensions":1024},"projections":[],"indexes":[{"id":"default","name":"Default","mode":"hybrid","topK":10,"oneResultPerDocument":true,"filters":[],"rerank":{"enabled":false,"scope":"document"}}]}
```

The `chunking.overlap` value is a percentage: `"overlap": 10` means 10% overlap.

The payload indexes all records in the source Object Type, uses no header or projections, and creates a named hybrid Search Index with reranking disabled. Adapt the template to your record fields and confirm that the embedding model is available in the target tenant.

Run:

```bash
ctxl aisearch profiles add \
  --input-file equipment-help.jsonl \
  --config-id <config-id> \
  --pretty
```

Read the profile with `profiles get` after creating it. Check indexing progress with [`profiles progress`](#inspect-index-progress-and-columns) or in the admin console before evaluating results; a successful create response does not mean indexing has finished. See [Keep Search Up to Date](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md).

## Update a Search Profile

`profiles replace` sends the complete profile configuration. Start from the latest profile so that your file retains the source, template, chunking, embedding, projections, and named indexes you intend to keep.

Save the current profile as a JSON file:

```bash
ctxl aisearch profiles get equipment-help \
  --config-id <config-id> \
  --pretty > equipment-help.json
```

Edit the configuration in that file. For example, change the `topK` value of the `default` named index. Keep `_metaData.hash` unchanged: `replace` uses it to reject the update if someone has changed the profile since you fetched it. If that check fails, fetch the profile again and apply your edits to the newer configuration.

Run:

```bash
ctxl aisearch profiles replace equipment-help \
  --input-file equipment-help.json \
  --config-id <config-id> \
  --pretty
```

Read the profile again to verify the saved configuration. Updating a named index's retrieval settings does not change stored embeddings. Changes to source selection, templates, chunking, embeddings, or projections can require reprocessing or rebuilding; see [Create and Manage Search Profiles](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/manage-search-profiles.md#change-an-existing-profile) before making those changes.

To request a full rebuild as part of a replacement, add `--rebuild-mode full`. Use this when you intend to re-embed the indexed text. To rebuild without replacing the configuration, use [`profiles rebuild`](#rebuild-an-index).

## Repair or Rebuild an Index

### Repair an Index

Use repair when records appear missing or stale and the profile configuration is appropriate. It reuses unchanged embeddings:

```bash
ctxl aisearch profiles repair equipment-help \
  --config-id <config-id> \
  --pretty
```

Keep the returned `reconciliationId` if you may need to stop the repair. Use `profiles progress` to inspect the repair after the request is accepted.

### Stop a Repair

To stop a repair that is queuing records, pass its `reconciliationId` as `--repair-id`. Get that ID from the `repair` response or `profiles progress`:

```bash
ctxl aisearch profiles stoprepair equipment-help \
  --repair-id <repair-id> \
  --config-id <config-id>
```

Use `profiles progress` to check the repair after sending the stop request.

### Rebuild an Index

A rebuild creates a new index generation and embeds the matching source records again. To rebuild using the profile's saved configuration, run:

```bash
ctxl aisearch profiles rebuild equipment-help \
  --config-id <config-id> \
  --pretty
```

The request returns before the background work finishes. Use `profiles progress` to check progress, then rerun a known query. See [Repair and Rebuild](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/keep-search-up-to-date.md#repair-and-rebuild) for the effect of each operation.

## Run a Search

Return current source records:

```bash
ctxl aisearch query "The pump is running but barely moving water." \
  --profile equipment-help \
  --index default \
  --config-id <config-id> \
  --pretty
```

Return matching text chunks and search evidence instead:

```bash
ctxl aisearch query "The pump is running but barely moving water." \
  --profile equipment-help \
  --index default \
  --chunks \
  --config-id <config-id> \
  --pretty
```

| Query Option              | Effect                                                                                              |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| `--profile <profile-id>`  | Required. Selects the Search Profile.                                                               |
| `--index <index-id>`      | Selects a named Search Index from that profile.                                                     |
| `--type <object-type-id>` | Supplies the source Object Type ID. If omitted, the CLI reads it from the profile.                  |
| `--chunks`                | Returns indexed text, source references, projections, and scores instead of current source records. |
| `--top-k <1–100>`         | Overrides the selected index's retrieval candidate limit. The returned count can be lower.          |

Pass `--index` explicitly to apply a named index's settings and static filters. Omitting it uses semantic retrieval, Top K 10, no document grouping, no preset filters, and no reranking; it does not select an index named `default`. `--top-k` still overrides the candidate limit.

The CLI sends the query through the Tenant Native Object API. Results contain an `items` array of current records or evidence hits; the CLI does not generate an answer from them. See [Query and Use Results](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md#read-search-evidence) to interpret the response and preserve source references.

## Delete a Search Profile

Confirm that searches no longer depend on the profile, then run:

```bash
ctxl aisearch profiles delete equipment-help \
  --config-id <config-id>
```

The command sends the delete request immediately; it does not ask for confirmation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/contextual-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
