esctl/README.md

[![status-badge](https://ci.codeberg.org/api/badges/16999/status.svg)](https://ci.codeberg.org/repos/16999)

# 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:
  ```console
  esctl doc add -i foo '{"title":"curry in a hurry", "message":"australian thai"}'
  ```

## Usage

Command tree:

```console
 api
     list
     repl
     show
 ccr
     follower
         add
         delete
         pause
         renew
         resume
         show
         unfollow
     info
     pause
     resume
     status
 cluster
     list
     settings
         list
         set
     status
 datastream
     create
     delete
     list
     rollover
     show
 debug
 doc
     add
     delete
     show
 help
 help-jsonpath
 ilm
     create
     list
     retry
     show
     status
 index
     alias
         create
         delete
         list
         rollover
     allocation
     close
     create
     delete
     fields
     ilm
     list
     modify
     show
     template
         create
         delete
         list
         modify
         show
 node
     list
     show
 role
     diff
     list
     show
 search
 shard
     list
     show
 snapshot
     list
     show
 task
     cancel
     list
 version
```

Configure `esctl` with environment variables:

- `ES_URI`: elasticsearch uri
- `ES_USER`: username
- `ES_PASS`: password

Or create a config file such as this:

```yaml
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](https://github.com/marwanhawari/stew) to install esctl:
```default
stew install https://codeberg.org/scip/esctl
```

Or go to the [latest release page](https://codeberg.org/scip/esctl/releases/)
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:

```shell
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:
   
```shell
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:

```default
make
sudo make install
```

# Development

## To test completion

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

```console
./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](https://codeberg.org/scip/esctl/issues). Thanks!

# License

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

# Author

Copyleft (c) 2026 Thomas von Dein