Documentation
¶
Overview ¶
Package cli provides Cobra scaffolding for hex applications.
The helpers here cover the boilerplate every hex-based CLI wants: a root command wired to *hex.App, common persistent flags (--log-level, --env, --verbose), a version subcommand backed by hex/build, and a small context helper so subcommands can retrieve the *hex.App without a package-level global.
Anything app-specific — command groups, subcommand tree, error pretty-printing, plugin discovery, session/env semantics — stays in the consumer app. hex/cli deliberately keeps its surface tight so it does not turn into "one big framework CLI."
Typical main:
app := hex.New()
provider.Boot(app)
if err := app.Bootstrap(ctx); err != nil { log.Fatal(err) }
defer app.Shutdown(ctx)
root := hexcli.Root(hexcli.RootOptions{
Name: "myapp",
Short: "my hex-powered CLI",
App: app,
})
root.AddCommand(hexcli.Version(hexcli.VersionOptions{App: "myapp"}))
root.AddCommand(cmd.Auth(app), cmd.Token(app))
os.Exit(hexcli.Execute(root))
Index ¶
- func AddEnvFlag(cmd *cobra.Command)
- func AddLogLevelFlag(cmd *cobra.Command, defaultLevel string)
- func AddVerboseFlag(cmd *cobra.Command)
- func Execute(root *cobra.Command) int
- func FromContext(ctx context.Context) *hex.App
- func Root(opts RootOptions) *cobra.Command
- func Version(opts VersionOptions) *cobra.Command
- func WithApp(ctx context.Context, app *hex.App) context.Context
- func WithPreRun(cmd *cobra.Command, fn func(*cobra.Command, []string) error)
- type RootOptions
- type VersionOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddEnvFlag ¶
AddEnvFlag installs --env / -e for consumer apps that ship multiple environments (dev, staging, prod). hex reads the flag but has no opinion on what values are valid; the consumer's PersistentPreRun interprets it.
func AddLogLevelFlag ¶
AddLogLevelFlag installs the --log-level persistent flag on cmd with the given default. Safe to call on any Cobra command; typically only used on the root command.
func AddVerboseFlag ¶
AddVerboseFlag installs --verbose / -v as a boolean shortcut for --log-level=debug.
func Execute ¶
Execute runs root and returns a suggested process exit code: 0 on success, 1 on any non-nil error. Consumers with richer exit-code logic should write their own instead.
func FromContext ¶
FromContext extracts the *hex.App stored in ctx, or nil if none is present. Subcommands typically read it with:
app := hexcli.FromContext(cmd.Context())
func Root ¶
func Root(opts RootOptions) *cobra.Command
Root builds the top-level Cobra command with hex's standard wiring.
The returned command:
- Silences usage-on-error and error print by default; consumer apps handle their own error rendering.
- Carries opts.App in its context, retrievable via FromContext.
- Adds the --log-level, --env, and --verbose persistent flags. --log-level is applied to hex/log during PersistentPreRunE.
Consumer apps typically add subcommands and their own PersistentPreRun on top. When they wire their own PersistentPreRunE, it is called *after* hex's — see WithPreRun.
func Version ¶
func Version(opts VersionOptions) *cobra.Command
Version returns a Cobra `version` subcommand that renders build metadata from hex/build. It has no dependencies beyond hex/build and Cobra.
func WithPreRun ¶
WithPreRun chains fn to run after hex's default PersistentPreRunE on cmd. Both functions run in sequence; if hex's returns an error, fn is not called. Use this instead of overwriting PersistentPreRunE directly when you want to keep the --log-level / --verbose handling hex provides.
Types ¶
type RootOptions ¶
type RootOptions struct {
// Name is the command binary name (cobra.Command.Use).
Name string
// Short is the one-line description shown in help output.
Short string
// Long is the long-form description. If empty, Root leaves it unset so
// Cobra falls back to Short.
Long string
// App is the hex kernel to stash in the command context so subcommands
// can retrieve it via FromContext. Optional; may be nil for pure-help
// setups.
App *hex.App
// DefaultLogLevel is the value used for the --log-level flag default.
// Empty means the flag is added with an empty default (equivalent to
// "leave the current logger level alone until the user opts in").
DefaultLogLevel string
// SilenceUsage and SilenceErrors mirror the Cobra fields of the same
// name. Default: both true — hex apps generally render their own
// errors and don't want Cobra's usage dump on every failed run.
// Set the *Enable variants to force-enable one you want back.
EnableUsageOnError bool
EnableErrorPrint bool
}
RootOptions configures Root. Only Name is required.
type VersionOptions ¶
type VersionOptions struct {
// App is a human-readable app name used in the one-line short output
// (e.g. "myapp"). Falls back to the binary name if empty.
App string
// Long, when true, prints the multi-line build.Info block. When false
// (default), prints a single line.
Long bool
}
VersionOptions configures the version subcommand.
Source Files