Usage examples for the Algolia CLI

Examples for completing various tasks with the Algolia CLI.

The examples on this page use the application you selected with algolia application select. Where two applications are involved, they pass credentials with the --application-id and --api-key flags. For more information, see Authentication.

Work with JSON data

The Algolia CLI works well with other command-line tools, such as jq for working with JSON data. Many examples on this page use jq to transform inputs and outputs to and from JSON.

You can install jq with your favorite package manager, or download a binary from the Releases page of the GitHub repository.

Newline-delimited JSON

Newline-delimited JSON (NDJSON), also called JSON lines (JSONL), is a file format that works well for streaming lists of objects. Because each line is its own valid JSON object, you can work with each object separately while you are reading the stream. With a JSON array for example, you would have to read the entire list first, or you would get a JSON parsing error.

Convert between JSON and NDJSON

You can convert between JSON and NDJSON with jq:

Command line

# From NDJSON to JSON
jq --slurp "." file.ndjson > file.json

# From JSON to NDJSON
jq --compact-output '.[]' file.json > file.ndjson

Export your Algolia data

To create a backup of your index (records, rules, settings, and synonyms), use the following commands:

Command line

# Export records from the index INDEX
algolia objects browse INDEX > records.ndjson

# Export rules from the index INDEX
algolia rules browse INDEX > rules.ndjson

# Export settings from the index INDEX
# (Settings is a JSON object)
algolia settings get INDEX > settings.json

# Export synonyms from the index INDEX
algolia synonyms browse INDEX > synonyms.ndjson

If you want to upload the records, synonyms, or rules in the Algolia dashboard, convert them to JSON first.

To export all your settings, synonyms, and rules in a single file, use the algolia indices config export command. This creates a JSON file which you can import in the dashboard.

Import your Algolia data

To import records, synonyms, settings, or rules from a file, use these commands:

Command line

# Import records from an NDJSON file
algolia objects import INDEX --file records.ndjson

# Import records from a JSON file
cat records.json | jq -c '.[]' | algolia import import INDEX --file -

The same commands also work with synonyms or rules instead of objects. Settings are in a regular JSON object:

Command line

algolia settings import INDEX --file settings.json

To import a JSON file with all your settings, synonyms, and rules, use the algolia indices config import command. The JSON file can be exported from the dashboard, or with the algolia indices config export command.

Compare index settings

To compare two index settings, use the Algolia CLI with the diff and jq commands. This example uses process substitution:

Command line

diff --side-by-side \
  --suppress-common-lines \
  <(algolia settings get INDEX_1 | jq) \
  <(algolia settings get INDEX_2 | jq)

jq is required because the algolia settings command prints compact JSON output without formatting if it runs in pipes, which makes it difficult to see the differences.

Replace INDEX_1 and INDEX_2 with the names of the indices you want to compare, and pass --application-id and --api-key if the indices aren’t in your selected application.

Copy indices between applications

To copy an index (records, synonyms, synonyms, rules) between two Algolia applications, you can list all objects with the browse command first, and pipe this into an import command:

Command line

# Copy the records
algolia objects browse INDEX --application-id APP_ID_1 --api-key API_KEY_1 \
  | algolia objects import INDEX --application-id APP_ID_2 --api-key API_KEY_2 -F -

# Copy synonyms
algolia synonyms browse INDEX --application-id APP_ID_1 --api-key API_KEY_1 \
  | algolia synonyms import INDEX --application-id APP_ID_2 --api-key API_KEY_2 -F -

# Copy rules
algolia rules browse INDEX --application-id APP_ID_1 --api-key API_KEY_1 \
  | algolia rules import INDEX --application-id APP_ID_2 --api-key API_KEY_2 -F -

# Copy settings
algolia settings get INDEX --application-id APP_ID_1 --api-key API_KEY_1 \
  | algolia settings import INDEX --application-id APP_ID_2 --api-key API_KEY_2 -F -

Replace APP_ID_1/API_KEY_1 and APP_ID_2/API_KEY_2 with the credentials of the source and destination applications. For more information, see Authentication.

Copy specific index settings

You can use jq to filter the output from the algolia settings get command so that only specific index settings are copied.

For example, to copy all index settings except queryLanguages and indexLanguages, run:

Command line

algolia settings get INDEX_1 \
  | jq 'del(.queryLanguages,.indexLanguages)' \
  | algolia settings import INDEX_2 -F -

Change settings while copying

You can change the output from the algolia settings get command with jq. For example, to change the queryLanguages and indexLanguages settings to French, run:

Command line

algolia settings get INDEX_1 \
  | jq '.queryLanguages=["fr"],.indexLanguages=["fr"]' \
  | algolia settings import INDEX_2 -F -

Find records with missing attributes

Filter the results from the algolia objects browse command with jq. For example, to find records without a name attribute:

Command line

algolia objects browse INDEX --attributesToRetrieve "name" \
  | jq -rs 'map(select(has("name") | not) .objectID)'

The --attributesToRetrieve option only includes the name attribute in the API response. The jq command first selects all elements without a name attribute and then returns a list of their object IDs. You can turn this into a comma-separated list by adding | join(",") to the command.

You can combine this with the algolia objects delete command to delete all records with a missing attribute.

Command line

records_to_delete=$(
  algolia objects browse INDEX --attributesToRetrieve "name" \
    | jq -rs 'map(select(has("name") | not) .objectID) | join(",")'
)
algolia objects delete --object-ids "$records_to_delete"