es-cli-tool

A CLI tool to help you query your elasticsearch server super fast 🚀

1. Prerequisites

You need to have:

• A running elasticsearch server, whether it's a local one, or a remote one.

Essentially you'll just need to have access to some elasticsearch server running. There are several ways to achieve that, so I'll just show you one way, which is running a local elasticsearch server on the default port (which 9200) using docker, with basic authentication, but you can choose whatever you like.

If you already have a running elasticsearch server you can skip to the Getting Started section.

* ElasticSearch With Docker *

- Step 1: run elasticsearch server for the first time

Run elasticsearch server and expose it to the host:

docker run --name es01 -p 9200:9200 -e ELASTIC_PASSWORD="your_password_here" -it -m 1GB docker.elastic.co/elasticsearch/elasticsearch:8.16.1

A little bit about the flags:

• We're giving our container the name "es01".
• The -m flag is here to set a limit for the memory of the container.
• Notice that the version of the elasticsearch image is 8.16.1, which could be out-of-date at the time you're watching this (it is currently the latest).

- Step 2: store password in an environment variable called ELASTIC_PASSWORD

In MacOS, put the following line:

export ELASTIC_PASSWORD="your_password_here"

in either one of .bashrc or .zshrc.

In Windows, create an environment variable named ELASTIC_PASSWORD and give it the password as value.

- Step 3: Test Connectivity

Before trying out the tool, let's test the connectivity with raw curl:

curl --insecure -u elastic:$ELASTIC_PASSWORD https://localhost:9200

The important parts to note here are:

• I'm using version 8.16.1 of elasticsearch. Different image versions would require different flags & protocols.
• It is required to use the --insecure flag.
• It is required to use the https protocol.
• It is required to use basic authentication. I had the password stored in an ENV variable called ELASTIC_PASSWORD, though you can put it directly in the command, it's just not recommended.

A good response would look like:

{
  "name" : "d37acd14f568",
  "cluster_name" : "docker-cluster",
  "cluster_uuid" : "ORl7COC4TxadsLCODBuA3A",
  "version" : {
    "number" : "8.16.1",
    "build_flavor" : "default",
    "build_type" : "docker",
    "build_hash" : "ffe992aa682c1968b5df375b5095b3a21f122bf3",
    "build_date" : "2024-11-19T16:00:31.793213192Z",
    "build_snapshot" : false,
    "lucene_version" : "9.12.0",
    "minimum_wire_compatibility_version" : "7.17.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "You Know, for Search"
}

---

2. Getting Started

- Step 1: Installation

Install the package globally:

- With npm:

npm install -g es-cli-tool

- With pnpm:

pnpm add -g es-cli-tool

- With yarn:

yarn add -g es-cli-tool

To check and see that the tool was installed properly, run the command:

es-cli-tool

And you should see this:

It is recommended to give the tool a shorted alias.

For example, if you're using zsh on a macOS, open the .zshrc file, and add this line:

alias sq="es-cli-tool"

Now, by running sq you should get the same result as running es-cli-tool (don't forget to source the zshrc file afterwards, or simply open a new terminal). (The next steps will assume you gave es-cli-tool an alias of sq)

- Step 2: Create your first context

Create a new context with:

sq create-context

In the first step, give it a name.
For example:

es8

In the second step, it'll ask you for a full url.
Write:

https://localhost:9200

In the third step, it'll ask you for flags.
Write:

--insecure --silent -u elastic:$ELASTIC_PASSWORD -H 'Content-Type: application/json'

- Step 3: Use the context

Let's use our newly created context:

sq use-context

And select the context you just created, es8.

- Step 4: Create an index

Let's now create our first index:

sq create-index

Give it a name, for example users.

- Step 5: Add the first document

To add a document we have two options:

1. Without Flags
2. With Flags

If you type:

sq add

You'll have two steps to complete: choosing an index to insert the document to, and writing the document to add in an editor.

However, if you type:

sq add --index users --file path/to/file.json

The query would execute immediately. You'll only need to create a json file with the contents of the document to add.

The file's contents could, for example, be:

{
  "firstName": "Tal",
  "lastName": "Kohavy"
}

And you should see the following output printed:

{
  "_index" : "users",
  "_id" : "oC9dt5MBmkFk9pPeuZX2",
  "_version" : 1,
  "result" : "created",
  "_shards" : {
    "total" : 2,
    "successful" : 1,
    "failed" : 0
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

- Step 6: Execute a GET query

Finally, this is where you'll appreciate the tool's simplicity 🙂
Using the get sub-command, you'll be able to execute pure elasticsearch queries with ease.

Write a simple line as:

sq get --index users --file path/to/file.json

where the file's contents would be a pure elasticsearch query, such as:

{
  "query": {
    "match_all": {}
  }
}

You can achieve exactly the same result, with a much simpler line:

sq get all --index users

And you should see the following output printed:

{
  "took" : 3,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "users",
        "_id" : "oC9dt5MBmkFk9pPeuZX2",
        "_score" : 1.0,
        "_source" : {
          "firstName" : "Tal",
          "lastName" : "Kohavy"
        }
      }
    ]
  }
}

---

3. Contributing

If you found a bug, or have a feature request, please open an issue about it.

License

MIT © Tal Kohavy