Skip to main content
This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).
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 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 that Algolia runs for you.
  • Build on the generated search UI. The wizard uses InstantSearch, 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 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 for that application.
  • If you want to index existing data, you need a data source such as a file, database, or API.
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:
Command line
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.
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.

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

​
Troubleshoot the wizard

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

​
Error messages

​
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. 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.
Last modified on October 23, 2026