> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage examples for the Algolia CLI

> Examples for completing various tasks with the Algolia CLI.

<Info>
  The examples on this page use `-p` (`--profile`) for authentication,
  or use the default profile.
  For more information, see [Authentication](/doc/tools/cli/authentication)
</Info>

## Work with JSON data

The Algolia CLI works well with other command-line tools,
such as [`jq`](https://jqlang.org) 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](https://github.com/stedolan/jq/releases/latest) page of the GitHub repository.

### Newline-delimited JSON

Newline-delimited JSON ([NDJSON](https://github.com/ndjson/ndjson-spec)),
also called JSON lines ([JSONL](https://jsonlines.org)),
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`:

```sh Command line icon=square-terminal theme={"system"}
# 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:

```sh Command line icon=square-terminal theme={"system"}
# 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](#convert-between-json-and-ndjson).

To export all your settings, synonyms, and rules in a single file,
use the [`algolia indices config export`](/doc/tools/cli/commands/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:

```sh Command line icon=square-terminal theme={"system"}
# 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:

```sh Command line icon=square-terminal theme={"system"}
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`](/doc/tools/cli/commands/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](https://en.wikipedia.org/wiki/Process_substitution):

```sh Command line icon=square-terminal theme={"system"}
diff --side-by-side \
  --suppress-common-lines \
  <(algolia settings get INDEX_1 | jq) \
  <(algolia settings get INDEX_2 | jq)
```

<Info>
  `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.
</Info>

Replace `INDEX_1` and `INDEX_2` with the names of the indices you want to compare,
and [specify profiles](/doc/tools/cli/authentication)
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:

```sh Command line icon=square-terminal theme={"system"}
# 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](/doc/tools/cli/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`](/doc/api-reference/api-parameters/queryLanguages) and
[`indexLanguages`](/doc/api-reference/api-parameters/indexLanguages), run:

```sh Command line icon=square-terminal theme={"system"}
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:

```sh Command line icon=square-terminal theme={"system"}
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:

```sh Command line icon=square-terminal theme={"system"}
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**.

```sh Command line icon=square-terminal theme={"system"}
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"
```