Usage examples for the Algolia CLI

Learn how to complete various tasks with the Algolia CLI.

Install jq for working with JSON data

The Algolia CLI works well with other command-line tools. For example, jq is a useful tool for working with JSON data.

You can install jq with a package manager or download the release from the GitHub repository.

Input and output formats

By default, these commands import and export data in newline-delimited JSON (NDJSON) format, one object per line:

• algolia objects
• algolia rules
• algolia synonyms

The algolia settings command imports and exports a regular JSON object.

The Algolia CLI can read from NDJSON files directly. The Algolia dashboard expects rules, records, and synonyms as a JSON array.

You can convert between JSON and NDJSON with jq:

1
2
3
4
5
# Convert an NDJSON file to a JSON file with an array
jq --slurp "." file.ndjson > file.json

# Convert a JSON file (array) into an NDJSON file
jq --compact-output '.[]' file.json > file.ndjson

Export to files

To export your index (rules, synonyms, settings, and records) to files, add > to the command, followed by a filename. This can be useful to create backups of your Algolia application data.

1
2
3
algolia objects browse INDEX > records.ndjson
algolia rules browse INDEX > rules.ndjson
algolia synonyms browse INDEX > synonyms.ndjson

1
algolia objects browse INDEX | jq -s > records.json

1
algolia index config export INDEX

Replace INDEX with your index name and specify the profile if your index isn’t in your default profile.

Import from files or standard input

Use the --file option (-F) to read from an NDJSON file. Use --file - (-F -) to read from standard input—for example, the output from another command.

1
2
3
algolia objects import INDEX -F records.ndjson
algolia rules import INDEX -F rules.ndjson
algolia synonyms import INDEX -F synonyms.ndjson

1
2
3
4
5
jq -c '.[]' file.json | algolia objects import INDEX -F -
jq -c '.[]' file.json | algolia rules import INDEX -F -
jq -c '.[]' file.json | algolia synonyms import INDEX -F -
# Settings are already a regular JSON object
algolia settings import INDEX -F settings.json

1
algolia indices config import INDEX -F export-STAGING_TEST_PRODUCTS-APP_ID-1666792448.json

Replace INDEX with your index name and specify the profile if your index isn’t in your default profile.

Compare two index configurations

To compare two index configurations, run:

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

Replace INDEX_1 and INDEX_2 with the names of the indices you want to compare, and specify profiles if your indices aren’t in the default profile.

Copy indices with the Algolia CLI

The Algolia CLI lets you export your records, rules, synonyms, or settings from one index and import them into another, even across profiles (different Algolia applications).

To copy an index within the same Algolia application, you can also use the algolia indices copy command.

Copy indices between apps

To copy records, rules, or synonyms between two indices, run:

1
2
algolia COMMAND browse INDEX_1 -p PROFILE_1 \
| algolia COMMAND import INDEX_2 -p PROFILE_2 -F -

• Replace COMMAND with rules, synonyms, or objects.
• Replace INDEX_1 and PROFILE_1 with the index and profile name from which you want to copy.
• Replace INDEX_2 and PROFILE_2 with the index and profile name to which you want to copy.

To copy settings between two indices, run:

1
2
algolia settings get INDEX_1 -p PROFILE_1 \
| algolia settings import INDEX_1 -p PROFILE_2 -F -

Copy only some index settings

To copy the index settings, except the queryLanguages and indexLanguages settings, run:

1
2
3
algolia settings get SOURCE_INDEX \
| jq 'del(.queryLanguages,.indexLanguages)' \
| algolia settings import TARGET_INDEX -F -

Replace SOURCE_INDEX and TARGET_INDEX with your index names and specify profiles if your indices aren’t in the default profile.

You can then use the algolia settings set command to add or change the settings:

1
2
3
algolia settings set TARGET_INDEX \
  --queryLanguages "..." \
  --indexLanguages "..."

Change settings while copying

With jq, you can also change the settings while copying them between indices. For example, to set the query and indexing language to French:

1
2
3
algolia settings get SOURCE_INDEX \
| jq '.queryLanguages=["fr"],.indexLanguages=["fr"]' \
| algolia settings import TARGET_INDEX -F -

Replace SOURCE_INDEX and TARGET_INDEX with your index names and specify profiles if your indices aren’t in the default profile.

Copy indices with replicas

Copying an index with the algolia indices copy command does not copy the replicas of the original index.

To create a copy of an index, including its replicas, copy the indices separately and set the replica with the algolia settings set command:

1
2
3
4
5
6
7
8
# Copy the primary index
algolia index copy INDEX INDEX_COPY

# Copy the replica index
algolia index copy REPLICA_INDEX REPLICA_INDEX_COPY

# Set the copy as replica index
algolia settings set INDEX_COPY --replicas REPLICA_INDEX_COPY

Replace INDEX, INDEX_COPY, REPLICA_INDEX, and REPLICA_INDEX_COPY with your index names and specify profiles if your indices aren’t in the default profile.

Find and filter records with missing attributes

To find records with missing attributes, use the algolia objects browse command and filter the results with jq. For example, to get the object IDs for records without a name attribute, run the following command:

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

The attributesToRetrieve option limits the attributes included in the response from the Algolia API to just the name attribute. The jq command first selects all elements without a name attribute and then returns a list of objectID values. You can turn this into a comma-separated list by appending | join(",") to the jq command.

For example, to delete records with a missing attribute from an index, you can run these two commands:

1
2
3
4
5
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}

For more information, check the jq documentation.