esctl/README.md

[![status-badge](https://ci.codeberg.org/api/badges/16999/status.svg)](https://ci.codeberg.org/repos/16999)
[![humanmande](https://img.shields.io/badge/human-made-green)](CONTRIBUTING.md)
[![License](https://img.shields.io/badge/license-GPL-blue.svg)](https://codeberg.org/scip/esctl/blob/master/LICENSE)
[![Go Report Card](https://goreportcard.com/badge/codeberg.org/scip/esctl)](https://goreportcard.com/report/codeberg.org/scip/esctl)
[![Latest Release](https://flat.badgen.net/codeberg/release/scip/esctl)](https://codeberg.org/scip/esctl/releases)

# 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. 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 diff`
  subcommand, which is for internal use. It can be used to verify if
  role defs in a CSV match the deployed roles.
- API  documentation   (`api  list`  and  `api   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 `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                   - 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 uri
- `ES_USER`: username
- `ES_PASS`: password

Or create a config file such as this:

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

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

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

1. If there's just one cluster configured (either via environment
   variables or config), this one will be selected.
2. If there is one cluster configured with the `default` flag `true`,
   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](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