Struct CommandTree 

pub struct CommandTree {
    pub app_name: String,
    pub root: Node,
    pub hidden: HashSet<String>,
    pub global_flag_help: BTreeMap<String, String>,
    pub global_flag_long_help: BTreeMap<String, String>,
    pub strict_metadata: bool,
    pub min_stability: Stability,
}

The top-level command tree for an application.

Fields

app_name: String

Application name (used for env var naming).

root: Node

Root node (always a group).

hidden: HashSet<String>

Commands that exist but are hidden from root-level listing.

global_flag_help: BTreeMap<String, String>

Help text for global flags. Falls back to per-node flag_help when the cursor sits inside a leaf that doesn’t override the help line for a global flag like --dataset or --profile. Used by the value-position rapid-tap UX.

global_flag_long_help: BTreeMap<String, String>

Extended help text for global flags. Same fallback chain as Self::global_flag_help; surfaced on triple-tap at a value position.

strict_metadata: bool

When true, every registered command must declare both a category (via Node::with_category) and an explicit level (via Node::with_level). Self::command / Self::group / Self::hidden_command panic on registration of an undertagged node, surfacing the problem at the call site rather than producing a silently-uncategorized completion tree at runtime. Opt-in for apps that want their stratified completion UX enforced at compile-test time.

min_stability: Stability

Minimum command Stability offered during completion. Commands below this threshold are omitted from suggestions (but remain runnable). Defaults to Stability::Preview, so Experimental commands are hidden until lowered. handle_complete_env adjusts it per-completion when the line begins with ---experimental / ---preview / ---stable.

Implementations

impl CommandTree

pub fn max_level(&self) -> u32

Maximum Node::level across all root-level children. Drives the rotation cycle in complete_rotating: a tap beyond max_level() wraps back to level 1.

Returns at least 1 (since DEFAULT_LEVEL is 1) so callers can use the result directly as a modular cycle length.

pub fn new(app_name: &str) -> Self

Create a new command tree with an empty root group.

The app_name is used to construct the environment variable name for completion callbacks (e.g., _MYAPP_COMPLETE=bash).

pub fn global_flag_help_for(&self, flag: &str) -> Option<&str>

Lookup help text for a global flag. Returns None if no global help was registered for this flag.

pub fn global_flag_help(self, flag: &str, help: &str) -> Self

Register help text for a global flag. Builder-style.

pub fn global_flag_long_help_for(&self, flag: &str) -> Option<&str>

Lookup extended help for a global flag.

pub fn global_flag_long_help(self, flag: &str, help: &str) -> Self

Register extended help for a global flag — surfaced on rapid triple-tap at a value position. Composes with Self::global_flag_help.

pub fn require_metadata(self) -> Self

Opt-in to strict-metadata mode. Every subsequent call to Self::command / Self::group / Self::hidden_command checks that the node has both a category and an explicit level — registration panics if either is missing, with a message naming the offending command.

Use this in apps that have committed to a stratified completion model and want the build to break if a new command is added without categorizing it.

pub fn validate(&self) -> Result<(), Vec<MetadataError>>

Walk every registered command and check for missing category / level metadata. Returns Ok(()) when every node satisfies the contract; Err(Vec<MetadataError>) otherwise with one entry per offending command.

Always available regardless of strict_metadata — apps that want validation as a one-shot post-build check (CI test, debug-assert, etc.) can call this directly without enabling the panic-at-registration mode.

pub fn command(self, name: &str, node: Node) -> Self

Add a top-level command (leaf or group) to the tree.

This is a builder method — it consumes and returns self for chaining.

pub fn strict_command(self, name: &str, node: StrictNode<true, true>) -> Self

Add a top-level command using the type-state-checked StrictNode API. The signature requires StrictNode<true, true>, so calling this with a node missing either with_category(...) or with_level(...) is a compile-time error — no runtime panic, no silent skip. Recommended entry point for apps that want the stratified completion model strictly enforced.

pub fn strict_group(self, name: &str, node: StrictNode<true, true>) -> Self

Type-state-checked alias for grouping. Same compile-time guarantee as Self::strict_command.

pub fn strict_hidden_command( self, name: &str, node: StrictNode<true, true>, ) -> Self

Type-state-checked variant of Self::hidden_command.

pub fn group(self, name: &str, node: Node) -> Self

Add a top-level group to the tree. Alias for command.

pub fn hidden_command(self, name: &str, node: Node) -> Self

Add a command that is registered but hidden from root-level listing.

Hidden commands are still completable if the user types the name prefix directly — they are just excluded from the initial empty-prefix candidate list. Useful for aliases and shorthands.

pub fn with_auto_help(self) -> Self

Built-in option: enable --help everywhere. Walks the whole tree and adds --help (boolean) to every node that doesn’t already declare it. Embedders use this to opt into uniform help support without writing per-node with_boolean_flags(&[ "--help"]) boilerplate. The same --help shows up in tab completion at every level and is recognised by parse_argv as a known flag.

Pair with render_usage in your handler:

let parsed = parse_argv(&tree, &argv)?;
if parsed.flags.contains_key("--help") {
    // walk parsed.path to find the node, then:
    println!("{}", render_usage(node, &parsed.path));
    return Ok(());
}

pub fn with_metricsql_at( self, path: &[&str], catalog: Arc<dyn MetricsqlCatalog>, ) -> Self

Built-in option: attach a crate::providers::metricsql_provider at the supplied subcommand path. The path is ["sub1", "sub2", …] — the chain of children to descend through from the root before the provider takes over completion.

Equivalent to manually navigating to the node and calling with_subtree_provider(metricsql_provider(catalog)), but surfaces the intent at tree-construction time.

Trait Implementations

impl Clone for CommandTree

fn clone(&self) -> CommandTree

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.