Documentation
¶
Overview ¶
Package cli provides a public API for extending and customizing the Flow CLI.
This package allows external projects to:
- Build custom CLIs that include Flow's commands
- Add cross-cutting hooks (PreRun/PostRun) to commands
- Override existing commands with custom implementations
- Add new commands alongside Flow's built-in commands
Basic Usage ¶
Build a custom CLI with all Flow commands:
ctx := context.NewContext(...)
rootCmd := cli.BuildRootCommand(ctx)
cli.RegisterAllCommands(ctx, rootCmd)
if err := cli.Execute(ctx, rootCmd); err != nil {
log.Fatal(err)
}
Customizing the Root Command ¶
Use functional options to customize the root command:
rootCmd := cli.BuildRootCommand(ctx,
cli.WithVersion("1.0.0-custom"),
cli.WithShort("My custom Flow CLI"),
cli.WithPersistentPreRun(myPreRunHook),
)
Adding Hooks ¶
Add hooks to individual commands or recursively to all commands:
// Add to a single command cli.AddPreRunHook(cmd, telemetryHook) // Add to all commands recursively cli.ApplyHooksRecursive(rootCmd, preHook, postHook)
Command Registry Operations ¶
Manipulate the command tree:
// Find a command
wsCmd := cli.FindCommand(rootCmd, "workspace")
// Replace a command
cli.ReplaceCommand(rootCmd, "exec", customExecCmd)
// Walk all commands
cli.WalkCommands(rootCmd, func(cmd *cobra.Command) {
// Do something with each command
})
Thread Safety ¶
This package is not thread-safe. Command building and modification should be done during CLI initialization, not concurrently.
Index ¶
- func AddPersistentPostRunHook(cmd *cobra.Command, hook HookFunc)
- func AddPersistentPreRunHook(cmd *cobra.Command, hook HookFunc)
- func AddPostRunHook(cmd *cobra.Command, hook HookFunc)
- func AddPreRunHook(cmd *cobra.Command, hook HookFunc)
- func BuildRootCommand(ctx *context.Context, opts ...RootOption) *cobra.Command
- func Execute(ctx *context.Context, rootCmd *cobra.Command) error
- func FindCommand(rootCmd *cobra.Command, name string) *cobra.Command
- func FindCommandPath(rootCmd *cobra.Command, path string) *cobra.Command
- func GetSubcommands(cmd *cobra.Command) map[string]*cobra.Command
- func ListCommands(rootCmd *cobra.Command) []string
- func RegisterAllCommands(ctx *context.Context, rootCmd *cobra.Command)
- func RemoveCommand(rootCmd *cobra.Command, name string) error
- func ReplaceCommand(rootCmd *cobra.Command, oldName string, newCmd *cobra.Command) error
- func WalkCommands(rootCmd *cobra.Command, fn func(*cobra.Command))
- type HookFunc
- type RootConfig
- type RootOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddPersistentPostRunHook ¶
AddPersistentPostRunHook adds a PersistentPostRun hook to a command, preserving any existing hook. If the command already has a PersistentPostRun hook, the new hook will run after it.
PersistentPostRun hooks run after all commands in the subtree.
func AddPersistentPreRunHook ¶
AddPersistentPreRunHook adds a PersistentPreRun hook to a command, preserving any existing hook. If the command already has a PersistentPreRun hook, the new hook will run before it.
PersistentPreRun hooks run before all commands in the subtree.
func AddPostRunHook ¶
AddPostRunHook adds a PostRun hook to a command, preserving any existing PostRun hook. If the command already has a PostRun hook, the new hook will run after it.
func AddPreRunHook ¶
AddPreRunHook adds a PreRun hook to a command, preserving any existing PreRun hook. If the command already has a PreRun hook, the new hook will run before it.
func BuildRootCommand ¶
func BuildRootCommand(ctx *context.Context, opts ...RootOption) *cobra.Command
BuildRootCommand creates a new root command with optional configuration. The root command is the main entry point for the CLI.
By default, this creates a root command with Flow's standard configuration. Use RootOption functions to customize the command.
func FindCommand ¶
FindCommand finds a command by name in the command tree. It performs a breadth-first search starting from the root.
Returns nil if the command is not found.
func FindCommandPath ¶
FindCommandPath finds a command by its full path (e.g., "workspace add"). The path should be space-separated command names.
Returns nil if the command is not found.
func GetSubcommands ¶
GetSubcommands returns a map of subcommand names to commands for a given command. This is a convenience wrapper around cobra's Commands() method.
func ListCommands ¶
ListCommands returns a list of all command names in the tree. The list includes the root command and all subcommands.
func RegisterAllCommands ¶
RegisterAllCommands registers all Flow commands to the root command.
func RemoveCommand ¶
RemoveCommand removes a command by name from the command tree.
Returns an error if the command is not found or if it's the root command.
func ReplaceCommand ¶
ReplaceCommand replaces a command with the given name with a new command. The new command will be added to the same parent as the old command.
Returns an error if the old command is not found or if the replacement fails.
Types ¶
type HookFunc ¶
HookFunc is a function that can be used as a PreRun or PostRun hook for a command. It receives the command being executed and its arguments.
type RootConfig ¶
type RootConfig struct {
// Use is the one-line usage message (defaults to "flow")
Use string
// Short is the short description shown in help (defaults to Flow's standard description)
Short string
// Long is the long description shown in help (defaults to Flow's standard description)
Long string
// Version is the version string (defaults to Flow's current version)
Version string
}
RootConfig holds configuration options for building the root command.
type RootOption ¶
type RootOption func(*RootConfig)
RootOption is a functional option for configuring the root command.
func WithLong ¶
func WithLong(long string) RootOption
WithLong sets the Long description for the root command.
func WithShort ¶
func WithShort(short string) RootOption
WithShort sets the Short description for the root command.
func WithVersion ¶
func WithVersion(version string) RootOption
WithVersion sets the Version string for the root command.
Source Files
Directories