Add CCR stuff, fix search, add docs support, support index maps, refactor (#13)

cmd/ccr.go

@@ -0,0 +1,103 @@
+/*
+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 (
+	"context"
+	"errors"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"codeberg.org/scip/esctl/pkg/es"
+
+	"github.com/urfave/cli/v3"
+)
+
+func Ccr(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "ccr",
+		Aliases: []string{"replication", "rep"},
+		Usage:   "manage cross cluster replication",
+
+		Commands: []*cli.Command{
+			CcrStatus(conf),
+			CcrShardPause(conf),
+			CcrShardResume(conf),
+			CcrFollower(conf),
+		},
+	}
+}
+
+func CcrStatus(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "status",
+		Aliases: []string{"st"},
+		Usage:   "cross cluster replication status (yaml config with 2 clusters required)",
+
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:        "exclude",
+				Usage:       "regexp of indicies to exclude",
+				Destination: &conf.Exclude,
+				Aliases:     []string{"e"},
+			},
+		},
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			leader := cmd.Args().Get(0)
+			follower := cmd.Args().Get(1)
+
+			if leader == "" || follower == "" {
+				return errors.New("no leader and follower aliases specified")
+			}
+
+			_, hasLeader := conf.Clusters[leader]
+			_, hasFollower := conf.Clusters[follower]
+
+			if !hasLeader || !hasFollower {
+				return errors.New("either leader or follower alias not configured")
+			}
+
+			if err := es.CcrStatus(conf, leader, follower); err != nil {
+				return err
+			}
+
+			return nil
+		},
+	}
+}
+
+func CcrShardPause(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:  "pause",
+		Usage: "pause shard allocation",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			return es.CcrShardPause(conf)
+		},
+	}
+}
+
+func CcrShardResume(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:  "resume",
+		Usage: "resume shard allocation",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			return es.CcrShardResume(conf)
+		},
+	}
+}

cmd/ccr_follower.go

@@ -0,0 +1,108 @@
+/*
+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 (
+	"context"
+	"errors"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"codeberg.org/scip/esctl/pkg/es"
+
+	"github.com/urfave/cli/v3"
+)
+
+func CcrFollower(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "follower",
+		Aliases: []string{"f"},
+		Usage:   "manage ccr follower indices",
+
+		Commands: []*cli.Command{
+			CcrFollowerShow(conf),
+			CcrFollowerAdd(conf),
+			CcrFollowerDelete(conf),
+		},
+	}
+}
+
+func CcrFollowerAdd(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:      "add",
+		Aliases:   []string{"+"},
+		Usage:     "add ccr follower index",
+		UsageText: "add [options] <index>",
+
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:        "wait",
+				Usage:       "wait for active shards",
+				Destination: &conf.Wait,
+				Aliases:     []string{"w"},
+			},
+		},
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Args()
+
+			if args.Len() != 1 {
+				return errors.New("missing arguments: <index>")
+			}
+
+			return es.CcrFollowerAdd(conf, cmd.Args().Get(0))
+		},
+	}
+}
+
+func CcrFollowerDelete(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:      "delete",
+		Aliases:   []string{"-"},
+		Usage:     "delete ccr follower index",
+		UsageText: "delete <index>",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Args()
+
+			if args.Len() != 1 {
+				return errors.New("missing arguments: <index>")
+			}
+
+			// just an alias to index delete
+			return es.IndexDelete(conf, cmd.Args().Get(0))
+		},
+	}
+}
+
+func CcrFollowerShow(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:      "show",
+		Aliases:   []string{"sh"},
+		Usage:     "show ccr follower index details",
+		UsageText: "show <index>",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Args()
+
+			if args.Len() != 1 {
+				return errors.New("missing arguments: <index>")
+			}
+
+			return es.CcrFollowerShow(conf, cmd.Args().Get(0))
+		},
+	}
+}

cmd/cluster.go

@@ -18,7 +18,6 @@ package cmd
 
 import (
 	"context"
-	"errors"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"codeberg.org/scip/esctl/pkg/es"
@@ -33,7 +32,6 @@ func Cluster(conf *cfg.Config) *cli.Command {
 		Usage:   "manage cluster[s]",
 
 		Commands: []*cli.Command{
-			ClusterCompare(conf),
 			ClusterStatus(conf),
 			ClusterList(conf),
 			ClusterSettings(conf),
@@ -48,11 +46,7 @@ func ClusterList(conf *cfg.Config) *cli.Command {
 		Aliases: []string{"ls"},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.ClusterList(conf); err != nil {
-				return err
-			}
-
-			return nil
+			return es.ClusterList(conf)
 		},
 	}
 }
@@ -73,132 +67,7 @@ func ClusterStatus(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.ClusterStatus(conf); err != nil {
-				return err
-			}
-
-			return nil
-		},
-	}
-}
-
-func ClusterCompare(conf *cfg.Config) *cli.Command {
-	return &cli.Command{
-		Name:    "compare",
-		Aliases: []string{"c"},
-		Usage:   "compare cluster[s] (yaml config with 2 clusters required)",
-
-		Flags: []cli.Flag{
-			&cli.StringFlag{
-				Name:        "exclude",
-				Usage:       "regexp of indicies to exclude",
-				Destination: &conf.Exclude,
-				Aliases:     []string{"e"},
-			},
-		},
-
-		Action: func(ctx context.Context, cmd *cli.Command) error {
-			leader := cmd.Args().Get(0)
-			follower := cmd.Args().Get(1)
-
-			if leader == "" || follower == "" {
-				return errors.New("no leader and follower aliases specified")
-			}
-
-			_, hasLeader := conf.Clusters[leader]
-			_, hasFollower := conf.Clusters[follower]
-
-			if !hasLeader || !hasFollower {
-				return errors.New("either leader or follower alias not configured")
-			}
-
-			if err := es.ClusterCompare(conf, leader, follower); err != nil {
-				return err
-			}
-
-			return nil
-		},
-	}
-}
-
-func ClusterSettings(conf *cfg.Config) *cli.Command {
-	return &cli.Command{
-		Name:    "settings",
-		Usage:   "cluster settings management",
-		Aliases: []string{"config"},
-
-		Commands: []*cli.Command{
-			ClusterSettingsList(conf),
-			ClusterSettingsSet(conf),
-		},
-	}
-}
-
-func ClusterSettingsList(conf *cfg.Config) *cli.Command {
-	return &cli.Command{
-		Name:    "list",
-		Usage:   "show cluster settings",
-		Aliases: []string{"ls", "get"},
-
-		Flags: []cli.Flag{
-			&cli.BoolFlag{
-				Name:        "persistent",
-				Usage:       "only show persistent setting[s] (default)",
-				Destination: &conf.Persistent,
-				Aliases:     []string{"p"},
-			},
-			&cli.BoolFlag{
-				Name:        "transient",
-				Usage:       "only show transient setting[s]",
-				Destination: &conf.Transient,
-				Aliases:     []string{"t"},
-			},
-			&cli.BoolFlag{
-				Name:        "default",
-				Usage:       "only show default setting[s]",
-				Destination: &conf.Default,
-				Aliases:     []string{"D"},
-			},
-		},
-
-		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.ClusterSettingsList(conf); err != nil {
-				return err
-			}
-
-			return nil
-		},
-	}
-}
-
-func ClusterSettingsSet(conf *cfg.Config) *cli.Command {
-	return &cli.Command{
-		Name:      "set",
-		Usage:     "set|update cluster settings",
-		Aliases:   []string{"set", "update"},
-		UsageText: "set [options] setting:value [setting:value ...]",
-
-		Flags: []cli.Flag{
-			&cli.BoolFlag{
-				Name:        "persistent",
-				Usage:       "add persistent setting[s] (default)",
-				Destination: &conf.Persistent,
-				Aliases:     []string{"p"},
-			},
-			&cli.BoolFlag{
-				Name:        "transient",
-				Usage:       "add transient setting[s]",
-				Destination: &conf.Transient,
-				Aliases:     []string{"t"},
-			},
-		},
-
-		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.ClusterSettingsSet(conf, cmd.Args()); err != nil {
-				return err
-			}
-
-			return nil
+			return es.ClusterStatus(conf)
 		},
 	}
 }

cmd/cluster_settings.go

@@ -0,0 +1,119 @@
+/*
+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 (
+	"context"
+	"errors"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"codeberg.org/scip/esctl/pkg/es"
+
+	"github.com/urfave/cli/v3"
+)
+
+const (
+	SETTINGS = `https://www.elastic.co/docs/reference/elasticsearch/configuration-reference`
+)
+
+func ClusterSettings(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "settings",
+		Usage:   "cluster settings management",
+		Aliases: []string{"config"},
+
+		Commands: []*cli.Command{
+			ClusterSettingsList(conf),
+			ClusterSettingsSet(conf),
+		},
+	}
+}
+
+func ClusterSettingsList(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:    "list",
+		Usage:   "show cluster settings",
+		Aliases: []string{"ls", "get"},
+
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:        "persistent",
+				Usage:       "only show persistent setting[s] (default)",
+				Destination: &conf.Persistent,
+				Aliases:     []string{"p"},
+			},
+			&cli.BoolFlag{
+				Name:        "transient",
+				Usage:       "only show transient setting[s]",
+				Destination: &conf.Transient,
+				Aliases:     []string{"t"},
+			},
+			&cli.BoolFlag{
+				Name:        "default",
+				Usage:       "only show default setting[s]",
+				Destination: &conf.Default,
+				Aliases:     []string{"D"},
+			},
+		},
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			if err := es.ClusterSettingsList(conf); err != nil {
+				return err
+			}
+
+			return nil
+		},
+	}
+}
+
+func ClusterSettingsSet(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:      "set",
+		Usage:     "set|update cluster settings",
+		Aliases:   []string{"set", "update"},
+		UsageText: "set [options] setting:value [setting:value ...]\n\nReference: " + SETTINGS,
+
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:        "persistent",
+				Usage:       "add persistent setting[s] (default)",
+				Destination: &conf.Persistent,
+				Aliases:     []string{"p"},
+			},
+			&cli.BoolFlag{
+				Name:        "transient",
+				Usage:       "add transient setting[s]",
+				Destination: &conf.Transient,
+				Aliases:     []string{"t"},
+			},
+		},
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Args()
+
+			if args.Len() == 0 {
+				return errors.New("at least one setting must be specified (format: setting:value)")
+			}
+
+			if err := es.ClusterSettingsSet(conf, cmd.Args()); err != nil {
+				return err
+			}
+
+			return nil
+		},
+	}
+}

cmd/doc.go

@@ -0,0 +1,58 @@
+/*
+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 (
+	"context"
+	"errors"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"codeberg.org/scip/esctl/pkg/es"
+
+	"github.com/urfave/cli/v3"
+)
+
+func Doc(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:  "doc",
+		Usage: "manage documents",
+
+		Commands: []*cli.Command{
+			DocAdd(conf),
+			//Delete(conf),
+		},
+	}
+}
+
+func DocAdd(conf *cfg.Config) *cli.Command {
+	return &cli.Command{
+		Name:      "add",
+		Aliases:   []string{"+"},
+		Usage:     "add JSON document index",
+		UsageText: "add [options] <index> '<json-doc>'",
+
+		Action: func(ctx context.Context, cmd *cli.Command) error {
+			args := cmd.Args()
+
+			if args.Len() != 2 {
+				return errors.New("missing arguments: <index> <json-doc>")
+			}
+
+			return es.DocAdd(conf, cmd.Args().Get(0), cmd.Args().Get(1))
+		},
+	}
+}

cmd/index.go

@@ -69,11 +69,7 @@ func IndexList(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.IndexList(conf); err != nil {
-				return err
-			}
-
-			return nil
+			return es.IndexList(conf)
 		},
 	}
 }
@@ -85,11 +81,8 @@ func IndexShow(conf *cfg.Config) *cli.Command {
 		Usage:   "show details about an index",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.IndexShow(conf, cmd.Args().Get(0)); err != nil {
-				return err
-			}
+			return es.IndexShow(conf, cmd.Args().Get(0))
 
-			return nil
 		},
 
 		// FIXME: doesn't work at all
@@ -140,11 +133,14 @@ func IndexCreate(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.IndexCreate(conf, cmd.Args().Get(0)); err != nil {
-				return err
+			args := cmd.Args()
+			if args.Len() == 0 {
+				return fmt.Errorf("no index specified")
 			}
 
-			return nil
+			mappings := args.Slice()[1:]
+
+			return es.IndexCreate(conf, args.Get(0), mappings)
 		},
 	}
 }
@@ -156,11 +152,7 @@ func IndexDelete(conf *cfg.Config) *cli.Command {
 		Usage:   "delete an index",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.IndexDelete(conf, cmd.Args().Get(0)); err != nil {
-				return err
-			}
-
-			return nil
+			return es.IndexDelete(conf, cmd.Args().Get(0))
 		},
 	}
 }

cmd/node.go

@@ -45,11 +45,7 @@ func NodeList(conf *cfg.Config) *cli.Command {
 		Usage:   "list nodes",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.NodeList(conf); err != nil {
-				return err
-			}
-
-			return nil
+			return es.NodeList(conf)
 		},
 	}
 }
@@ -62,10 +58,7 @@ func NodeShow(conf *cfg.Config) *cli.Command {
 		UsageText: "show [options] <node>",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			// if err := es.NodeShow(conf, cmd.Args().Get(0)); err != nil {
-			// 	return err
-			// }
-
+			// return es.NodeShow(conf, cmd.Args().Get(0))
 			return nil
 		},
 	}

cmd/root.go

@@ -76,7 +76,9 @@ func Main() int {
 			Index(conf),
 			Snapshot(conf),
 			Cluster(conf),
+			Ccr(conf),
 			Node(conf),
+			Doc(conf),
 		},
 
 		Before: func(ctx context.Context, cmd *cli.Command) (context.Context, error) {

cmd/search.go

@@ -18,6 +18,7 @@ package cmd
 
 import (
 	"context"
+	"errors"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
 	"codeberg.org/scip/esctl/pkg/es"
@@ -30,7 +31,7 @@ func Search(conf *cfg.Config) *cli.Command {
 		Name:      "search",
 		Aliases:   []string{"/"},
 		Usage:     "search within an index",
-		UsageText: "search [options] <query>",
+		UsageText: "search [options] <field=pattern> ...",
 
 		Flags: []cli.Flag{
 			&cli.StringFlag{
@@ -63,11 +64,12 @@ func Search(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.Search(conf, cmd.Args().Get(0)); err != nil {
-				return err
+			args := cmd.Args()
+			if args.Len() == 0 {
+				return errors.New("at least one query must be specified (format: field=pattern)")
 			}
 
-			return nil
+			return es.Search(conf, args.Slice())
 		},
 	}
 }

cmd/snapshot.go

@@ -54,11 +54,7 @@ func SnapshotList(conf *cfg.Config) *cli.Command {
 		},
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.SnapshotList(conf); err != nil {
-				return err
-			}
-
-			return nil
+			return es.SnapshotList(conf)
 		},
 	}
 }
@@ -71,11 +67,7 @@ func SnapshotShow(conf *cfg.Config) *cli.Command {
 		UsageText: "show [options] <snapshot>",
 
 		Action: func(ctx context.Context, cmd *cli.Command) error {
-			if err := es.SnapshotShow(conf, cmd.Args().Get(0)); err != nil {
-				return err
-			}
-
-			return nil
+			return es.SnapshotShow(conf, cmd.Args().Get(0))
 		},
 	}
 }

pkg/cfg/config.go

@@ -31,7 +31,7 @@ import (
 )
 
 const (
-	Version string = `v0.0.6`
+	Version string = `v0.0.8`
 )
 
 type Cluster struct {
@@ -90,11 +90,12 @@ func (conf *Config) Init() error {
 		}
 	} else {
 		if len(conf.Clusters) == 1 {
-			for _, cluster := range conf.Clusters {
+			for name, cluster := range conf.Clusters {
 				conf.DefaultCluster = cluster
+				conf.CurrentCluster = name
 			}
 		} else {
-			for _, cluster := range conf.Clusters {
+			for name, cluster := range conf.Clusters {
 				_, err := cluster.ES.Cluster.Health().
 					Header("content-type", "application/json").
 					Header("accept", "application/json").
@@ -102,18 +103,33 @@ func (conf *Config) Init() error {
 
 				if err == nil {
 					conf.DefaultCluster = cluster
+					conf.CurrentCluster = name
 				}
 			}
 		}
 	}
 
-	if conf.Debug {
-		repr.Println(conf)
-	}
+	conf.PrintDebug()
 
 	return nil
 }
 
+func (conf *Config) PrintDebug() {
+	if !conf.Debug {
+		return
+	}
+
+	clone := *conf
+
+	for name := range clone.Clusters {
+		clone.Clusters[name] = nil
+	}
+	clone.DefaultCluster = nil
+
+	fmt.Println("config:")
+	repr.Println(clone)
+}
+
 func (conf *Config) LoadEnv() error {
 	cluster := Cluster{
 		Uri:  os.Getenv("ES_URI"),

pkg/es/ccr.go

@@ -0,0 +1,87 @@
+/*
+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 es
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
+)
+
+const (
+	shard_pause = `cluster.routing.allocation.enable`
+)
+
+func CcrShardPause(conf *cfg.Config) error {
+	return ClusterSettingsSetSingle(conf, shard_pause, "none")
+}
+
+func CcrShardResume(conf *cfg.Config) error {
+	return ClusterSettingsSetSingle(conf, shard_pause, "all")
+}
+
+func CcrStatus(conf *cfg.Config, leader, follower string) error {
+	if !checkClusterIsLeader(conf, leader) {
+		if !checkClusterIsLeader(conf, follower) {
+			return errors.New("leader/follower attribution is invalid, both clusters are followers")
+		}
+
+		// reverse attribution
+		f := follower
+		follower = leader
+		leader = f
+		slog.Debug("leader/follower attribution is invalid, reversing", "leader", leader, "follower", follower)
+	}
+
+	indices := ClusterIndices{}
+
+	for _, alias := range []string{leader, follower} {
+		cat := conf.Clusters[alias].ES.Cat.Indices().
+			// we need to add custom request headers, required for older ES instances
+			Header("content-type", "application/json").
+			Header("accept", "application/json")
+
+		res, err := cat.Do(context.Background())
+		if err != nil {
+			return fmt.Errorf("failed to get indicies on %s: %s", alias, err)
+		}
+
+		indices[alias] = make(map[string]*types.IndicesRecord, len(res))
+
+		for _, index := range res {
+			indices[alias][*index.Index] = &index
+		}
+	}
+
+	if !checkClusterStatus(conf, leader, follower) {
+		return errors.New("one of the two clusters is in a failed state")
+	}
+
+	findIlmErrors(conf, leader, follower)
+
+	if findIndicesOnlyOnLeader(conf, indices, leader, follower) &&
+		findOrphanedIndices(conf, indices, leader, follower) &&
+		findFailedFollowerIndices(conf, indices, follower) {
+		fmt.Println("everything's hunky-dory.")
+	}
+
+	return nil
+}

pkg/es/ccr_follower.go

@@ -0,0 +1,106 @@
+/*
+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 es
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+)
+
+func CcrFollowerAdd(conf *cfg.Config, index string) error {
+	res, err := conf.DefaultCluster.ES.Cluster.RemoteInfo().
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to retrieve follower info: %s", err)
+	}
+
+	remote := ""
+	for name := range res {
+		remote = name
+		break
+	}
+
+	if remote == "" {
+		return fmt.Errorf("cluster doesn't have a follower: %s", err)
+	}
+
+	create := conf.DefaultCluster.ES.Ccr.Follow(index).
+		LeaderIndex(index).
+		RemoteCluster(remote).
+		Header("content-type", "application/json").
+		Header("accept", "application/json")
+
+	if conf.Wait {
+		create.WaitForActiveShards("all")
+	}
+
+	_, err = create.Do(context.Background())
+
+	if err != nil {
+		return fmt.Errorf("failed to create follower index: %s", err)
+	}
+
+	return nil
+}
+
+func CcrFollowerShow(conf *cfg.Config, index string) error {
+	res, err := conf.DefaultCluster.ES.Ccr.FollowStats(index).
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to retrieve follower index info: %s", err)
+	}
+
+	slog.Debug("ES result", "follower stats", res.Indices)
+
+	if len(res.Indices) == 0 {
+		return fmt.Errorf("cluster did not return any follower stats for index %s", index)
+	}
+
+	if len(res.Indices[0].Shards) == 0 {
+		return fmt.Errorf("cluster did not return any shard stats on follower index %s", index)
+	}
+
+	follower := res.Indices[0].Shards[0]
+
+	table := NewTable(2, 9)
+	table.Addheaders("field", "value")
+
+	table.entries = [][]string{
+		{"name", index},
+		{"remote_cluster", follower.RemoteCluster},
+		{"leader_checkpoint", fmt.Sprintf("%d", follower.LeaderGlobalCheckpoint)},
+		{"follower_checkpoint", fmt.Sprintf("%d", follower.FollowerGlobalCheckpoint)},
+		{"bytes_read", fmt.Sprintf("%d", follower.BytesRead)},
+		{"failed_read_requests", fmt.Sprintf("%d", follower.FailedReadRequests)},
+		{"failed_write_requests", fmt.Sprintf("%d", follower.FailedWriteRequests)},
+		{"successful_read_requests", fmt.Sprintf("%d", follower.SuccessfulReadRequests)},
+		{"successful_write_requests", fmt.Sprintf("%d", follower.SuccessfulWriteRequests)},
+	}
+
+	if err := table.PrintMarkdown(); err != nil {
+		return err
+	}
+
+	return nil
+}

pkg/es/cluster.go

@@ -18,10 +18,9 @@ package es
 
 import (
 	"context"
-	"encoding/json"
-	"errors"
 	"fmt"
 	"log/slog"
+	"slices"
 	"sync"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
@@ -29,11 +28,6 @@ import (
 	"github.com/elastic/go-elasticsearch/v9/typedapi/cluster/health"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/core/info"
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
-	"github.com/urfave/cli/v3"
-)
-
-const (
-	DefaultExclude = `(part|monitoring|.internal|metrics-endpoint)`
 )
 
 const (
@@ -52,54 +46,24 @@ type apiResponse struct {
 	which  int
 }
 
-func ClusterCompare(conf *cfg.Config, leader, follower string) error {
-	if !checkClusterFollower(conf, leader) {
-		return errors.New("leader/follower attribution is invalid, reverse cluster attribution and retry")
-	}
-
-	indices := ClusterIndices{}
-
-	for _, alias := range []string{leader, follower} {
-		cat := conf.Clusters[alias].ES.Cat.Indices().
-			// we need to add custom request headers, required for older ES instances
-			Header("content-type", "application/json").
-			Header("accept", "application/json")
-
-		res, err := cat.Do(context.Background())
-		if err != nil {
-			return fmt.Errorf("failed to get indicies on %s: %s", alias, err)
-		}
-
-		indices[alias] = make(map[string]*types.IndicesRecord, len(res))
-
-		for _, index := range res {
-			indices[alias][*index.Index] = &index
-		}
-	}
-
-	if !checkClusterStatus(conf, leader, follower) {
-		return errors.New("one of the two clusters is in a failed state")
-	}
-
-	findIlmErrors(conf, leader, follower)
-
-	if findIndicesOnlyOnLeader(conf, indices, leader, follower) &&
-		findOrphanedIndices(conf, indices, leader, follower) &&
-		findFailedFollowerIndices(conf, indices, follower) {
-		fmt.Println("everything's hunky-dory.")
-	}
-
-	return nil
-}
-
 func ClusterList(conf *cfg.Config) error {
 	table := NewTable(3, len(conf.Clusters))
 
 	table.Addheaders("cluster", "uri", "default")
 
 	idx := 0
-	for name, cluster := range conf.Clusters {
+
+	names := make([]string, len(conf.Clusters))
+	for name := range conf.Clusters {
+		names[idx] = name
+		idx++
+	}
+
+	slices.Sort(names)
+
+	for idx, name := range names {
 		current := name == "default" || name == conf.CurrentCluster
+		cluster := conf.Clusters[name]
 
 		_, err := cluster.ES.Cluster.Health().
 			Header("content-type", "application/json").
@@ -111,10 +75,8 @@ func ClusterList(conf *cfg.Config) error {
 		}
 
 		table.entries[idx] = []string{name, cluster.Uri, fmt.Sprintf("%t", current)}
-		idx++
 	}
 
-	table.Sort()
 	if err := table.PrintMarkdown(); err != nil {
 		return err
 	}
@@ -204,91 +166,3 @@ func ClusterStatus(conf *cfg.Config) error {
 
 	return nil
 }
-
-func ClusterSettingsList(conf *cfg.Config) error {
-	res, err := conf.DefaultCluster.ES.Cluster.GetSettings().
-		Header("content-type", "application/json").
-		Header("accept", "application/json").
-		Do(context.Background())
-	if err != nil {
-		return fmt.Errorf("failed to get cluster settings: %s", err)
-	}
-
-	table := NewTable(2, 0)
-	table.Addheaders("setting", "value")
-	entries := [][]string{}
-
-	settingshash := res.Persistent // == map[string]json.RawMessage
-
-	switch {
-	case conf.Transient:
-		settingshash = res.Transient
-	case conf.Default:
-		settingshash = res.Defaults
-	}
-
-	for topic, val := range settingshash {
-		data := map[string]map[string]any{}
-
-		err := json.Unmarshal(val, &data)
-
-		if err != nil {
-			return fmt.Errorf("failed to unmarshall setting for topic %s: %s", topic, err)
-		}
-
-		for key, settings := range data {
-			for setting, value := range settings {
-				entries = append(entries, []string{
-					fmt.Sprintf("%s.%s.%s", topic, key, setting),
-					fmt.Sprintf("%v", value),
-				})
-
-			}
-		}
-	}
-
-	table.entries = entries
-	table.Sort()
-
-	if err := table.PrintMarkdown(); err != nil {
-		return err
-	}
-
-	return nil
-}
-
-func ClusterSettingsSet(conf *cfg.Config, args cli.Args) error {
-	put := conf.Clusters[conf.CurrentCluster].ES.Cluster.PutSettings()
-
-	for _, arg := range args.Slice() {
-		setting, value := splitArg(arg)
-
-		switch {
-		case conf.Transient:
-			message, err := json.Marshal(value)
-			if err != nil {
-				return fmt.Errorf("failed to marshall transient value <%v> to valid JSON: %s", value, err)
-			}
-			put.AddTransient(setting, message)
-		case conf.Persistent:
-			fallthrough
-		default:
-			message, err := json.Marshal(value)
-			if err != nil {
-				return fmt.Errorf("failed to marshall persistent value <%v> to valid JSON: %s", value, err)
-			}
-			put.AddPersistent(setting, message)
-		}
-	}
-
-	_, err := put.
-		Header("content-type", "application/json").
-		Header("accept", "application/json").
-		Do(context.Background())
-
-	if err != nil {
-		return fmt.Errorf("failed to set settings: %s", err)
-	}
-
-	return nil
-}

pkg/es/cluster_settings.go

@@ -0,0 +1,160 @@
+/*
+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 es
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+	"github.com/urfave/cli/v3"
+)
+
+// recursively traverse  the raw  settings hash and  build a  flat map
+// consisting of the translated path and its value.
+//
+// e.g.
+// logger:
+//
+//	org:
+//	  elasticsearch:
+//	    transport:
+//	      OutboundHandler: "ERROR"
+//
+// gets:
+//
+// logger.org.elasticsearch.transport.OutboundHandler: "ERROR"
+func getJsonPath(raw map[string]any, topic string) map[string]string {
+	paths := map[string]string{}
+
+	for name, data := range raw {
+		path := topic + "." + name
+		switch value := data.(type) {
+		case string:
+			paths[path] = value
+		case map[string]any:
+			paths = getJsonPath(value, path)
+		}
+	}
+
+	return paths
+}
+
+func ClusterSettingsList(conf *cfg.Config) error {
+	res, err := conf.DefaultCluster.ES.Cluster.GetSettings().
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to get cluster settings: %s", err)
+	}
+
+	table := NewTable(2, 0)
+	table.Addheaders("setting", "value")
+	entries := [][]string{}
+
+	settingshash := res.Persistent // == map[string]json.RawMessage
+
+	switch {
+	case conf.Transient:
+		settingshash = res.Transient
+	case conf.Default:
+		settingshash = res.Defaults
+	}
+
+	for topic, val := range settingshash {
+		data := map[string]any{}
+
+		err := json.Unmarshal(val, &data)
+		if err != nil {
+			return fmt.Errorf("failed to unmarshall setting for topic %s: %s", topic, err)
+		}
+
+		paths := getJsonPath(data, topic)
+		slog.Debug("settings", topic, paths)
+
+		for setting, value := range paths {
+			entries = append(entries, []string{setting, fmt.Sprintf("%v", value)})
+		}
+	}
+
+	table.entries = entries
+	table.Sort()
+
+	if err := table.PrintMarkdown(); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func ClusterSettingsSet(conf *cfg.Config, args cli.Args) error {
+	put := conf.Clusters[conf.CurrentCluster].ES.Cluster.PutSettings()
+
+	for _, arg := range args.Slice() {
+		setting, value := splitArg(arg)
+
+		switch {
+		case conf.Transient:
+			message, err := json.Marshal(value)
+			if err != nil {
+				return fmt.Errorf("failed to marshall transient value <%v> to valid JSON: %s", value, err)
+			}
+			put.AddTransient(setting, message)
+		case conf.Persistent:
+			fallthrough
+		default:
+			message, err := json.Marshal(value)
+			if err != nil {
+				return fmt.Errorf("failed to marshall persistent value <%v> to valid JSON: %s", value, err)
+			}
+			put.AddPersistent(setting, message)
+		}
+	}
+
+	_, err := put.
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+
+	if err != nil {
+		return fmt.Errorf("failed to set settings: %s", err)
+	}
+
+	return nil
+}
+
+func ClusterSettingsSetSingle(conf *cfg.Config, setting, value string) error {
+	message, err := json.Marshal(value)
+	if err != nil {
+		return fmt.Errorf("failed to marshall persistent value <%v> to valid JSON: %s", value, err)
+	}
+
+	_, err = conf.Clusters[conf.CurrentCluster].ES.Cluster.PutSettings().
+		AddPersistent(setting, message).
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+
+	if err != nil {
+		return fmt.Errorf("failed to set %s: %s", setting, err)
+	}
+
+	return nil
+}

pkg/es/cluster_util.go

@@ -30,7 +30,11 @@ import (
 	"github.com/elastic/go-elasticsearch/v9/typedapi/types"
 )
 
-func checkClusterFollower(conf *cfg.Config, leader string) bool {
+const (
+	DefaultExclude = `(part|monitoring|.internal|metrics-endpoint)`
+)
+
+func checkClusterIsLeader(conf *cfg.Config, leader string) bool {
 	stats, err := conf.Clusters[leader].ES.Ccr.Stats().
 		Header("content-type", "application/json").
 		Header("accept", "application/json").

pkg/es/doc.go

@@ -0,0 +1,55 @@
+/*
+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 es
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"codeberg.org/scip/esctl/pkg/cfg"
+)
+
+// create index with:
+//
+// esctl index create foo [id:keyword user:text age:integer]
+//
+// then add a doc:
+//
+// esctl doc add foo2 '{"id":"d8d8d","user":"scip"}'
+func DocAdd(conf *cfg.Config, index, jsondoc string) error {
+	data := map[string]any{}
+
+	err := json.Unmarshal([]byte(jsondoc), &data)
+	if err != nil {
+		return fmt.Errorf("supplied document was not valid JSON: %s", err)
+	}
+
+	now := fmt.Sprintf("%d", time.Now().Unix())
+
+	_, err = conf.DefaultCluster.ES.Create(index, now).
+		Document(data).
+		Header("content-type", "application/json").
+		Header("accept", "application/json").
+		Do(context.Background())
+	if err != nil {
+		return fmt.Errorf("failed to create new doc in index %s: %s", index, err)
+	}
+
+	return nil
+}

pkg/es/index.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"log/slog"
 	"strconv"
+	"strings"
 	"time"
 
 	"codeberg.org/scip/esctl/pkg/cfg"
@@ -134,11 +135,7 @@ func IndexShow(conf *cfg.Config, index string) error {
 	return nil
 }
 
-func IndexCreate(conf *cfg.Config, index string) error {
-	if index == "" {
-		return fmt.Errorf("no index specified")
-	}
-
+func IndexCreate(conf *cfg.Config, index string, mappings []string) error {
 	settings := esdsl.NewIndexSettings()
 
 	create := conf.DefaultCluster.ES.Indices.Create(index).
@@ -156,6 +153,30 @@ func IndexCreate(conf *cfg.Config, index string) error {
 		settings = settings.NumberOfReplicas(strconv.Itoa(conf.Replicas))
 	}
 
+	if len(mappings) > 0 {
+		maps := esdsl.NewTypeMapping()
+
+		for _, mapping := range mappings {
+			parts := strings.Split(mapping, ":")
+			if len(parts) != 2 {
+				return fmt.Errorf("invalid mapping %s, expect <name:type> (type: integer, text, date, keyword)", mapping)
+			}
+
+			switch parts[1] {
+			case "text":
+				maps.AddProperty(parts[0], esdsl.NewTextProperty())
+			case "integer":
+				maps.AddProperty(parts[0], esdsl.NewIntegerNumberProperty())
+			case "date":
+				maps.AddProperty(parts[0], esdsl.NewDateProperty())
+			case "keyword":
+				maps.AddProperty(parts[0], esdsl.NewKeywordProperty())
+			}
+		}
+
+		create.Mappings(maps)
+	}
+
 	_, err := create.Settings(settings).
 		Do(context.Background())
 

pkg/es/search.go

@@ -34,9 +34,17 @@ Execute an ES search.
 	q is the actual search query given as arg to the 'search' cmd
 	additional filters can be given as -F key=value
 */
-func Search(conf *cfg.Config, q string) error {
-	query := esdsl.NewBoolQuery().
-		Must(esdsl.NewMatchQuery("message", q))
+func Search(conf *cfg.Config, queries []string) error {
+	query := esdsl.NewBoolQuery()
+
+	for _, q := range queries {
+		parts := strings.Split(q, "=")
+		if len(parts) != 2 {
+			return fmt.Errorf("search queries must be in the form field=pattern")
+		}
+
+		query.Must(esdsl.NewMatchQuery(parts[0], parts[1]))
+	}
 
 	filters := make([]types.QueryVariant, len(conf.Filter))