Problem
elastic stack es --help lists the ~30 top-level commands in a flat alphabetical list. Related commands are scattered: get-script, put-script, and delete-script are separated by unrelated entries, and search, msearch, search-template, msearch-template, and scroll are not adjacent.
Suggestions
1. Group commands by functional domain
Rather than a flat alphabetical list, group the top-level commands under named sections — similar to how subcommand namespaces (cat, cluster, etc.) already work. Possible groupings:
| Group |
Commands |
| Documents |
get, get-source, exists, exists-source, index, create, update, delete, mget, bulk |
| Search |
search, msearch, scroll, search-template, msearch-template, search-mvt, open-point-in-time, close-point-in-time |
| Scripts |
get-script, put-script, delete-script, scripts-painless-execute, render-search-template |
| Analysis |
explain, termvectors, mtermvectors, field-caps, terms-enum, rank-eval, count |
| Cluster |
info, ping, reindex, update-by-query, delete-by-query |
The exact groupings are up to the maintainers; the point is co-locating related commands so discovery is easier.
2. Order groups (and/or commands within groups) by usage popularity
If telemetry data is available for which API endpoints are called most frequently, use it to determine the display order — most-used groups first, and within a group most-used commands first. This surfaces the high-value commands (e.g. search, index, get) at the top and pushes rarely-used ones toward the bottom, which benefits new users who are still learning the CLI.
If telemetry isn't available or doesn't apply here, a hand-curated "common first" ordering based on Elasticsearch API usage patterns would still be an improvement over pure alphabetical.
Notes
- Commander.js (which this CLI uses) supports custom help formatters, so grouping is implementable without switching libraries.
- The subcommand namespaces (
cat, cluster, etc.) are already a form of grouping — this proposal extends that same concept to the flat top-level list.
Problem
elastic stack es --helplists the ~30 top-level commands in a flat alphabetical list. Related commands are scattered:get-script,put-script, anddelete-scriptare separated by unrelated entries, andsearch,msearch,search-template,msearch-template, andscrollare not adjacent.Suggestions
1. Group commands by functional domain
Rather than a flat alphabetical list, group the top-level commands under named sections — similar to how subcommand namespaces (
cat,cluster, etc.) already work. Possible groupings:get,get-source,exists,exists-source,index,create,update,delete,mget,bulksearch,msearch,scroll,search-template,msearch-template,search-mvt,open-point-in-time,close-point-in-timeget-script,put-script,delete-script,scripts-painless-execute,render-search-templateexplain,termvectors,mtermvectors,field-caps,terms-enum,rank-eval,countinfo,ping,reindex,update-by-query,delete-by-queryThe exact groupings are up to the maintainers; the point is co-locating related commands so discovery is easier.
2. Order groups (and/or commands within groups) by usage popularity
If telemetry data is available for which API endpoints are called most frequently, use it to determine the display order — most-used groups first, and within a group most-used commands first. This surfaces the high-value commands (e.g.
search,index,get) at the top and pushes rarely-used ones toward the bottom, which benefits new users who are still learning the CLI.If telemetry isn't available or doesn't apply here, a hand-curated "common first" ordering based on Elasticsearch API usage patterns would still be an improvement over pure alphabetical.
Notes
cat,cluster, etc.) are already a form of grouping — this proposal extends that same concept to the flat top-level list.