marshall explain output only in debug mode

README.md

@@ -4,6 +4,48 @@
 
 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:
@@ -34,6 +76,7 @@ Command tree:
      delete
      show
  help
+ help-jsonpath
  index
      alias
          create
@@ -52,6 +95,7 @@ Command tree:
      show
  repl
  role
+     diff
      list
      show
  search
@@ -91,10 +135,6 @@ can omit `-c ...`.
 If you want to  work on a specific cluster, specify  its name with the
 global `-C` option.
 
-## Introduction
-
-FIXME
-
 ## Installation
 
 The tool does not have any dependencies.  Just download the binary for
@@ -145,6 +185,30 @@ 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!

TODO.md

@@ -1,33 +1,13 @@
 - [Go client docs](https://www.elastic.co/docs/reference/elasticsearch/clients/go/typed-api)
 - [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}
 
 
-- add validate:
+- add datastream support:
+  https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-data-stream
   
-> GET /mock/_validate/query?rewrite=true {"from":0,"query":{"bool":{"must":[{"match_all":{}}]}},"size":20,"sort":[{"name":{"order":"desc"}}]}
+  also exclude data stream backing indices from index ls
-{
-  "valid": false
-}
-
-- add explain to search (maybe option -e)
-
-> GET /mock/_explain/1780043878 {"query":{"bool":{"must":[{"match_all":{}}]}}}
-{
-  "_index": "mock",
-  "_id": "1780043878",
-  "matched": true,
-  "explanation": {
-    "value": 1.0,
-    "description": "*:*",
-    "details": []
-  }
-}

cmd/ccr.go

@@ -47,6 +47,7 @@ func CcrStatus(conf *cfg.Config) *cli.Command {
 		Name:      "status",
 		Aliases:   []string{"st"},
 		Usage:     "cross cluster replication status (yaml config with 2 clusters required)",
+		UsageText: "status <leader> <follower>",
 
 		Flags: []cli.Flag{
 			&cli.StringFlag{
@@ -57,6 +58,10 @@ func CcrStatus(conf *cfg.Config) *cli.Command {
 			},
 		},
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeCluster(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			leader := cmd.Args().Get(0)
 			follower := cmd.Args().Get(1)
@@ -109,6 +114,10 @@ func CcrRemoteInfo(conf *cfg.Config) *cli.Command {
 		Usage:     "show ccr remote info",
 		UsageText: "info [options] [<index>]",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			return es.CcrRemoteInfo(conf, cmd.Args().Get(0))
 		},

cmd/ccr_follower.go

@@ -59,6 +59,10 @@ func CcrFollowerRenew(conf *cfg.Config) *cli.Command {
 			},
 		},
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -77,6 +81,10 @@ func CcrFollowerResume(conf *cfg.Config) *cli.Command {
 		Usage:     "resume ccr index to follow",
 		UsageText: "resume [options] <index>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -95,6 +103,10 @@ func CcrFollowerPause(conf *cfg.Config) *cli.Command {
 		Usage:     "pause ccr index to follow",
 		UsageText: "pause [options] <index>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -113,6 +125,10 @@ func CcrFollowerUnfollow(conf *cfg.Config) *cli.Command {
 		Usage:     "unfollow ccr follower index",
 		UsageText: "unfollow [options] <index>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -141,6 +157,10 @@ func CcrFollowerAdd(conf *cfg.Config) *cli.Command {
 			},
 		},
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -160,6 +180,10 @@ func CcrFollowerDelete(conf *cfg.Config) *cli.Command {
 		Usage:     "delete ccr follower index",
 		UsageText: "delete <index>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 
@@ -180,6 +204,10 @@ func CcrFollowerShow(conf *cfg.Config) *cli.Command {
 		Usage:     "show ccr follower index details",
 		UsageText: "show <index>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			args := cmd.Args()
 

cmd/completion.go

@@ -0,0 +1,89 @@
+/*
+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 cmd
+
+import (
+	"fmt"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"codeberg.org/scip/esctl/pkg/es"
+
+	"github.com/urfave/cli/v3"
+)
+
+func completeIndex(cmd *cli.Command) {
+	if cmd.NArg() > 0 {
+		return
+	}
+
+	// FIXME: config should load from root.Before(), see https://github.com/urfave/cli/issues/2348
+	// workaround: load it directly here
+	conf := cfg.NewConfig()
+	if err := conf.Init(); err != nil {
+		return
+	}
+
+	indices, err := es.IndexNames(conf)
+	if err != nil {
+		return
+	}
+
+	for _, index := range indices {
+		fmt.Println(index)
+	}
+
+}
+
+func completeRole(cmd *cli.Command) {
+	if cmd.NArg() > 0 {
+		return
+	}
+
+	// FIXME: config should load from root.Before(), see https://github.com/urfave/cli/issues/2348
+	// workaround: load it directly here
+	conf := cfg.NewConfig()
+	if err := conf.Init(); err != nil {
+		return
+	}
+
+	roles, err := es.RoleNames(conf)
+	if err != nil {
+		return
+	}
+
+	for _, role := range roles {
+		fmt.Println(role)
+	}
+
+}
+
+func completeCluster(cmd *cli.Command) {
+	if cmd.NArg() > 0 {
+		return
+	}
+
+	// FIXME: config should load from root.Before(), see https://github.com/urfave/cli/issues/2348
+	// workaround: load it directly here
+	conf := cfg.NewConfig()
+	if err := conf.Init(); err != nil {
+		return
+	}
+
+	for cluster := range conf.Clusters {
+		fmt.Println(cluster)
+	}
+}

cmd/doc.go

@@ -89,19 +89,9 @@ func DocShow(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Path,
 				Aliases:     []string{"p"},
 			},
-			&cli.BoolFlag{
-				Name:        "help-jsonpath",
-				Usage:       "show jsonPath help",
-				Destination: &conf.Subhelp,
-				Aliases:     []string{"H"},
-			},
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if args.Len() != 1 {
@@ -161,10 +151,6 @@ func DocDelete(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if args.Len() == 0 && !conf.All {

cmd/index.go

@@ -133,22 +133,8 @@ func IndexShow(conf *cfg.Config) *cli.Command {
 			return es.IndexShow(conf, cmd.Args().Get(0))
 		},
 
-		// FIXME: doesn't work at all
-		// FIXME: also it would ONLY work if the user uses env vars, -C would not be
-		//        there when the completion output is being generated
 		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
-			if cmd.NArg() > 0 {
+			completeIndex(cmd)
-				return
-			}
-
-			indices, err := es.IndexNames(conf)
-			if err != nil {
-				return
-			}
-
-			for _, index := range indices {
-				fmt.Println(index)
-			}
 		},
 	}
 }
@@ -200,6 +186,11 @@ func IndexDelete(conf *cfg.Config) *cli.Command {
 		Name:      "delete",
 		Aliases:   []string{"rm"},
 		Usage:     "delete an index",
+		UsageText: "delete <index>",
+
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
@@ -216,6 +207,11 @@ func IndexClose(conf *cfg.Config) *cli.Command {
 	return &cli.Command{
 		Name:      "close",
 		Usage:     "close an index",
+		UsageText: "close <index>",
+
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
@@ -234,6 +230,10 @@ func IndexModify(conf *cfg.Config) *cli.Command {
 		Usage:     "modify an index",
 		UsageText: "modify <index[,index,...]|_all>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Flags: []cli.Flag{
 			&cli.IntFlag{
 				Name:        "replicas",
@@ -260,6 +260,31 @@ func IndexFields(conf *cfg.Config) *cli.Command {
 		Usage:     "show info about field capabilities",
 		UsageText: "index fields <index>",
 
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:        "aggretable",
+				Usage:       "include only aggretable fields",
+				Destination: &conf.Aggretable,
+				Aliases:     []string{"a"},
+			},
+			&cli.BoolFlag{
+				Name:        "searchable",
+				Usage:       "include only searchable fields",
+				Destination: &conf.Searchable,
+				Aliases:     []string{"s"},
+			},
+			&cli.StringSliceFlag{
+				Name:        "type",
+				Usage:       "show only fields of this type",
+				Destination: &conf.Filter,
+				Aliases:     []string{"t"},
+			},
+		},
+
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
 			if index == "" {

cmd/index_alias.go

@@ -36,6 +36,7 @@ func IndexAlias(conf *cfg.Config) *cli.Command {
 			IndexAliasCreate(conf),
 			IndexAliasList(conf),
 			IndexAliasDelete(conf),
+			// FIXME: implement IndexAliasShow + IndexAliasAdd
 			//IndexAliasShow(conf),
 			//IndexAliasAdd(conf), // see https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-update-aliases
 		},
@@ -49,6 +50,10 @@ func IndexAliasCreate(conf *cfg.Config) *cli.Command {
 		Usage:     "create an index alias",
 		UsageText: "create <index> <alias>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
 			alias := cmd.Args().Get(1)
@@ -69,6 +74,10 @@ func IndexAliasDelete(conf *cfg.Config) *cli.Command {
 		Usage:     "delete an index alias",
 		UsageText: "delete <index> <alias>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeIndex(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
 			alias := cmd.Args().Get(1)

cmd/node.go

@@ -58,6 +58,7 @@ func NodeShow(conf *cfg.Config) *cli.Command {
 		UsageText: "show [options] <node>",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
+			// FIXME: implement es.NodeShow()
 			// return es.NodeShow(conf, cmd.Args().Get(0))
 			return nil
 		},

cmd/roles.go

@@ -67,6 +67,10 @@ func RoleShow(conf *cfg.Config) *cli.Command {
 		Usage:     "show details about a role",
 		UsageText: "show [options] <role>",
 
+		ShellComplete: func(ctx context.Context, cmd *cli.Command) {
+			completeRole(cmd)
+		},
+
 		Action: func(ctx context.Context, cmd *cli.Command) error {
 			index := cmd.Args().Get(0)
 			if index == "" {

cmd/root.go

@@ -98,6 +98,7 @@ func Main() int {
 			Version(conf),
 			Debug(conf),
 			Roles(conf),
+			HelpJsonPath(conf),
 		},
 
 		Before: func(ctx context.Context, cmd *cli.Command) (context.Context, error) {
@@ -119,6 +120,45 @@ func Main() int {
 	return Finish(cmd.Run(context.Background(), os.Args))
 }
 
+func HelpJsonPath(conf *cfg.Config) *cli.Command {
+	msg := `jsonPath usage:
+
+name.last          >> "Anderson"
+age                >> 37
+children           >> ["Sara","Alex","Jack"]
+children.#         >> 3
+children.1         >> "Alex"
+child*.2           >> "Jack"
+c?ildren.0         >> "Sara"
+fav\.movie         >> "Deer Hunter"
+friends.#.first    >> ["Dale","Roger","Jane"]
+friends.1.last     >> "Craig"
+
+You can also  query an array for  the first match by  using #(...), or
+find all matches  with #(...)#. Queries support the ==,  !=, <, <=, >,
+>= comparison operators  and the simple pattern matching  % (like) and
+!% (not like) operators. Eg:
+
+friends.#(last=="Murphy").first    >> "Dale"
+friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
+friends.#(age>45)#.last            >> ["Craig","Murphy"]
+friends.#(first%"D*").last         >> "Murphy"
+friends.#(first!%"D*").last        >> "Craig"
+friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]
+
+Documentation: https://github.com/tidwall/gjson/blob/master/SYNTAX.md`
+
+	return &cli.Command{
+		Name:  "help-jsonpath",
+		Usage: "show jsonpath help",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			_, err := fmt.Println(msg)
+			return err
+		},
+	}
+}
+
 func Version(conf *cfg.Config) *cli.Command {
 	return &cli.Command{
 		Name:  "version",

cmd/search.go

@@ -18,7 +18,6 @@ package cmd
 
 import (
 	"context"
-	"fmt"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"codeberg.org/scip/esctl/pkg/es"
@@ -113,12 +112,6 @@ func Search(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Ascending,
 				Aliases:     []string{"a"},
 			},
-			&cli.BoolFlag{
-				Name:        "help-jsonpath",
-				Usage:       "show jsonPath help",
-				Destination: &conf.Subhelp,
-				Aliases:     []string{"H"},
-			},
 			&cli.BoolFlag{
 				Name:        "tail",
 				Usage:       "follow search live, like tail -f",
@@ -131,13 +124,21 @@ func Search(conf *cfg.Config) *cli.Command {
 				Destination: &conf.Or,
 				Aliases:     []string{"O"},
 			},
+			&cli.BoolFlag{
+				Name:        "validate",
+				Usage:       "validate search query",
+				Destination: &conf.Validate,
+				Aliases:     []string{"v"},
+			},
+			&cli.BoolFlag{
+				Name:        "explain",
+				Usage:       "explain search query",
+				Destination: &conf.Explain,
+				Aliases:     []string{"e"},
+			},
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if conf.Subhelp {
-				return showJsonPathHelp()
-			}
-
 			args := cmd.Args()
 
 			if conf.To == -1 {
@@ -148,34 +149,3 @@ func Search(conf *cfg.Config) *cli.Command {
 		},
 	}
 }
-
-func showJsonPathHelp() error {
-	_, err := fmt.Println(`jsonPath usage:
-
-name.last          >> "Anderson"
-age                >> 37
-children           >> ["Sara","Alex","Jack"]
-children.#         >> 3
-children.1         >> "Alex"
-child*.2           >> "Jack"
-c?ildren.0         >> "Sara"
-fav\.movie         >> "Deer Hunter"
-friends.#.first    >> ["Dale","Roger","Jane"]
-friends.1.last     >> "Craig"
-
-You can also  query an array for  the first match by  using #(...), or
-find all matches  with #(...)#. Queries support the ==,  !=, <, <=, >,
->= comparison operators  and the simple pattern matching  % (like) and
-!% (not like) operators. Eg:
-
-friends.#(last=="Murphy").first    >> "Dale"
-friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
-friends.#(age>45)#.last            >> ["Craig","Murphy"]
-friends.#(first%"D*").last         >> "Murphy"
-friends.#(first!%"D*").last        >> "Craig"
-friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]
-
-Documentation: https://github.com/tidwall/gjson/blob/master/SYNTAX.md`)
-
-	return err
-}

pkg/cfg/config.go

@@ -34,7 +34,7 @@ import (
 )
 
 const (
-	Version string = `v0.0.16`
+	Version string = `v0.0.18`
 )
 
 var (
@@ -59,6 +59,8 @@ type Config struct {
 	Shards, Replicas               int      // index create+allocation: -s -r
 	Wait                           bool     // index create: -w
 	Primary                        bool     // index allocation: -p
+	Searchable                     bool     // index fields: -s
+	Aggretable                     bool     // index fields: -a
 	From, To, MaxItems             int      // search: flags
 	Filter                         []string // search: -F
 	Path                           string   // search+doc sh: -p
@@ -68,6 +70,7 @@ type Config struct {
 	Range                          string   // search: -r
 	TimestampFormat                string   // search: --timestamp-format
 	Explain                        bool     // search: -e
+	Validate                       bool     // search: --validate
 	SortBy                         string   // sort: -k
 	Ascending                      bool     // sort: -a
 	Exclude                        string   // cluster compare: -e (regexp)

pkg/es/index.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"log/slog"
 	"regexp"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -52,15 +53,24 @@ func IndexNames(conf *cfg.Config) ([]string, error) {
 }
 
 func filterIndices(conf *cfg.Config, list indices.Response) indices.Response {
+	// apply partials filter first
+	selectedlist := indices.Response{}
+	for _, index := range list {
+		if !conf.Partials && strings.HasPrefix(*index.Index, "partial-") {
+			continue
+		}
+		selectedlist = append(selectedlist, index)
+	}
+
 	if len(conf.Filter) == 0 {
-		return list
+		return selectedlist
 	}
 
 	// we support just one filter here, for now
 	filter := *regexp.MustCompile(conf.Filter[0])
 	newlist := indices.Response{}
 
-	for _, index := range list {
+	for _, index := range selectedlist {
 		if filter.MatchString(*index.Index) {
 			newlist = append(newlist, index)
 		}
@@ -117,8 +127,8 @@ func IndexList(conf *cfg.Config) error {
 	return nil
 }
 
-func IndexShow(conf *cfg.Config, index string) error {
+func IndexShow(conf *cfg.Config, indexpattern string) error {
-	res, err := conf.DefaultCluster.ES.Indices.Get(index).
+	res, err := conf.DefaultCluster.ES.Indices.Get(indexpattern).
 		// we need to add custom request headers, required for older ES instances
 		Header("content-type", "application/json").
 		Header("accept", "application/json").
@@ -127,11 +137,10 @@ func IndexShow(conf *cfg.Config, index string) error {
 		return fmt.Errorf("failed to get index: %s", esErrorString(err))
 	}
 
-	slog.Debug("ES result", "index", res)
+	for name, index := range res {
-
+		fields := make([]string, len(index.Mappings.Properties))
-	fields := make([]string, len(res[index].Mappings.Properties))
 		idx := 0
-	for field := range res[index].Mappings.Properties {
+		for field := range index.Mappings.Properties {
 			fields[idx] = field
 			idx++
 		}
@@ -139,7 +148,7 @@ func IndexShow(conf *cfg.Config, index string) error {
 		table := printer.NewTable(conf, 2, 5)
 		table.Addheaders("index property", "value")
 
-	ts, err := strconv.ParseInt(res[index].Settings.Index.CreationDate.(string), 10, 64)
+		ts, err := strconv.ParseInt(index.Settings.Index.CreationDate.(string), 10, 64)
 		if err != nil {
 			ts = 0
 		}
@@ -147,11 +156,11 @@ func IndexShow(conf *cfg.Config, index string) error {
 		created := time.Unix(ts/1000, 0)
 
 		table.Entries = [][]string{
-		{"name", index},
+			{"name", name},
-		{"replicas", *res[index].Settings.Index.NumberOfReplicas},
+			{"replicas", *index.Settings.Index.NumberOfReplicas},
-		{"shards", *res[index].Settings.Index.NumberOfShards},
+			{"shards", *index.Settings.Index.NumberOfShards},
 			{"created", created.Format("2006-01-02 15:04:05")},
-		{"uuid", *res[index].Settings.Index.Uuid},
+			{"uuid", *index.Settings.Index.Uuid},
 			{"fields", strings.Join(fields, ",")},
 		}
 
@@ -159,6 +168,9 @@ func IndexShow(conf *cfg.Config, index string) error {
 			return err
 		}
 
+		fmt.Println()
+	}
+
 	return nil
 }
 
@@ -311,17 +323,26 @@ func IndexFields(conf *cfg.Config, index string) error {
 		return fmt.Errorf("failed to retrieve field capabilties: %s", esErrorString(err))
 	}
 
-	table := printer.NewTable(conf, 5, len(res.Fields))
+	table := printer.NewTable(conf, 5, 0)
 	table.Addheaders("field", "type", "searchable", "aggretable", "metadata")
 
 	idx := 0
 	for name, field := range res.Fields {
 		for fieldtype, caps := range field {
 			// fields only have 1 type, so this one is it
-			table.Entries[idx] = []string{name, fieldtype,
+			switch {
+			case conf.Searchable && !caps.Searchable:
+				continue
+			case conf.Aggretable && !caps.Aggregatable:
+				continue
+			case len(conf.Filter) > 0 && !slices.Contains(conf.Filter, fieldtype):
+				continue
+			}
+
+			table.Entries = append(table.Entries, []string{name, fieldtype,
 				fmt.Sprintf("%t", caps.Searchable),
 				fmt.Sprintf("%t", caps.Aggregatable),
-				fmt.Sprintf("%t", *caps.MetadataField)}
+				fmt.Sprintf("%t", *caps.MetadataField)})
 			break
 		}
 

pkg/es/role.go

@@ -27,6 +27,23 @@ import (
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 )
 
+func RoleNames(conf *cfg.Config) ([]string, error) {
+	res, err := conf.DefaultCluster.ES.Security.GetRole().
+		Do(context.Background())
+	if err != nil {
+		return nil, fmt.Errorf("failed to get roles: %s", esErrorString(err))
+	}
+
+	roles := make([]string, len(res))
+	idx := 0
+	for name := range res {
+		roles[idx] = name
+		idx++
+	}
+
+	return roles, nil
+}
+
 func RoleList(conf *cfg.Config) error {
 	res, err := conf.DefaultCluster.ES.Security.GetRole().
 		Do(context.Background())

pkg/es/search.go

@@ -18,6 +18,7 @@ package es
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"log"
 	"log/slog"
@@ -28,8 +29,10 @@ import (
 	"github.com/alecthomas/repr"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/core/search"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/esdsl"
+	"github.com/elastic/go-elasticsearch/v9/typedapi/indices/validatequery"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types/enums/sortorder"
+	"github.com/tidwall/gjson"
 )
 
 const (
@@ -43,8 +46,11 @@ Execute an ES search.
 	additional filters can be given as -F key=value
 */
 func Search(conf *cfg.Config, queries []string) error {
-	searchEs := conf.DefaultCluster.ES.Search().
+	if conf.Validate {
-		Index(conf.Index)
+		return validateSearch(conf, queries)
+	}
+
+	searchEs := conf.DefaultCluster.ES.Search().Index(conf.Index)
 
 	queryCaster, err := prepareQuery(conf, queries)
 	if err != nil {
@@ -57,9 +63,11 @@ func Search(conf *cfg.Config, queries []string) error {
 
 	searchEs = addSort(conf, searchEs)
 
-	switch conf.Tail {
+	switch {
-	case true:
+	case conf.Tail:
 		return searchTail(conf, searchEs)
+	case conf.Explain:
+		return explainSearch(conf, searchEs)
 	default:
 		if conf.To > MAXPAGE {
 			return searchPit(conf, req)
@@ -69,6 +77,78 @@ func Search(conf *cfg.Config, queries []string) error {
 	}
 }
 
+func explainSearch(conf *cfg.Config, search *search.Search) error {
+	res, err := search.
+		Explain(true).
+		Size(1). // one's enough for explain
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to call explain search (esdsl): %s", esErrorString(err))
+	}
+
+	if conf.Debug {
+		raw, err := json.Marshal(res)
+		if err != nil {
+			return fmt.Errorf("failed to marshal explain result: %s", err)
+		}
+
+		value := gjson.Get(string(raw), "hits.hits.0._explanation")
+		fmt.Println(value.String())
+	}
+
+	if len(res.Hits.Hits) > 0 {
+		ex := res.Hits.Hits[0].Explanation_
+		fmt.Println(ex.Description)
+		fmt.Println(ex.Value)
+
+		// recurse into explanation details (it's a tree)
+		for _, ex := range ex.Details {
+			explain(&ex, "  ")
+		}
+	}
+
+	return nil
+}
+
+func explain(res *types.ExplanationDetail, indent string) {
+	fmt.Println(indent + "- " + res.Description)
+	for _, ex := range res.Details {
+		fmt.Println(indent + "  - " + ex.Description)
+		fmt.Println(indent + fmt.Sprintf("    score: %f", res.Value))
+
+		explain(&ex, indent+"  ")
+	}
+}
+
+func validateSearch(conf *cfg.Config, queries []string) error {
+	validate := conf.DefaultCluster.ES.Indices.ValidateQuery()
+
+	queryCaster, err := prepareQuery(conf, queries)
+	if err != nil {
+		return err
+	}
+
+	req := &validatequery.Request{Query: queryCaster}
+
+	validate.Request(req)
+
+	res, err := validate.
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to validate search (esdsl): %s", esErrorString(err))
+	}
+
+	slog.Debug("ES result", "search", res)
+
+	if res.Valid {
+		fmt.Println(printer.Colorize(conf, "green", "valid"))
+	} else {
+		fmt.Println(printer.Colorize(conf, "red", "invalid"))
+	}
+
+	return nil
+}
+
 func Debug(conf *cfg.Config) error {
 	res, err := conf.DefaultCluster.ES.Search().
 		Index(conf.Index).
@@ -99,9 +179,7 @@ func searchOnce(conf *cfg.Config, search *search.Search) error {
 
 	slog.Debug("ES result", "search", res)
 
-	for _, hit := range res.Hits.Hits {
+	printer.PrintDocs(conf, res.Hits.Hits)
-		printer.PrintDoc(conf, hit)
-	}
 
 	return nil
 }
@@ -141,9 +219,7 @@ func searchPit(conf *cfg.Config, req *search.Request) error {
 			break
 		}
 
-		for _, hit := range res.Hits.Hits {
+		printer.PrintDocs(conf, res.Hits.Hits)
-			printer.PrintDoc(conf, hit)
-		}
 
 		last := res.Hits.Hits[len(res.Hits.Hits)-1]
 		search = search.SearchAfterValues(last.Sort)
@@ -178,6 +254,7 @@ func searchTail(conf *cfg.Config, search *search.Search) error {
 			}
 
 			printer.PrintDoc(conf, hit)
+			fmt.Println()
 
 			docs[*hit.Id_] = 1
 		}

pkg/printer/doc.go

@@ -18,12 +18,24 @@ package printer
 
 import (
 	"fmt"
+	"slices"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 	"github.com/tidwall/gjson"
 )
 
+func PrintDocs(conf *cfg.Config, hits []types.Hit) {
+	if !conf.Ascending {
+		slices.Reverse(hits)
+	}
+
+	for _, hit := range hits {
+		PrintDoc(conf, hit)
+	}
+
+}
+
 func PrintDoc(conf *cfg.Config, hit types.Hit) {
 	var score types.Float64
 	if hit.Score_ != nil {
@@ -40,6 +52,6 @@ func PrintDoc(conf *cfg.Config, hit types.Hit) {
 		value := gjson.Get(docjson, conf.Path)
 		fmt.Println(value.String())
 	} else {
-		fmt.Println(docjson)
+		fmt.Print(docjson)
 	}
 }