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 lsshows 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. Automatic rollover of aliases supported.
- Index template management: create, modify, delete etc
- Index alias management: create, modify, delete etc
- Node management: only list nodes yet.
- Shard management: only list shards yet.
- Snapshot management: only list snapshots yet.
- ILM management: list, create, delete etc.
- Task management: list and cancel tasks
- Role management: only list roles yet. There's also a
role diffsubcommand, which is for internal use. It can be used to verify if role defs in a CSV match the deployed roles. - API documentation (
api listandapi show <path>) with interactive markdown pager for endpoint documentation. - 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
jqis 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 fooand then insert docs into it for search experiments:esctl doc add -i foo '{"title":"curry in a hurry", "message":"australian thai"}'
Usage
Command tree:
api - api access and documentation
list - list index of API calls
show - show an API doc
repl - interactive API repl
ccr - manage cross cluster replication
status - cross cluster replication status (yaml config with 2 clusters required)
pause - pause shard allocation
resume - resume shard allocation
follower - manage ccr follower indices
show - show ccr follower index details
add - add ccr follower index
delete - delete ccr follower index
unfollow - unfollow ccr follower index
pause - pause ccr index to follow
resume - resume ccr index to follow
renew - renew ccr follower index
info - show ccr remote info
cluster - manage cluster[s]
status - show cluster status
switch - set current elasticsearch cluster
list - list configured clusters
settings - cluster settings management
list - show cluster settings
set - set|update cluster settings
datastream - manage data streams
list - list indicies
show - show details about an data stream
create - create a new data stream
delete - delete a data stream
rollover - roll over a data stream
doc - manage documents
add - add JSON document index
show - show a JSON document
delete - delete JSON document[s] from index[es]
ilm - manage index lifecycle
retry - retry applying an ILM profile to an index
status - get the current index lifecycle management status
list - list index lifecycle policies
show - show details about an index lifecycle policy
create - create a index lifecycle policy
index - manage indicies
list - list indicies
show - show details about an index
create - create a new index
delete - delete an index
close - close an index
allocation - explain index allocation
modify - modify an index
fields - show info about field capabilities
ilm - show ilm status
alias - manage index aliases
create - create an index alias
list - list index aliases
delete - delete an index alias
rollover - roll over an index alias
template - manage index templates
list - list index templates
show - show details about an index template
create - create a new index template
modify - modify a new index template
delete - delete an index template
node - manage nodes
list - list nodes
show - show details about a node
role - manage roles
list - list roles
show - show details about a role
diff - show differences between roles and CSV baseline
search - search within an index
shard - manage shards
list - list shards
show - show details about a shard
snapshot - manage snapshots
list - list snapshots
show - show details about a snapshot
task - manage tasks
list - list tasks
cancel - cancel running task
version - show esctl version information
debug - developer only
help-jsonpath - show jsonpath help
completion - Output shell completion script for bash, zsh, fish, or Powershell
bash - Output bash completion script
zsh - Output zsh completion script
fish - Output fish completion script
pwsh - Output pwsh completion script
Configure esctl with environment variables:
ES_URI: elasticsearch uriES_USER: usernameES_PASS: password
Or create a config file such as this:
clusters:
foobar:
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, you need to make it the current default one. You can either manually configure it in the config:
clusters:
foobar:
uri: https://es.foo.bar:9200/
user: elastic
pass: 123456
default: true
or - if the cluster already exists in the config - issue this command:
esctl cluster switch foobar
You may also temporary set a cluster as the current default with the
global -C option.
The following rules apply for default cluster selection:
- If there's just one cluster configured (either via environment variables or config), this one will be selected.
- If there is one cluster configured with the
defaultflagtrue, use this one.
Use esctl cluster ls to check status and see which one would be used.
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