esctl/README.md

esctl

Elasticsearch CLI

Introduction

This is a handy cli tool which interfaces to an elasticsearch cluster (or two of them if you're using cross cluster replication). It is a work-in-progress project yet, things might change occasionally. Expect a stable release once we reach major version 1.0.0.

Features:

• Configuration of cluster credentials using environment vars or config file. Multiple clusters can be configured. esctl cluster ls shows which one is reachable.
• Shell completion support (bash, zsh and fish). Put this into your rc: source <(esctl completion bash).
• Cluster settings can be viewed and modified.
• Search: you can search indices using full text or by fields, select logical condition (OR, AND), use PIT, limit datetime (ES date math can be used), etc. It is however not yet possible to create recursive searches like: (cond1 AND cond2) OR (cond3 OR cond4).
• Cross cluster replication (ccr): view, pause, resume, delete replication. You can also manage follower configuration.
• Index management: manage aliases, create, modify, delete indices, display field mappings etc.
• Node management: only list nodes yet.
• Shard management: only list shards yet.
• Snapshot management: only list snapshots yet.
• Role management: only list roles yet. There's also a role diff subcommand, which is for internal use. It can be used to verify if role defs in a CSV match the deployed roles.
• Repl: this is an interactive REPL (read eval print loop) towards the elasticsearch API. You can run API calls on the current selected cluster w/o the hassle to specify the whole url, credentials etc. It has line editing and history support. If jq is installed output JSON will be syntax highlighted.
• Doc support. You can put, delete and show docs for an index. Very handy if you want to play with it. Just create a new index: esctl index create foo and then insert docs into it for search experiments:

  esctl doc add -i foo '{"title":"curry in a hurry", "message":"australian thai"}'
  

Usage

Command tree:

 ccr
     follower
         add
         delete
         pause
         renew
         resume
         show
         unfollow
     info
     pause
     resume
     status
 cluster
     list
     settings
         list
         set
     status
 debug
 doc
     add
     delete
     show
 help
 index
     alias
         create
         delete
         list
     allocation
     close
     create
     delete
     fields
     list
     modify
     show
 node
     list
     show
 repl
 role
     list
     show
 search
 shard
     list
     show
 snapshot
     list
     show
 version

Configure esctl with environment variables:

• ES_URI: elasticsearch uri
• ES_USER: username
• ES_PASS: password

Or create a config file such as this:

clusters:
  default:
    uri: https://es.foo.bar:9200/
    user: elastic
    pass: 123456
  other:
    uri: https://myes.foo:9200/
    user: elastic
    pass: asdasdasd

and specify it with -c configfile. You may also put clusters into a default config file in ~/.config/esctl/config.yaml. In this case you can omit -c ....

If you want to work on a specific cluster, specify its name with the global -C option.

Installation

The tool does not have any dependencies. Just download the binary for your platform from the releases page and you're good to go.

Installation using a pre-compiled binary

You can use stew to install esctl:

stew install https://codeberg.org/scip/esctl

Or go to the latest release page and look for your OS and platform. There are two options to install the binary:

Directly download the binary for your platform, e.g. esctl-linux-amd64-0.0.2, rename it to esctl (or whatever you like more!) and put it into your bin dir (e.g. $HOME/bin or as root to /usr/local/bin).

Be sure to verify the signature of the binary file. For this also download the matching esctl-linux-amd64-0.0.2.sha256 file and:

cat esctl-linux-amd64-0.0.2.sha25 && sha256sum esctl-linux-amd64-0.0.2

You should see the same SHA256 hash.

You may also download a binary tarball for your platform, e.g. esctl-linux-amd64-0.0.2.tar.gz, unpack and install it. GNU Make is required for this:

tar xvfz esctl-linux-amd64-0.0.2.tar.gz
cd esctl-linux-amd64-0.0.2
sudo make install

Installation from source

Check out the repository and execute go build, then copy the compiled binary to your $PATH.

Or, if you have GNU Make installed, just execute:

make
sudo make install

Development

To test completion

Add the flag --generate-shell-completion to any command, e.g.:

./esctl role show --generate-shell-completion
machine_learning_admin
rollup_admin
editor
reporting_user
snapshot_user
fcn_admin
machine_learning_user
kibana_system
beats_admin
kibana_user
fcns_space
transport_client
transform_user
[..]

Report bugs

Please open an issue. Thanks!

License

This work is licensed under the terms of the General Public Licens version 3.

Author

Copyleft (c) 2026 Thomas von Dein