Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/algolia/algolia-cli-old

[DEPRECATED] This repo and npm package are no longer maintained or supported. The new official command line tool can be found here: https://github.com/algolia/cli
https://github.com/algolia/algolia-cli-old

deprecated

Last synced: about 2 months ago
JSON representation

[DEPRECATED] This repo and npm package are no longer maintained or supported. The new official command line tool can be found here: https://github.com/algolia/cli

Host: GitHub
URL: https://github.com/algolia/algolia-cli-old
Owner: algolia
Archived: true
Created: 2018-11-13T22:09:20.000Z (almost 6 years ago)
Default Branch: develop
Last Pushed: 2023-03-03T08:42:59.000Z (over 1 year ago)
Last Synced: 2024-07-12T10:07:29.623Z (2 months ago)
Topics: deprecated
Language: JavaScript
Homepage:
Size: 4.13 MB
Stars: 83
Watchers: 59
Forks: 10
Open Issues: 13
Metadata Files:
- Readme: readme.md

Awesome Lists containing this project

README

# [DEPRECATED]

The new official Algolia CLI can be found here: https://github.com/algolia/cli

This repo and npm package are no longer maintained or supported.

# Algolia CLI

A Node CLI tool that makes it easy to perform common data manipulations and interactions with your Algolia app or indices.

- [Requirements](#requirements)
- [Install](#install)
- [Usage](#usage)
- [Commands](#commands)
- [Examples](#examples)
- [Contribute](#contribute)

# Requirements

- [Node.js](https://nodejs.org/)

# Install

- `npm install -g @algolia/cli`

# Usage

##### 📌 `algolia [OPTIONS]` 📌

```bash
$ algolia --help

$ algolia --version

$ algolia interactive

$ algolia search -a -k -n -q -p -o

$ algolia import -s -a -k -n -b -t -m -p

$ algolia export -a -k -n -o -p

$ algolia getsettings -a -k -n

$ algolia setsettings -a -k -n -s -p

$ algolia addrules -a -k -n -s -p

$ algolia exportrules -a -k -n -o

$ algolia addsynonyms -a -k -n -s -p

$ algolia exportsynonyms -a -k -n -o

$ algolia transferindex -a -k -n -d -y -i -t -e

$ algolia transferindexconfig -a -k -n -d -y -i -p -e

$ algolia deleteindicespattern -a -k -r '' -x

$ algolia transformlines -s -o -t

$ algolia examples
```

See also [additional examples](#examples).

# Commands

### 1. Help | `--help`

##### Description:

Get basic usage info for all provided CLI scripts.

##### Usage:

```shell
algolia --help
```

```
algolia -h
```

### 2. Version | `--version`

##### Description:

Get version info for npm package.

##### Usage:

```shell
algolia --version
```

```
algolia -v
```

### 3. Interactive | `interactive`

##### Description:

Use Algolia CLI in interactive mode. Get command and argument prompts.

##### Usage:

```shell
algolia interactive
```

### 4. Search | `search`

##### Description:

Search an Algolia index.

##### Usage:

```shell
algolia search -a -k -n -q -p -o
```

##### Options:

##### Notes:

- If no `` is provided, command will simply console.log() the response.
- If an `` is provided, command will write a JSON file to that location.
- Provided `` path must include file name.
- See [search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/) for more documentation about search options.

### 5. Import | `import`

##### Description:

Import JSON or CSV data into Algolia index, from a file or directory of files.

You may also optionally apply custom transformations to each object indexed. CSV files will automatically be converted to JSON before transformations are applied.

Will handle arbitrarily large files without performance issues.

##### Usage:

```shell
algolia import -s -a -k -n -b -t -m -p
```

##### Options:

- `` | Required | Path to a JSON or CSV file, or to a directory of such files.
- `` | Required
- `` | Required
- `` | Required
- `` | Optional | Number of JSON objects to be included in each batch for indexing. Default is `5000`.
- `` | Optional | The path to any file that exports a function which (1) takes 2 arguments; an object and a callback, then (2) ends by calling said callback with the 2 arguments `null` and ``.
- `` | Optional | Maximum number of concurrent filestreams to process. Default is `2`.
- `` | Optional | Stringified [Parser parameters](https://github.com/Keyang/node-csvtojson#parameters) object passed to [csvtojson](https://www.npmjs.com/package/csvtojson) module.

##### Example Transformation File:

See `transformations/example-transformations.js` for an extensive JSON object transformation example.

Simple transformation file example:
```javascript
module.exports = (data,cb) => {
try {
const record = Object.assign({}, data);
record.objectID = data.product_id;
record.score = Math.floor(Math.random() * 100);
record.formattedNumber = parseInt(data.integer_formatted_as_string, 10);
cb(null, record);
} catch (e) {
console.log('Transformation error:', e.message, e.stack);
throw e;
}
}
```

##### Notes:

- `` may target a file or a directory of files.
- JSON files must contain an array of objects.
- CSV files must have a `.csv` extension.
- `` requires a path to a transformation file. See [example file](transformations/example-transformations.js).
- Make sure you only import JSON or CSV files. Don't accidentally try to import hidden files like `.DS_Store`, log files, etc. as they will throw an error.
- Command assumes each file contains an array of JSON objects unless the file extension ends with `.csv`.
- CSV to JSON conversion performed using [csvtojson](https://www.npmjs.com/package/csvtojson) package.
- If no `` is explicitly provided, command will try to determine optimal batch size by estimating average record size, estimating network speed, and calculating a size that should work well given the concurrency.
- If command outputs a `AlgoliaSearchRequestTimeoutError` error, this means a batch of records failed to import. This typically occurs when attempting to import too much data over too slow a network connection. Command will automatically attempt to reduce `` to compensate, and re-try. If issues persist, consider reducing `` and/or ``.
- If command outputs a `High memory usage` warning, it means the process is consuming a very high percentage of the estimated system heap allocation for the node process. Command will automatically attempt to reduce `` to compensate. If issues persist, consider reducing `` and/or ``.

### 6. Export | `export`

##### Description:

Download all JSON records from a specific Algolia index.

##### Usage:

```shell
algolia export -a -k -n -o -p
```

##### Options:

- `` | Required
- `` | Required
- `` | Required
- `` | Optional | Path to an existing local directory where output files will be saved (filenames are autogenerated). If no output path is provided, defaults to current working directory.
- `` | Optional | JSON [Search params](https://www.algolia.com/doc/api-reference/search-api-parameters/) object passed to `browseAll()` [method](https://www.algolia.com/doc/api-reference/api-methods/browse/).

##### Notes:

- `` must be a directory.

### 7. Get Settings | `getsettings`

##### Description:

Get settings for a specific Algolia index.

##### Usage:

```shell
algolia getsettings -a -k -n
```

##### Options:

- `` | Required
- `` | Required
- `` | Required

##### Notes:

- To write settings JSON locally, just redirect the output to a file. For example:
`$ algolia getsettings -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME > ~/Desktop/EXAMPLE_FILE_NAME.json`

### 8. Set Settings | `setsettings`

##### Description:

Set settings for a specific Algolia index.

##### Usage:

```shell
algolia setsettings -a -k -n -s -p
```

##### Options:

##### Example settings file:

```js
module.exports = {
minWordSizefor1Typo: 4,
minWordSizefor2Typos: 8,
hitsPerPage: 20,
maxValuesPerFacet: 100,
version: 2,
attributesToIndex: null,
numericAttributesToIndex: null,
attributesToRetrieve: null,
unretrievableAttributes: null,
optionalWords: null,
attributesForFaceting: null,
attributesToSnippet: null,
attributesToHighlight: null,
paginationLimitedTo: 1000,
attributeForDistinct: null,
exactOnSingleWordQuery: 'attribute',
ranking:
[ 'typo',
'geo',
'words',
'filters',
'proximity',
'attribute',
'exact',
'custom' ],
customRanking: null,
separatorsToIndex: '',
removeWordsIfNoResults: 'none',
queryType: 'prefixLast',
highlightPreTag: '',
highlightPostTag: '',
snippetEllipsisText: '',
alternativesAsExact: [ 'ignorePlurals', 'singleWordSynonym' ]
};
```

##### Example setSettings params:

```
'{"forwardToReplicas":true}'
```
##### Notes:
- Any index setting parameter needs to be added directly in the file containing the settings object. See [Settings API paraameters documentation](https://www.algolia.com/doc/api-reference/settings-api-parameters/) to find the full list of index settings parameters.
- forwardToReplicas is currently the only option that can be passed to the settings method as an optional argument.

### 9. Add Rules | `addrules`

##### Description:

Import a local JSON file of query rules to an Algolia index.

##### Usage:

```shell
algolia addrules -a -k -n -s -p
```

##### Options:

##### Notes:

- See [batchRules documentation](https://www.algolia.com/doc/api-reference/api-methods/batch-rules/) and [implementing query rules documentation](https://www.algolia.com/doc/guides/managing-results/refine-results/merchandising-and-promoting/in-depth/implementing-query-rules/) for more info.

### 10. Export Rules | `exportrules`

##### Description:

Download all query rules from a specific Algolia index.

##### Usage:

```shell
algolia exportrules -a -k -n -o
```

##### Options:

##### Notes:

- ``path must include file name.

### 11. Add Synonyms | `addsynonyms`

##### Description:

Import a local CSV or JSON file of synonyms to an Algolia index. Some public synonym files can be downloaded from [this repository](https://github.com/algolia/synonym-dictionaries). Disclaimer: These are not intended to be all encompassing -- edits may be needed for your use case.

Note that if importing a CSV file, the expected format is file with no headers and with each row of comma-separated values being a group of synonyms for each other. For more information, read our [documentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/how-to/managing-synonyms-from-the-dashboard/#csv) on the topic.

##### Usage:

```shell
algolia addsynonyms -a -k -n -s -p
```

##### Options:

##### Notes:

- See [batchSynonyms documentation](https://www.algolia.com/doc/api-reference/api-methods/batch-synonyms/) and [adding synonyms documentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/) for more info.

### 12. Export Synonyms | `exportsynonyms`

##### Description:

Download all synonyms from a specific Algolia index.

##### Usage:

```shell
algolia exportsynonyms -a -k -n -o
```

##### Options:

##### Notes:

- ``path must include file name.

### 13. Transfer Index | `transferindex`

##### Description:

Transfer all data and settings (including synonyms and query rules) from one Algolia app/index to another.

##### Usage:

```shell
algolia transferindex -a -k -n -d -y -i -t -e
```

##### Options:

- `` | Required
- `` | Required
- `` | Required
- `` | Required
- `` | Required
- `` | Optional | If no destination index name is specified, script will default to creating a new index with the same name as the source index.
- `` | Optional | The path to any file that exports a function which (1) takes a single object as argument, then (2) returns a transformed object.
- `` | Optional | This is a boolean. When `true`, it will exclude the `replicas` setting when copying settings to the destination index. When `false`, it will copy the full settings object. Defaults to `false`.

##### Example Transformation File:

Simple transformation file for transferring an index:

```javascript
module.exports = (obj) => {
try {
const record = {};
record.objectID = obj.product_id;
record.score = Math.floor(Math.random() * 100);
record.formattedNumber = parseInt(obj.integer_formatted_as_string, 10);
} catch (e) {
console.log('Transformation error:', e.message, e.stack);
throw e;
}
}
```

##### Notes:

- Command duplicates data and copies settings, synonyms, and rules; does not delete or affect source index.
- Command does NOT forward settings or synonyms to replicas.

### 14. Transfer Index Config | `transferindexconfig`

##### Description:

Transfer an index's settings, synonyms, and query rules to another index. Works even across indices in different Algolia applications.

##### Usage:

```shell
algolia transferindexconfig -a -k -n -d -y -i -p -e
```

##### Options:

- `` | Required
- `` | Required
- `` | Required
- `` | Required
- `` | Required
- `` | Optional | If no destination index name is specified, script will default to targetting an existing index with the same name as the source index.
- `` | Optional | JSON object containing one or both of the following two properties: `batchSynonymsParams` and `batchRulesParams`. Each of those property values may contain a parameters object to be passed to the [batchSynonyms](https://www.algolia.com/doc/api-reference/api-methods/batch-synonyms/) and [batchRules](https://www.algolia.com/doc/api-reference/api-methods/batch-rules/) respectively.
- `` | Optional | This is a boolean. When `true`, it will exclude the `replicas` setting when copying settings to the destination index. When `false`, it will copy the full settings object. Defaults to `false`.

##### Notes:

- When transferring synonyms and query rules, `forwardToReplicas`, `replaceExistingSynonyms`, and `clearExistingRules` params will default to false, unless you specify ``.

### 15. Delete Indices Pattern | `deleteindicespattern`

##### Description:

Delete multiple indices at once (main or replica indices included) using a regular expression.

##### Usage:

```shell
algolia deleteindicespattern -a -k -r '' -x
```

##### Options:

##### Notes:

- The command handles replicas. First it update the settings of all main indices removing any replica that will match the regular expression. Then it will delete all matching indices (main and replica indices).

##### Example:

```shell
algolia deleteindicespattern -a someAppId -k someApiKey -r '^staging__' -x false
```

This will delete all indices of the application that are starting with "staging__".

### 16. Transform Lines | `transformlines`

##### Description:

Transform a file line-by-line.

##### Usage:

```shell
algolia transformlines -s -o -t
```

##### Options:

- `` | Required | Path to a single `.js` or `.json` file OR a directory of such files.
- `` | Optional | Path to an existing local directory where output files will be saved (saved output filenames will match corresponding source filenames). If no output path is provided, defaults to current working directory.
- `` | Optional | Path to file that exports a function which (1) takes a line string, and (2) returns a transformed line string.

##### Example use case:

Mapping each line of input file to a new output file.

Originally designed for converting `.json-seq` files to regular comma separated JSON arrays, in order to index them with the `import` cli tool.

##### Example Transformation File:

Let's say we had this source JSON file:
```json
[
{"id":1,"color":"blue"},
{"id":2,"color":"red"},
{"id":3,"color":"green"}
]
```
and we wanted to filter out any objects that didn't have a "color" value of "blue". In this case, our transformations function could be something like this:
```javascript
module.exports = (line) => {
if (line === '[' || line === ']') {
return line;
} else if (line.includes('"color":"blue"')) {
return line;
} else {
return '\n';
}
}
```

##### Notes:

- `` must be a directory.
- Running `transformlines` command without providing optional `` param will cause it to assume it's parsing a `.json-seq` file; thus, it will apply the `defaultLineTransformation` method in `transformLines.js` to each line. This checks each line for the ASCII Record Separator character `\u001e` and replaces it with a `,`. It will _also_ cause it to enclose the whole file in "[" and "]" square brackets to make it a valid JS array. Providing a custom transformation method via the optional `` param will make it exclusively run your transformation function instead of the default one (and in this case it will also omit adding enclosing square brackets).

### 14. Examples | `examples`

##### Description:

Display command usage examples.

##### Usage:

```shell
algolia examples
```

##### Notes:

- See equivalent list of [examples below](#examples).

# Examples
```bash
$ algolia --help

$ algolia --version

$ algolia interactive

$ algolia search -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -q 'example query' -p '{"facetFilters":["category:book"]}' -o ~/Desktop/results.json

$ algolia import -s ~/Desktop/example_source_directory/ -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -b 5000 -t ~/Desktop/example_transformations.js -m 4 -p '{"delimiter":[":"]}'

$ algolia export -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -o ~/Desktop/example_output_folder/ -p '{"filters":["category:book"]}'

$ algolia getsettings -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME

$ algolia setsettings -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -s ~/Desktop/example_settings.json -p '{"forwardToReplicas":true}'

$ algolia addrules -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -s ~/Desktop/example_rules.json -p '{"forwardToReplicas":false,"clearExistingRules":true}'

$ algolia exportrules -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -o ~/Desktop/example_rules.json

$ algolia addsynonyms -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -s ~/Desktop/example_synonyms.json -p '{"forwardToReplicas":true,"clearExistingSynonyms":true}'

$ algolia exportsynonyms -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -n EXAMPLE_INDEX_NAME -o ~/Desktop/example_synonyms.json

$ algolia transferindex -a EXAMPLE_SOURCE_APP_ID -k EXAMPLE_SOURCE_API_KEY -n EXAMPLE_SOURCE_INDEX_NAME -d EXAMPLE_DESTINATION_APP_ID -y EXAMPLE_DESTINATION_API_KEY -i EXAMPLE_DESTINATION_INDEX_NAME -t ~/Desktop/example_transformations.js -e true

$ algolia transferindexconfig -a EXAMPLE_SOURCE_APP_ID -k EXAMPLE_SOURCE_API_KEY -n EXAMPLE_SOURCE_INDEX_NAME -d EXAMPLE_DESTINATION_APP_ID -y EXAMPLE_DESTINATION_API_KEY -i EXAMPLE_DESTINATION_INDEX_NAME -p '{"batchSynonymsParams":{"forwardToReplicas":true,"replaceExistingSynonyms":true},"batchRulesParams":{"forwardToReplicas":true,"clearExistingRules":true}}' -e true

$ algolia deleteindicespattern -a EXAMPLE_APP_ID -k EXAMPLE_API_KEY -r '^regex' -x true

$ algolia transformlines -s ~/Desktop/example_source_file.json -o ~/Desktop/example_output_folder/ -t ~/Desktop/example_transformations.js

$ algolia examples
```

# Contribute

## Requirements

- Node: `brew install node` or [Node docs](https://nodejs.org/en/)
- Yarn: `brew install yarn` or [Yarn docs](https://yarnpkg.com/lang/en/)

## Install

- Clone repo.
- `yarn install`
- Create `.env` file in project root and assign environment variables as listed [below](#environment-variables).

## Environment variables

- `ALGOLIA_TEST_APP_ID`
- `ALGOLIA_TEST_API_KEY`
- `ALGOLIA_TEST_INDEX_NAME`
- `ALGOLIA_TEST_ALT_APP_ID`
- `ALGOLIA_TEST_ALT_API_KEY`

## Develop
- Run `node index.js [options]` to test various commands/options.
- Write code!
- Please use [git-flow](https://github.com/nvie/gitflow) and commit your changes on a feature branch, rebase it on develop branch before finishing the feature, then issue pull request to develop branch

## Tests
- `yarn test` to run full test suite locally
- `yarn test:unit` to run unit test suite only
- `yarn test:unit:watch` to run unit test suite with interactive `--watch` flag
- `yarn test:integration` to run integration test suite only

## Lint
- `yarn lint` to run eslint
- `yarn lint:fix` to run eslint with --fix flag