add explain index allocation

TODO.md

@@ -2,6 +2,10 @@
 - [ES API docs](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get)
 
 - Fix index names custom completion
+  https://github.com/urfave/cli/issues/2332
+  https://github.com/urfave/cli/issues/2333
+  
 - index show: add more details, see screenshots
+
 - add shard explain, aka:
   get /_cluster/allocation/explain {"index":"yourindex", "primary": true, "shard":0}

cmd/index.go

@@ -38,6 +38,7 @@ func Index(conf *cfg.Config) *cli.Command {
 			IndexCreate(conf),
 			IndexDelete(conf),
 			IndexClose(conf),
+			IndexAllocation(conf),
 		},
 	}
 }
@@ -75,6 +76,33 @@ func IndexList(conf *cfg.Config) *cli.Command {
 	}
 }
 
+func IndexAllocation(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "allocation",
+		Aliases: []string{"a"},
+		Usage:   "explain index allocation",
+
+		Flags: []cli.Flag{
+			&cli.IntFlag{
+				Name:        "shard",
+				Usage:       "shard number to explain for",
+				Destination: &conf.Shards,
+				Aliases:     []string{"s"},
+			},
+			&cli.BoolFlag{
+				Name:        "primary",
+				Usage:       "explain primary allocation (default true)",
+				Destination: &conf.Primary,
+				Aliases:     []string{"p"},
+			},
+		},
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			return es.IndexAllocation(conf, cmd.Args().Get(0))
+		},
+	}
+}
+
 func IndexShow(conf *cfg.Config) *cli.Command {
 	return &cli.Command{
 		Name:    "show",
@@ -83,7 +111,6 @@ func IndexShow(conf *cfg.Config) *cli.Command {
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			return es.IndexShow(conf, cmd.Args().Get(0))
-
 		},
 
 		// FIXME: doesn't work at all

go.mod

@@ -17,32 +17,36 @@ module codeberg.org/scip/esctl
 go 1.25.0
 
 require (
-	github.com/alecthomas/repr v0.5.2 // indirect
+	github.com/alecthomas/repr v0.5.2
+	github.com/chzyer/readline v1.5.1
+	github.com/dustin/go-humanize v1.0.1
+	github.com/elastic/elastic-transport-go/v8 v8.11.0
+	github.com/elastic/go-elasticsearch/v9 v9.3.4
+	github.com/fatih/color v1.19.0
+	github.com/mattn/go-isatty v0.0.22
+	github.com/olekukonko/tablewriter v1.1.4
+	github.com/tlinden/yadu v0.1.3
+	github.com/urfave/cli/v3 v3.9.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/chzyer/readline v1.5.1 // indirect
 	github.com/clipperhouse/displaywidth v0.10.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.6.0 // indirect
-	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/elastic/elastic-transport-go/v8 v8.11.0 // indirect
-	github.com/elastic/go-elasticsearch/v9 v9.3.2 // indirect
-	github.com/fatih/color v1.19.0 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/lmittmann/tint v1.1.3 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.21 // indirect
+	github.com/mattn/go-runewidth v0.0.23 // indirect
-	github.com/mattn/go-runewidth v0.0.19 // indirect
 	github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 // indirect
 	github.com/olekukonko/errors v1.2.0 // indirect
-	github.com/olekukonko/ll v0.1.6 // indirect
+	github.com/olekukonko/ll v0.1.8 // indirect
-	github.com/olekukonko/tablewriter v1.1.4 // indirect
-	github.com/tlinden/yadu v0.1.3 // indirect
-	github.com/urfave/cli/v3 v3.8.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/otel v1.35.0 // indirect
 	go.opentelemetry.io/otel/metric v1.35.0 // indirect
 	go.opentelemetry.io/otel/trace v1.35.0 // indirect
 	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f // indirect
 	golang.org/x/sys v0.42.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -18,6 +18,8 @@ github.com/elastic/elastic-transport-go/v8 v8.11.0 h1:taYmqC2M6+fZt/+W+ENYh/W5L9
 github.com/elastic/elastic-transport-go/v8 v8.11.0/go.mod h1:DZQ0szCNywc9F+C9l/Kkd4n69SvJVj0I3yK1Of7s3l8=
 github.com/elastic/go-elasticsearch/v9 v9.3.2 h1:nvtvfN/Gsp/rzUPz/9yILwDAsYJ3s5L0VmhR16zPKCA=
 github.com/elastic/go-elasticsearch/v9 v9.3.2/go.mod h1:ubKUMJCJbX5V/gW5MIn2NQZyaEZ61ubXwJmD5UMNrM8=
+github.com/elastic/go-elasticsearch/v9 v9.3.4 h1:vnqXl6jnlA+ZwlfRaKF9BR9woZC1KSB17gtyvgf8zVU=
+github.com/elastic/go-elasticsearch/v9 v9.3.4/go.mod h1:ubKUMJCJbX5V/gW5MIn2NQZyaEZ61ubXwJmD5UMNrM8=
 github.com/fatih/color v1.16.0 h1:zmkK9Ngbjj+K0yRhTVONQh1p/HknKYSlNT+vZCzyokM=
 github.com/fatih/color v1.16.0/go.mod h1:fL2Sau1YI5c0pdGEVCbKQbLXB6edEj1ZgiY4NijnWvE=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
@@ -29,6 +31,8 @@ github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/goccy/go-json v0.10.6 h1:p8HrPJzOakx/mn/bQtjgNjdTcN+/S6FcG2CTtQOrHVU=
+github.com/goccy/go-json v0.10.6/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/lmittmann/tint v1.1.3 h1:Hv4EaHWXQr+GTFnOU4VKf8UvAtZgn0VuKT+G0wFlO3I=
 github.com/lmittmann/tint v1.1.3/go.mod h1:HIS3gSy7qNwGCj+5oRjAutErFBl4BzdQP6cJZ0NfMwE=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
@@ -38,20 +42,28 @@ github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stg
 github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
 github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
 github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
+github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
 github.com/mattn/go-runewidth v0.0.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
 github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
+github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 h1:zrbMGy9YXpIeTnGj4EljqMiZsIcE09mmF8XsD5AYOJc=
 github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6/go.mod h1:rEKTHC9roVVicUIfZK7DYrdIoM0EOr8mK1Hj5s3JjH0=
 github.com/olekukonko/errors v1.2.0 h1:10Zcn4GeV59t/EGqJc8fUjtFT/FuUh5bTMzZ1XwmCRo=
 github.com/olekukonko/errors v1.2.0/go.mod h1:ppzxA5jBKcO1vIpCXQ9ZqgDh8iwODz6OXIGKU8r5m4Y=
 github.com/olekukonko/ll v0.1.6 h1:lGVTHO+Qc4Qm+fce/2h2m5y9LvqaW+DCN7xW9hsU3uA=
 github.com/olekukonko/ll v0.1.6/go.mod h1:NVUmjBb/aCtUpjKk75BhWrOlARz3dqsM+OtszpY4o88=
+github.com/olekukonko/ll v0.1.8 h1:ysHCJRGHYKzmBSdz9w5AySztx7lG8SQY+naTGYUbsz8=
+github.com/olekukonko/ll v0.1.8/go.mod h1:RPRC6UcscfFZgjo1nulkfMH5IM0QAYim0LfnMvUuozw=
 github.com/olekukonko/tablewriter v1.1.4 h1:ORUMI3dXbMnRlRggJX3+q7OzQFDdvgbN9nVWj1drm6I=
 github.com/olekukonko/tablewriter v1.1.4/go.mod h1:+kedxuyTtgoZLwif3P1Em4hARJs+mVnzKxmsCL/C5RY=
 github.com/tlinden/yadu v0.1.3 h1:5cRCUmj+l5yvlM2irtpFBIJwVV2DPEgYSaWvF19FtcY=
 github.com/tlinden/yadu v0.1.3/go.mod h1:l3bRmHKL9zGAR6pnBHY2HRPxBecf7L74BoBgOOpTcUA=
 github.com/urfave/cli/v3 v3.8.0 h1:XqKPrm0q4P0q5JpoclYoCAv0/MIvH/jZ2umzuf8pNTI=
 github.com/urfave/cli/v3 v3.8.0/go.mod h1:ysVLtOEmg2tOy6PknnYVhDoouyC/6N42TMeoMzskhso=
+github.com/urfave/cli/v3 v3.9.0 h1:AV9lIiPv3ukYnxunaCUsHnEozptYmDN2F0+yWqLMn/c=
+github.com/urfave/cli/v3 v3.9.0/go.mod h1:ysVLtOEmg2tOy6PknnYVhDoouyC/6N42TMeoMzskhso=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
 go.opentelemetry.io/otel v1.35.0 h1:xKWKPxrxB6OtMCbmMY021CqC45J+3Onta9MqjhnusiQ=

pkg/cfg/config.go

@@ -31,7 +31,7 @@ import (
 )
 
 const (
-	Version string = `v0.0.9`
+	Version string = `v0.0.10`
 )
 
 type Cluster struct {
@@ -47,14 +47,16 @@ type Config struct {
 	DefaultCluster                 *Cluster
 	Index                          string   // index: -i
 	Failed, Partials               bool     // index: flags
-	Shards, Replicas               int      // index create: -s -r
+	Shards, Replicas               int      // index create+allocation: -s -r
 	Wait                           bool     // index create: -w
+	Primary                        bool     // index allocation: -p
 	From, To, MaxItems             int      // search: flags
 	Filter                         []string // search: -F
 	Exclude                        string   // cluster compare: -e (regexp)
 	All, Verbose                   bool     // cluster status: -a -v
 	Persistent, Transient, Default bool     // -p -t -D cluster settings set
 	Force                          bool     // ccr follower renew: -f
+	HaveJQ                         bool     // determined at runtime by ourselfes
 }
 
 func NewConfig() *Config {
@@ -110,6 +112,8 @@ func (conf *Config) Init() error {
 		}
 	}
 
+	conf.HaveJQ = isJQinstalled()
+
 	conf.PrintDebug()
 
 	return nil

pkg/cfg/jq.go

@@ -0,0 +1,38 @@
+/*
+Copyright © 2026 Thomas von Dein
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package cfg
+
+import (
+	"context"
+	"os/exec"
+	"strings"
+)
+
+func isJQinstalled() bool {
+	cmd := exec.CommandContext(context.Background(), "jq", "-h")
+	out, err := cmd.Output()
+	if err != nil {
+		return false
+	}
+
+	if strings.Contains(string(out), "Usage") {
+		return true
+	}
+
+	return false
+}

pkg/es/ccr.go

@@ -116,7 +116,7 @@ func CcrRemoteInfo(conf *cfg.Config, index string) error {
 	}
 
 	table := NewTable(2, 5)
-	table.Addheaders("field", "value")
+	table.Addheaders("ccr remote property", "value")
 
 	table.entries = [][]string{
 		{"Remote Cluster", remote},

pkg/es/ccr_follower.go

@@ -176,7 +176,7 @@ func CcrFollowerShow(conf *cfg.Config, index string) error {
 	follower := res.Indices[0].Shards[0]
 
 	table := NewTable(2, 9)
-	table.Addheaders("field", "value")
+	table.Addheaders("ccr follower property", "value")
 
 	table.entries = [][]string{
 		{"name", index},

pkg/es/index.go

@@ -111,7 +111,7 @@ func IndexShow(conf *cfg.Config, index string) error {
 	slog.Debug("ES result", "index", res)
 
 	table := NewTable(2, 5)
-	table.Addheaders("field", "value")
+	table.Addheaders("index property", "value")
 
 	ts, err := strconv.ParseInt(res[index].Settings.Index.CreationDate.(string), 10, 64)
 	if err != nil {
@@ -216,3 +216,52 @@ func IndexClose(conf *cfg.Config, index string) error {
 
 	return nil
 }
+
+func IndexAllocation(conf *cfg.Config, index string) error {
+	if index == "" {
+		return fmt.Errorf("no index specified")
+	}
+
+	alloc := conf.DefaultCluster.ES.Cluster.AllocationExplain().
+		Index(index).
+		Primary(conf.Primary).
+		Shard(conf.Shards)
+
+	res, err := alloc.Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to get index allocation explain: %s", err)
+	}
+
+	slog.Debug("ES result", "index", res)
+
+	currentNode := res.CurrentNode
+
+	table := NewTable(2, 10)
+	table.Addheaders("index allocation setting", "value")
+
+	roles := make([]string, len(currentNode.Roles))
+	for idx, role := range currentNode.Roles {
+		roles[idx] = role.Name
+	}
+
+	table.entries = [][]string{
+		{"Index", index},
+		{"Current node", currentNode.Name},
+		{"Current k8s node", currentNode.Attributes["k8s_node_name"]},
+		{"Current node address", currentNode.TransportAddress},
+		{"Current node id", currentNode.Id},
+		{"Current node weight", fmt.Sprintf("%d", currentNode.WeightRanking)},
+		{"Current node roles", strings.Join(roles, ",")},
+		{"Can rebalance cluster", res.CanRebalanceCluster.Name},
+		{"Can rebalance to another node", res.CanRebalanceToOtherNode.Name},
+		{"Can remain on current node", res.CanRemainOnCurrentNode.Name},
+	}
+
+	if err := table.PrintMarkdown(); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/es/repl.go

@@ -18,6 +18,7 @@ package es
 
 import (
 	"bytes"
+	"context"
 	"crypto/tls"
 	"encoding/base64"
 	"encoding/json"
@@ -25,6 +26,7 @@ import (
 	"io"
 	"net/http"
 	"os"
+	"os/exec"
 	"slices"
 	"strings"
 
@@ -74,9 +76,30 @@ func CallAPI(conf *cfg.Config, input []string) error {
 		return fmt.Errorf("failed to read response body: %s", err)
 	}
 
+	return prettyfiJson(conf, body)
+}
+
+func prettyfiJson(conf *cfg.Config, raw []byte) error {
+	if conf.HaveJQ {
+		cmd := exec.CommandContext(context.Background(), "jq", "-C")
+		cmd.Stdin = bytes.NewReader(raw)
+
+		var out bytes.Buffer
+		cmd.Stdout = &out
+
+		err := cmd.Run()
+		if err != nil {
+			return err
+		}
+
+		fmt.Println(out.String())
+
+		return nil
+	}
+
 	var pretty bytes.Buffer
-	error := json.Indent(&pretty, body, "", "\t")
+	err := json.Indent(&pretty, raw, "", "\t")
-	if error != nil {
+	if err != nil {
 		return fmt.Errorf("json parse error: %s", err)
 	}
 

pkg/es/snapshot.go

@@ -117,7 +117,7 @@ func SnapshotShow(conf *cfg.Config, snapshot string) error {
 	}
 
 	table := NewTable(2, 17)
-	table.Addheaders("field", "value")
+	table.Addheaders("snapshot property", "value")
 
 	snap := res.Snapshots[0]