> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add search with the Algolia Wizard

> Use the Algolia Wizard to index your app's data and add a search UI with a guided, AI-assisted setup.

This is a **beta feature** according to [Algolia's Terms of Service ("Beta Services")](https://www.algolia.com/policies/terms/).

The wizard identifies data to index,
generates an ingestion script to send that data to Algolia,
and adds a basic search UI.
The wizard asks you to approve commands that can change your project, install software, or send records (A record is a searchable object in an Algolia index. Each record consists of named attributes.) to Algolia.

## When to use the Algolia Wizard

Use the wizard to go from an app with no search to searching your own data,
typically in less than 10 minutes.
The wizard indexes one of your app's data types and adds a search UI you can test with your records.
The generated code is yours to review, change, and extend.

The wizard gives you a starting point.
To extend the integration:

* **Keep the index up to date.**
  The generated ingestion script runs on demand, so schedule it, extend it to send only changed records, or
  replace it with a [connector](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/connectors) that Algolia runs for you.
* **Build on the generated search UI.**
  The wizard uses [InstantSearch](https://www.algolia.com/doc/ui-libraries.md), so you can add widgets such as filters, pagination, and highlighting from the same library.
* **Use your own coding agent for later changes.**
  Connect your coding agent to [DevEx MCP](https://www.algolia.com/doc/guides/model-context-protocol/devex-mcp.md) to help it generate API client code that matches your project.

## Before you begin

Before you run the wizard, make sure you have:

* An existing app in a Git repository with at least one commit.
  Start from a clean working tree, with no uncommitted changes or untracked files,
  so you can identify and undo the wizard's changes.
  The wizard changes files in your project directory but doesn't create a branch, commit, or push.
* Node.js 24 or later.
* An Algolia account with an active application and permission to manage [API keys](https://www.algolia.com/doc/guides/security/api-keys) for that application.
* If you want to index existing data, you need a data source such as a file, database, or API.

> [!NOTE]
>
> Imported JSON files must contain an array of objects. Imported CSV and TSV files must include a header row.

## Run the wizard

In the root directory of your app, run:

```sh Command line icon=square-terminal theme={"system"}
npx @algolia/wizard@latest
```

> [!TIP]
>
> For the best layout, use a terminal with at least 100 columns by 30 rows.
> Press `Tab` to show or hide the log panel and `Esc` to exit.

**1. Sign in to Algolia**

In the browser window the wizard opens, sign in to Algolia or create an account.

**2. Choose an application**

Choose the Algolia application to work in.

If a `.env` or `.env.local` file in your project defines a variable ending in `ALGOLIA_APP_ID` or `ALGOLIA_APPLICATION_ID`,
the wizard marks that application as detected.

**3. Consent to AI-generated changes**

The wizard asks for this consent once per project and saves your answer.
To reset consent, run the wizard with `--reset-on-run`.
This also deletes this project's saved session and removes the Algolia Wizard API keys stored for all projects.

During the run, the wizard asks you to approve commands that can change your project, install software, or send data, unless an earlier approval already covers the action.
It shows the full command, its working directory, and a brief explanation, and you approve or reject it.

Commands that only read, check, test, or build your project run without a prompt.

An approval also covers later commands that take the same action with the same side effects.
Installing a different package requires a new approval.
The wizard always asks for approval before running scripts in `.algolia-wizard/`.

**4. Confirm your app's languages**

Confirm the languages the wizard detected, or list them yourself.

**5. Choose the type of data to index**

Select the type of data to index, or name a different type for the wizard to find.

The wizard refers to types of app data as *entities*.
For example, a `Product` entity might have `name`, `description`, `category`, and `price` properties.
Each item becomes a record in the index.

**6. Choose an index**

Select an existing Algolia index or create one.

> [!WARNING]
>
> Use a non-production Algolia index while evaluating the wizard.
> If you approve the wizard's ingestion step, it sends records to the selected index.

**7. Choose data to index**

Choose existing project data, a JSON, CSV, or TSV file, or generated sample data.

**8. Review and run the ingestion script**

Review the ingestion script, then approve the exact command that runs it.

If the script changes after approval, the wizard asks for approval again.
Running the script sends records to the selected index, and the wizard reports how many records it indexed.

**9. Confirm your frontend framework**

Confirm the frontend framework the wizard detected, or select one from the list.

**10. Check the search UI for errors**

Review the wizard's type-check and lint results for the generated search UI.
If your project lacks packages needed for these checks,
the wizard offers to install them.

When the workflow finishes, the wizard summarizes what it did, suggests next steps, and asks you to review the generated code.

If the wizard stops, restart it in the same directory.
Choose whether to resume the session or start a new one.

## Review the generated changes

Before committing, review the files the wizard created or changed.
Use `git status` to find new and modified files and
`git diff` to inspect changes to tracked files.
Open new files separately to review their contents.

The generated search UI enables Insights and sends view and click events.
It sends a conversion event only if your app already has a matching action, such as adding a result to a cart.
Otherwise, the generated code leaves a `TODO` comment in the search UI component where you can add one.
For more information, see [Click and conversion events](https://www.algolia.com/doc/guides/sending-events).

### Inspect project files

* Review the ingestion script in `.algolia-wizard/` at the root of your project.
  The wizard doesn't add this directory to `.gitignore`, so you can review and commit its contents.
* Check any imported data copied into `.algolia-wizard/` or generated sample data written to `.algolia-wizard/data/`.
  If the script uses sample data, find the `TODO` comment in the ingestion script that marks where to replace it with your real data source.
* Review changes to the file that lists the packages your project uses,
  such as `package.json`, `requirements.txt`, `Gemfile`, `go.mod`, or `composer.json`.
  The wizard adds the Algolia client library for your language and uses your project's package manager to install the packages needed for InstantSearch.
* Confirm that the wizard added the search UI in an appropriate location and followed your project's conventions.
  It creates a component and adds the code to display it in an existing file.
  If your frontend has no `package.json`,
  it adds scripts to your HTML or template instead.
  These load InstantSearch.js and the Algolia client from a content delivery network (CDN).
* If your app already has a search box for the same content,
  the wizard replaces it with the Algolia search UI and removes the code it replaced.
  It keeps filters, navigation, and search controls for other content.

### Check API keys and credentials

The wizard creates or reuses two API keys, both restricted to the selected index:
a write key for the ingestion script and a search-only key for the UI.
The write key can add and delete records and change index settings, so treat it as a private credential.

Find them on the [**API Keys** page of the Algolia dashboard](https://dashboard.algolia.com/account/api-keys),
as "Algolia Wizard write key for INDEX\_NAME index" and "Algolia Wizard search-only key for INDEX\_NAME index".

Review any credentials written to project files before committing.

* If the ingestion script loads credentials from an existing `.env` file,
  confirm that `ALGOLIA_APP_ID` and `ALGOLIA_INDEX_NAME` match the selected application and index.
  The wizard restricts `ALGOLIA_WRITE_KEY` to that index, but the key can still add and delete records and change index settings.
  Confirm that Git doesn't track the `.env` file and that `.gitignore` excludes it.
* Confirm that the search UI configuration file exports only `ALGOLIA_APP_ID`, `ALGOLIA_SEARCH_API_KEY`, and `ALGOLIA_INDEX_NAME`.
  If your UI loads scripts from a CDN, check the values that the configuration script sets on the browser's `window` object.
* Confirm that the search-only key grants search access only to the intended index.
* Check the indexed records for personal information, private fields, and other data you don't intend to make searchable.

> [!WARNING]
>
> Only the search-only API key should appear in client-side code.
> Never commit or expose `ALGOLIA_WRITE_KEY`, an Algolia Admin API key, a database password, or other private credentials.

### Test your search

1. Confirm that the ingestion script used the intended data source and that the selected index contains the expected number of records.
2. Check that the attributes displayed in the search UI exist in the indexed records.
3. Start your app using your usual local development workflow.
4. Search for terms that match your indexed content. Check that the results are relevant and that the search UI works as expected.

After reviewing the generated files and credentials,
commit the changes.

## Update your index

To refresh the index after changing the source data,
run the ingestion command that the wizard showed after the ingestion step.
The script reads `ALGOLIA_APP_ID`, `ALGOLIA_WRITE_KEY`, and `ALGOLIA_INDEX_NAME` from the environment.
If the wizard wrote them to a `.env` file, the script loads them from there.
Otherwise, set them before running the command.

## Command-line options

Add these options after `npx @algolia/wizard@latest` to change how the wizard runs.
For example, use `npx @algolia/wizard@latest --help` to list the available options.

| Option | Description |
| - | - |
| `--reset-on-run` | Delete this project's saved wizard state, including AI consent and any saved session. It also removes Algolia Wizard API keys stored in your keychain for all projects. Later runs create new keys. |
| `-h`, `--help` | Show the options and exit. |

## Troubleshoot the wizard

Use the error messages and logs to investigate problems with a wizard run.

### Error messages

| Message | What to do |
| - | - |
| "You have loaded an old version of the Wizard." | Run `npx @algolia/wizard@latest`. |
| "This Algolia account has no applications." | Create an application in the Algolia dashboard or with `npx @algolia/cli@latest application create`, then rerun the wizard. |
| "None of the applications on this Algolia account are usable." | Each application is paused or your account lacks permission to manage its API keys. Activate an application or ask an administrator for permission to manage its API keys. |
| "implement requires a git repository with at least one commit." | In your app's root directory, initialize a Git repository, stage the project files, and create a commit. Then rerun the wizard. |
| "Records were not indexed" | You declined the command, or the script failed or timed out. The wizard shows the command and working directory. Fix the cause and run the command yourself. The script needs `ALGOLIA_APP_ID`, `ALGOLIA_WRITE_KEY`, and `ALGOLIA_INDEX_NAME` in its environment. |
| "Could not provision a search-only Algolia API key" | The search UI configuration file contains the placeholder `<your-algolia-search-only-api-key>` and a `TODO` comment. Create a search-only API key in the Algolia dashboard and replace the placeholder. |
| "Unable to validate the implementation after 3 attempts" | Review the reported issue and fix it. To undo the wizard's changes, restore modified tracked files and review any new files before removing them. |
| "Recommended size is 100x30" | Enlarge the terminal window. The wizard works in a smaller terminal with a compact layout. |
| "The AI service had trouble responding." | Run the wizard again. It offers to resume the interrupted session. |

### Wizard state and logs

The wizard stores its progress, settings, and logs outside your project, in `~/.algolia/PROJECT_SLUG/`.
Here, `PROJECT_SLUG` is your project's full path with path separators replaced by hyphens.
The directory contains:

* `config.json`: your AI consent and a record of completed runs.
* `state-default.json`: the current session, if a run stopped before it finished. The wizard offers to resume it the next time you run it in the same directory with the same application.
* `wizard.log`: a detailed log of the run.

Set `WIZARD_LOG` to change the log path.
Set `LOG_LEVEL` to change the amount of detail in the log.
Set `WIZARD_HOME` to store wizard data outside `~/.algolia`.

## Data use and privacy

The wizard sends project content for AI processing and sends analytics and diagnostic data to Algolia.

### AI processing

To analyze your project and generate code, the wizard sends project content to Anthropic Claude models through a server hosted by Algolia.
This content can include source code, configuration, file paths, directory listings, search results, command outputs, entity names, and entity attributes.

### Environment variables and command output

The wizard masks the values in files named `.env` or `.env.*` before sending their content to an Anthropic Claude model.
It still sends variable names, comments, and other non-secret text.
It also masks the Algolia API write key in command output.

### Analytics and telemetry

The wizard sends usage analytics and diagnostic data to Algolia,
as described in the [privacy policy](https://www.algolia.com/policies/privacy/).
Besides standard usage data, this includes file paths in your project, the names of the data types and properties you select, and model usage for each step.
The analytics and diagnostic data doesn't include prompts, file contents, or records.