Elastic Shell 101 - Getting Started

What is it

Elastic Shell is an open source project that includes a set of command line utilities and run as a client to help you manage Elasticsearch. It is entirely written in Bash Shell.

“Elastic Shell 101” is a series of posts that tells you how to use it.

In this post, I will show you how to run Elastic Shell from the command line and use its cat command to call Elasticsearch /_cat APIs.

How to run

Elastic Shell can be run both inside or outside of Docker container. Within Docker container, all dependencies have been installed and configured properly. So you don’t have to do anything else but just use it. Throughout the “Elastic Shell 101” series, I will use the prebuilt Docker image from Docker Hub to demonstrate all the work. So, now let’s pull the image from Docker Hub at first:

$ docker pull morningspace/elastic-shell

Then, start it:

$ docker run -it morningspace/elastic-shell bash

For local test, you can launch another Docker container which includes an Elasticsearch cluster and add both containers to the same bridge network in order to have the Elasticsearch cluster be visible to the Elastic Shell container. Then, you may need --net option when launch the Docker container. For example:

$ docker run -it --net=lab-elk-net morningspace/elastic-shell bash

In the Elastic Shell container, there’s a soft link that have been created for Elastic Shell, so you can run a command called elash from anywhere to launch Elastic Shell. Here, elash is the abbreviation of Elastic Shell, and the main entrance of all the commands that Elastic Shell provides.

Outside of container

When run Elastic Shell outside of the container, find the main.sh under the home folder of Elastic Shell to run.

Get help

If you do not specify any additional options, you will see the default help information with all the available commands. Choose one of the command, with option --help, it will take you to the detailed help information of that command, where you will see all the sub commands that are available to that command, some general options, as well as the usage examples of these sub commands.

If you run elash <command> without appending anything else, it will list all the sub commands or arguments that are available based on the current context. This is very helpful if you do not know what else information that you need to provide in order to run a particular command correctly. For example, here are all the sub-commands that you can run for elash index command.

bash-4.4# elash index

Commands/Options:
  cat
  create
  update
  delete
  doc
  bulk
  search
  config

Run cat

Let’s try cat command first. It maps to Elasticsearch /_cat APIs. Append cat after index

bash-4.4# elash index cat

Commands/Options:
  indices
  shards
  nodes
  ...

You will see the available commands or arguments are changed. Choose one of them, for example nodes, will show you topology of the Elasticsearch cluster.

bash-4.4# elash index cat nodes

_cat/nodes?v
------------------------------------------------------------------------------
ip          heap.percent  ram.percent cpu load_1m load_5m load_15m node.role master name
172.18.0.11           34           96  16    1.37    1.04     1.05 mdi       *      90d99514da15

Commands/Options:
  indices
  shards
  nodes
  ...

Again, we see the available commands or arguments based on the context. And this is the same as what we see before. It means you can append more cat commands and chain them together. This is very cool. Let’s try it:

bash-4.4# elash index cat nodes indices shards

_cat/nodes?v
------------------------------------------------------------------------------
ip          heap.percent  ram.percent cpu load_1m load_5m load_15m node.role master name
172.18.0.11           34           96  16    1.37    1.04     1.05 mdi       *      90d99514da15

_cat/indices?v
------------------------------------------------------------------------------
health status index uuid pri rep docs.count docs.deleted store.size pri.store.size

_cat/shards?v
------------------------------------------------------------------------------
index shard prirep state docs store ip node

Commands/Options:
  indices
  shards
  nodes
  ...

Because our Elasticsearch cluster has no any index yet, we see the indices and shards commands returning empty. We will run index command to create some indices later.

The … argument

There’s one more special argument to explain: the ... argument. It means all the other cat commands. If you want to run cat commands that are not listed above, just append that command after .... For example, this lists all plugins that are currently running.

bash-4.4# elash index cat ... plugins

_cat/plugins?v
------------------------------------------------------
name         component         version
90d99514da15 ingest-geoip      6.3.2
90d99514da15 ingest-user-agent 6.3.2

Commands/Options:
  indices
  shards
  nodes
  ...

If you just append ... after cat, it will list all the available cat commands that are supported by the Elasticsearch cluster.

For more stories on Elastic Shell, stay tuned for next posts! Any question about this post or Elastic Shell, feel free to leave comments or drop email at morningspace@yahoo.com.