mirror of
https://codeberg.org/scip/esctl.git
synced 2026-08-24 12:54:18 +02:00
293 lines
10 KiB
Markdown
293 lines
10 KiB
Markdown
[](https://ci.codeberg.org/repos/16999)
|
|
[](CONTRIBUTING.md)
|
|
[](https://codeberg.org/scip/esctl/blob/master/LICENSE)
|
|
[](https://goreportcard.com/report/codeberg.org/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
|