completion

Documentation

Overview

Package completion provides dynamic shell completion helpers for matter-cli. It uses the cluster registry and store to generate context-aware completions for cluster names, attribute names, command names, node IDs, and @target tokens.

Index

• Constants
• func AttributeNameCompletion(registry *clusters.Registry) ...
• func ClusterNameCompletion(registry *clusters.Registry) ...
• func CommandNameCompletion(registry *clusters.Registry) ...
• func FieldFlagCompletions(fields []clusters.CommandFieldInfo, existing []string, toComplete string) ([]string, cobra.ShellCompDirective)
• func NodeIDCompletionFunc() ...
• func RootCompletionFunc(registry *clusters.Registry, allowedClusters func() map[uint32]bool, ...) ...
• func TargetCompletionFunc(topLevelCommands func() []TopLevelCommand) ...
• type TopLevelCommand

Constants

const ExpandEnvVar = "MATTER_COMPLETION_EXPAND"

ExpandEnvVar is the environment variable the zsh completion script sets (to "zsh") before invoking "matter __complete ...". Its presence opts the caller into receiving "@N+<cmd>" expansion tokens. Other shells (bash, fish, PowerShell) do not set it, so they continue to receive only plain @N / @N/<ep> tokens and never display the literal expansion syntax.

const ExpandSeparator = "+"

ExpandSeparator is the separator embedded in "@N+<cmd>" expansion tokens. The zsh completion script recognises it to split the target prefix from the subcommand name and invoke compadd with -U -p "@N " so the subcommand is inserted as a separate shell word while the displayed candidate is the bare subcommand name. The "+" character is used because it cannot appear in either a valid numeric node token or a top-level cobra command name.

Functions

func AttributeNameCompletion

func AttributeNameCompletion(registry *clusters.Registry) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

AttributeNameCompletion returns a cobra ValidArgsFunction that completes attribute names for the cluster specified by the --cluster flag.

func ClusterNameCompletion

func ClusterNameCompletion(registry *clusters.Registry) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

ClusterNameCompletion returns a cobra ValidArgsFunction that completes cluster names from the global cluster registry.

func CommandNameCompletion

func CommandNameCompletion(registry *clusters.Registry) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

CommandNameCompletion returns a cobra ValidArgsFunction that completes command names for the cluster specified by the --cluster flag.

func FieldFlagCompletions

func FieldFlagCompletions(fields []clusters.CommandFieldInfo, existing []string, toComplete string) ([]string, cobra.ShellCompDirective)

FieldFlagCompletions returns completions for command fields. When toComplete contains "=" (e.g. "Direction="), it returns enum values for that field. Otherwise it returns "FieldName=" completions for all unset fields.

func NodeIDCompletionFunc

func NodeIDCompletionFunc() func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

NodeIDCompletionFunc returns a cobra completion function that lazily opens the store at completion time, reads the fabric ID from viper config, and returns all known node IDs with their human-friendly names as completion candidates. The store is opened and closed on each completion invocation so that no persistent handle is required at flag-registration time.

If the store cannot be opened (e.g. first run, no devices commissioned yet), the function gracefully returns an empty list instead of an error so the shell completion experience is not disrupted.

func RootCompletionFunc

func RootCompletionFunc(
	registry *clusters.Registry,
	allowedClusters func() map[uint32]bool,
	topLevelCommands func() []TopLevelCommand,
) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

RootCompletionFunc returns a cobra ValidArgsFunction for the root command that handles three completion types:

• @target tokens (e.g. "@1/2") — delegated to TargetCompletionFunc. When a numeric @N exactly matches an existing node, the returned set is enriched with endpoint tokens (@N/0, @N/1, ...) and "@N+<cmd>" expansion tokens for the commands returned by topLevelCommands, so the user does not need to type " " or "/" to see what comes next.
• cluster shorthand commands — case-insensitive prefix/substring match of cluster names, so typing "on<TAB>" offers "OnOff" and "level<TAB>" offers "LevelControl".

The cluster name completions are offered only when toComplete does not start with "@", and use the same search infrastructure as ClusterNameCompletion.

allowedClusters, if non-nil, is called at completion time to filter results to the set of cluster IDs present on the current target endpoint. A nil map means no filter (show all clusters); a non-nil but empty map means no clusters are applicable (e.g. node-only target without an endpoint).

topLevelCommands, if non-nil, is called when expanding an exact @N match to seed the "Device Commands" / "Tools" / "Cluster Commands" sections.

func TargetCompletionFunc

func TargetCompletionFunc(
	topLevelCommands func() []TopLevelCommand,
) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective)

TargetCompletionFunc returns a cobra ValidArgsFunction that completes @target tokens in two stages. Emitted tokens are always numeric @N; device names are shown only in the description as a visual hint.

Stage 1 — node-only (no "/" typed yet): When the user types "@" or "@ki", completions are numeric node tokens (e.g. "@1", "@2"). Prefix matching considers both the numeric ID and the device's kebab-case name, so "@ki" can narrow down to a node named "Kitchen Light". ShellCompDirectiveNoSpace is included so the shell does not append a trailing space, allowing the user to either type "/" to proceed to endpoint selection or " " (space) for device commands.

Stage 1b — exact match expansion: When toComplete is a numeric @N that exactly identifies a commissioned node, the result set is enriched with:

• endpoint tokens "@N/0", "@N/1", ... so the user sees endpoints without having to type "/" first; and
• "@N+<cmd>" expansion tokens for each top-level command returned by topLevelCommands (if non-nil), so device-level commands and tools appear in the same menu as the endpoint list. The zsh script strips the "@N+" prefix before display and inserts the selection as a separate word after "@N ".

Stage 2 — endpoint selection ("/" present): When the user types "@1/", completions are the non-root endpoints on the matched node (e.g. "@1/1", "@1/2"). Normal trailing space is applied so the user can proceed to a command after selection.

Types

type TopLevelCommand

type TopLevelCommand struct {
	// Name is the subcommand name as registered with cobra (e.g. "tree").
	Name string
	// Short is the one-line description shown next to the command.
	Short string
	// Group is "device", "cluster", "tool", or "". It is metadata for
	// shell-specific completion helpers and is not encoded in the emitted
	// "@N+<name>" token; the zsh script derives grouping from its own
	// statically-generated _matter_group_map, keyed by command name.
	Group string
	// TargetAware reports whether the command accepts/requires a node
	// target. Commands that operate on the fabric as a whole (e.g.
	// "commission", "discover") are skipped for @N expansion so the menu
	// stays relevant.
	TargetAware bool
}

TopLevelCommand describes a single root-level cobra subcommand for the purposes of @target completion expansion. When the user types "@N<TAB>" against an existing node, these commands are surfaced as "@N+<name>" tokens so the shell can offer them alongside endpoint and sibling-node completions in a single menu.