Usage examples for the Algolia CLI

Learn how to complete various tasks with the Algolia CLI.

The examples on this page use -p (--profile) for authentication, or use the default profile. 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:

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

1
2
3
4
5
6
7
8
9
10
11
12
# 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:

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

1
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:

1
2
3
4
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 specify profiles if your indices aren’t in the default profile.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Copy the records
algolia objects browse INDEX -p PROFILE_1 \
| algolia objects import INDEX -p PROFILE_2 -F -

# Copy synonyms
algolia synonyms browse INDEX -p PROFILE_1 \
| algolia synonyms import INDEX -p PROFILE_2 -F -

# Copy rules
algolia rules browse INDEX -p PROFILE_1 \
| algolia rules import INDEX -p PROFILE_2 -F -

# Copy settings
algolia settings get INDEX -p PROFILE_1 \
| algolia settings import INDEX -p PROFILE_2 -F -

Instead of using different profiles, you can provide the credentials with the --application-id and --api-key options. 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:

1
2
3
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:

1
2
3
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:

1
2
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.

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}