README
¶
Root Command
The entry point and orchestration layer for GTB CLI applications.
Key Responsibilities:
- Persistent service initialization (Logging, Configuration)
- Global flag management (
--config,--debug,--ci) - Lifecycle hooks (
PersistentPreRunE) - Automatic feature command registration
For detailed documentation on the root command and the application lifecycle, see the Built-in Commands Documentation.
Documentation
¶
Overview ¶
Package root provides the reusable root Cobra command constructor that wires configuration loading, logging setup, update checks, and feature-flagged subcommand registration (version, update, init, docs, MCP).
The NewCmdRoot and NewCmdRootWithConfig functions build a root command whose PersistentPreRunE handles config merging (local files + embedded assets), log level/format configuration, and optional self-update prompting before any subcommand executes.
Index ¶
- Variables
- func ConventionKey(flagName string) string
- func Execute(rootCmd *setup.Command, props *p.Props)
- func NewCmdRoot(props *p.Props, subcommands ...*setup.Command) *setup.Command
- func NewCmdRootWithConfig(props *p.Props, configPaths []string, subcommands ...*setup.Command) *setup.Command
- func NewCmdRootWithOptions(props *p.Props, opts ...RootOption) *setup.Command
- type ConfigLoadOptions
- type FlagValues
- type OutdatedVersionOption
- type RootOption
- type UpdateCheckResult
Constants ¶
This section is empty.
Variables ¶
var ErrUpdateComplete = errors.New("update complete — restart required")
ErrUpdateComplete is returned by PersistentPreRunE when a self-update has completed successfully. The Execute wrapper handles this by exiting cleanly without logging an error.
Functions ¶
func ConventionKey ¶ added in v0.17.0
ConventionKey maps a flag name to a configuration key using the hyphen-to-dot convention: "server-port" → "server.port". It is exported so downstream tools can derive the same keys when constructing explicit WithBoundFlags maps.
func Execute ¶
Execute runs the root command with centralized error handling and a signal-aware execution context. SIGINT/SIGTERM cancel cmd.Context() so commands can unwind gracefully; a second signal force-exits immediately (kubectl/docker UX); a signal-terminated run exits 128+signum (130 for SIGINT, 143 for SIGTERM) through the ErrorHandler's exit path.
It silences Cobra's default error output and routes any error returned by the command tree through ErrorHandler.Check at Fatal level. The buffered telemetry flush runs on every path — success, error, and cancellation — before any exit fires.
func NewCmdRoot ¶
NewCmdRoot creates the root command with Props wiring and optional subcommands.
func NewCmdRootWithConfig ¶
func NewCmdRootWithConfig(props *p.Props, configPaths []string, subcommands ...*setup.Command) *setup.Command
NewCmdRootWithConfig creates the root command for the CLI application. It accepts additional configuration file paths to be considered during initialization.
func NewCmdRootWithOptions ¶ added in v0.17.0
func NewCmdRootWithOptions(props *p.Props, opts ...RootOption) *setup.Command
NewCmdRootWithOptions creates the root command, configured by the supplied [RootOption]s. This is the extensible constructor; NewCmdRoot and NewCmdRootWithConfig are thin wrappers over it. Use WithBoundFlags or WithConventionBoundFlags to wire CLI flags into the configuration precedence (flags > env > file > embedded > defaults).
Types ¶
type ConfigLoadOptions ¶
type ConfigLoadOptions struct {
CfgPaths []string
ConfigPaths []string
Props *p.Props
AllowEmpty bool
}
ConfigLoadOptions holds the options needed for loading configuration.
type FlagValues ¶
FlagValues holds the command-line flag values extracted from cobra command.
type OutdatedVersionOption ¶
type OutdatedVersionOption func(*outdatedVersionConfig)
OutdatedVersionOption configures handleOutdatedVersion behavior.
type RootOption ¶ added in v0.17.0
type RootOption func(*rootOptions)
RootOption configures the root command constructed by NewCmdRootWithOptions. Options are the extensible way to register bound flags and subcommands without breaking the existing constructor signatures.
func WithBoundFlags ¶ added in v0.17.0
func WithBoundFlags(flags map[string]*pflag.Flag) RootOption
WithBoundFlags binds the given persistent/root pflags to configuration keys.
The map key is the dotted configuration key (e.g. "server.port") and the value is the pflag to bind. Bound flags participate in the documented configuration precedence (flags > env > file > embedded > defaults): a flag the user explicitly set on the command line overrides the corresponding config value. A flag left at its default does not override config — binding is filtered by flag.Changed during config load.
Example:
root.NewCmdRootWithOptions(props, root.WithBoundFlags(map[string]*pflag.Flag{
"server.port": rootCmd.PersistentFlags().Lookup("server-port"),
}))
func WithConfigPaths ¶ added in v0.17.0
func WithConfigPaths(paths ...string) RootOption
WithConfigPaths registers additional configuration file paths to consider during initialisation. Equivalent to the configPaths argument of NewCmdRootWithConfig.
func WithConventionBoundFlags ¶ added in v0.17.0
func WithConventionBoundFlags(flags *pflag.FlagSet) RootOption
WithConventionBoundFlags binds every flag in the given flag set to a config key derived from its name by the hyphen-to-dot convention: "--server-port" becomes the config key "server.port". This is the zero-boilerplate alternative to WithBoundFlags when flag names already mirror config keys.
As with WithBoundFlags, only flags the user explicitly changed override config (filtered by flag.Changed during load). Flags already containing a dot are mapped verbatim; authors should avoid dots in flag names to keep the mapping unambiguous.
func WithSubcommands ¶ added in v0.17.0
func WithSubcommands(subcommands ...*setup.Command) RootOption
WithSubcommands registers subcommands on the root command.
type UpdateCheckResult ¶
UpdateCheckResult holds the result of checking for updates.
Source Files