esctl

Elasticsearch Cluster Manager — manage multiple local Elasticsearch clusters from the CLI.

Run isolated ES clusters per project, switch between them instantly, and never touch config files manually.

esctl start myapp
esctl list
esctl stop myapp

---

Install

curl (recommended)

curl -fsSL https://raw.githubusercontent.com/prvn-codes/esctl/main/bin/esctl \
-o /usr/local/bin/esctl && chmod +x /usr/local/bin/esctl

Homebrew

brew tap prvn-codes/tap
brew trust prvn-codes/tap # required for third-party taps
brew install esctl

Homebrew requires trusting third-party taps before installing. This is a one-time step.

---

Requirements

Tool	Required	Notes
jq	Yes	Auto-installed via Homebrew if missing
curl	No	Used for HTTP readiness checks
Elasticsearch	Yes	Any version — see Auto-detect

---

Auto-detect

esctl finds your Elasticsearch binary automatically in this order:

1. $ESCTL_ES_BIN env var
2. evm installations in ~/.evm (latest version picked automatically)
3. elasticsearch on your $PATH
4. Common paths: /usr/local/bin, /opt/homebrew/bin, /usr/share/elasticsearch/bin

Works with evm, Homebrew, manual installs — anything.

---

Usage

esctl <command> [cluster]
COMMANDS
start [cluster] Start a cluster (or all if omitted); --verbose to stream logs
stop [cluster] Stop a cluster (or all if omitted)
restart [cluster] Restart a cluster (or all if omitted); --verbose to stream logs
status [cluster] Show cluster status
list List all clusters with live status
add Add a new cluster (interactive)
edit <cluster> Edit a cluster's configuration
remove <cluster> Remove a cluster
logs <cluster> Tail cluster logs (-f to follow)
setup Configure environment interactively
import Detect and import running clusters
doctor Check dependencies and configuration
config Show config file path and contents
version Show version

Examples

# First time setup — check your environment
esctl doctor
# Add a cluster for your project
esctl add
# → prompts for name, port, directories, ES binary# Start it
esctl start myapp
# Start with live log output
esctl start myapp --verbose
# See all clusters and their live status
esctl list
# Tail logs for a running cluster
esctl logs myapp
esctl logs -f myapp # follow in real time# Edit a cluster's config
esctl edit myapp
# Stop everything
esctl stop

Live status table

CLUSTER NODE PORT STATUS UPTIME MEMORY HTTP ACCESS URL
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
myapp node-myapp 9200 RUNNING 12:04 1GB OK http://localhost:9200
staging node-staging 9201 STOPPED N/A N/A N/A —
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

---

Configuration

Config is stored at ~/.esctl/clusters.json. You can override the path:

export ESCTL_CONFIG=~/my-custom-config.json

Each cluster stores:

{
"name": "myapp",
"node_name": "node-myapp",
"port": 9200,
"data_dir": "$HOME/.esctl/data/myapp",
"logs_dir": "$HOME/.esctl/logs/myapp",
"es_bin": null
}

es_bin is null by default (auto-detect). Set it per-cluster to pin a specific ES version:

esctl edit myapp
# → ES binary: /path/to/specific/elasticsearch

Environment variables

Variable	Default	Description
ESCTL_ES_BIN	—	Path to Elasticsearch binary (global override)
ESCTL_CONFIG	~/.esctl/clusters.json	Config file location

---

Updating

brew upgrade esctl

---

License

MIT