Meilisearch CLI quick start

This guide walks you through setting up Meilisearch with meili, the Meilisearch command line tool. meili works with Meilisearch Cloud projects and with self-hosted instances.

Prerequisites

A Meilisearch instance (Cloud or self-hosted)
Node.js 22 or later, only if you install the CLI with npm

1. Install the CLI

npm
Homebrew
Install script

npm install -g @meilisearch/cli

brew install meilisearch/tap/meili

# to upgrade
brew update && brew upgrade meilisearch/tap/meili

curl -fsSL https://raw.githubusercontent.com/meilisearch/cli/main/scripts/install.sh | sh

The script works on macOS and Linux. Run it again to update the CLI.

Check the installation:

meili version

2. Connect to Meilisearch

The CLI stores your projects in a config file, ~/.config/meili/config.json by default. Each project has a name, a URL, and an API key.

Meilisearch Cloud
Self-hosted

meili auth login
meili config sync-with-cloud --all

When you are an admin of the project’s team, the CLI also saves the project’s master key. Otherwise, the CLI saves the project without an API key. Ask an admin of the team for an API key, then add it to the config file:

meili config update --project PROJECT_NAME --project-api-key YOUR_API_KEY

Add your instance to the config file:

meili config set --project local \
  --project-url http://localhost:7700 \
  --project-api-key YOUR_API_KEY

List the projects of the config file:

meili config list

Every command takes the project name with --project (or -p). Check that the instance is available:

meili health --project local
# status  available

3. Add documents

Create a movies.json file:

cat > movies.json << 'EOF'
[
  { "id": 1, "title": "The Matrix", "genres": ["Action", "Sci-Fi"], "year": 1999 },
  { "id": 2, "title": "Inception", "genres": ["Action", "Thriller"], "year": 2010 },
  { "id": 3, "title": "Interstellar", "genres": ["Drama", "Sci-Fi"], "year": 2014 }
]
EOF

Add the documents to the movies index (--index or -i):

meili document add --project local --index movies --file movies.json --wait

Meilisearch creates the movies index if it does not exist. Adding documents is an asynchronous operation: without --wait, the CLI prints the task and returns at once. --wait follows the task until indexing is complete, then prints the final task.

4. Search

meili search --project local --index movies --q matrix

The CLI prints the results as a table:

Showing 1 of about 1
query matrix • processingTimeMs 1 • limit 20 • offset 0

ID  TITLE       GENRES          YEAR
1   The Matrix  Action, Sci-Fi  1999

Add --json to print the JSON response of Meilisearch instead.

5. Search with filters

First, configure filterable attributes:

meili settings update --project local --index movies \
  --filterable-attributes genres,year --wait

Then search with filters:

meili search --project local --index movies \
  --filter 'genres = "Sci-Fi" AND year > 2000'

Without --q, Meilisearch runs a placeholder search and returns all documents that match the filter, here Interstellar.

Full example

# Connect to your instance
meili config set --project local \
  --project-url http://localhost:7700 \
  --project-api-key YOUR_API_KEY

# Add documents
meili document add -p local -i movies --file movies.json --wait

# Search
meili search -p local -i movies --q inter

Explore the commands

meili --help lists every command. Add --help to any command to see its flags and examples:

meili --help
meili search --help

meili schema describes every command as JSON. meili schema --command <name> describes one command in full, with its flags, the Meilisearch routes it calls, and examples. Scripts and AI agents can use it to discover the commands:

meili schema
meili schema --command search

Next steps

Full-text search

Configure ranking and relevancy

Filtering

Add filters and facets

AI-powered search

Add semantic search

API reference

Explore all search parameters

Resources

Meilisearch CLI on GitHub

Introduction

Tools

Back-end SDKs

Frontend SDKs

Framework integrations

Integrations

Prerequisites

1. Install the CLI

2. Connect to Meilisearch

3. Add documents

4. Search

5. Search with filters

Full example

Explore the commands

Next steps

Full-text search

Filtering

AI-powered search

API reference

Resources

​Prerequisites

​1. Install the CLI

​2. Connect to Meilisearch

​3. Add documents

​4. Search

​5. Search with filters

​Full example

​Explore the commands

​Next steps

Full-text search

Filtering

AI-powered search

API reference

​Resources

Prerequisites

1. Install the CLI

2. Connect to Meilisearch

3. Add documents

4. Search

5. Search with filters

Full example

Explore the commands

Next steps

Resources