cmdguard

https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard
Admin
A type-safe, DI-powered CLI framework for Go that provides safe command handling with dependency...
Tokens:43,254
Snippets:688
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Command Example Usage

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Example returns the example usage string.

```go
func (c Command[T, F]) Example() string
```

--------------------------------

### Command.Example

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Example returns the example usage string.

```APIDOC
## Command.Example

### Description
Example returns the example usage string.

### Signature
```go
func (c Command[T, F]) Example() string
```
```

--------------------------------

### Set Example Usage for a Command

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithExample to set the example usage string for a command. This helps users understand how to invoke the command.

```go
func WithExample[T, F any](example string) CommandOption[T, F]
```

--------------------------------

### WithExample

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the example usage for a command.

```APIDOC
## WithExample

### Description
Sets the example usage.

### Signature
```go
func WithExample[T, F any](example string) CommandOption[T, F]
```
```

--------------------------------

### Example: Timing Middleware

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

An example of a middleware that logs the execution duration of a command. It measures the time taken by the 'next' function and prints it to stderr.

```go
TimingMiddleware := func(ctx context.Context, cfg *MyConfig, info CommandInfo, next func() error) error {
    start := time.Now()
    err := next()
    fmt.Fprintf(os.Stderr, "%s took %v\n", info.Name, time.Since(start))
    return err
}
```

--------------------------------

### Example Output for NewCommand

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Demonstrates creating a leaf command with the constructor API.

```text
command created: hello
```

--------------------------------

### Get Command Version

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Version returns the version string.

```go
func (c Command[T, F]) Version() string
```

--------------------------------

### Example Output for MustNewCommand

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Demonstrates the panic variant for compile-time-known config with MustNewCommand.

```text
command: version
```

--------------------------------

### Get Command Short Description

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Short returns the short description shown in help.

```go
func (c Command[T, F]) Short() string
```

--------------------------------

### Get Command Name and Usage

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use returns the command name and usage string.

```go
func (c Command[T, F]) Use() string
```

--------------------------------

### Example: Create Command with Typed Flags

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Demonstrates creating a command with typed flags using the NewCommand constructor.

```text

```

--------------------------------

### Configure CLI with Output Format Flag

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Example demonstrating how to initialize a CLI with the WithOutputFormat option to enable a global --output/-o flag.

```go
cli, _ := v2.NewCLI[Config]("app", "My app", Config{},
    v2.WithOutputFormat[Config](v2.FormatTable),
)
// CLI now has --output/-o flag
// In handlers: format := cli.OutputFormat()
```

--------------------------------

### Get URL Scheme

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the scheme of the URL as a string. For example, "https".

```go
func (u URL) Scheme() string
```

--------------------------------

### Get URL Port

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the port number of the URL as a string. For example, "8080".

```go
func (u URL) Port() string
```

--------------------------------

### Get URL Path

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the path component of the URL.

```go
func (u URL) Path() string
```

--------------------------------

### Get Command Subcommands

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Commands returns the subcommands of this command.

```go
func (c Command[T, F]) Commands() []Command[T, F]
```

--------------------------------

### Get Short Description

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Short returns the short description of the CLI application, often used in command listings.

```go
func (cli *CLI[T]) Short() string
```

--------------------------------

### Get URL Hostname

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the hostname part of the URL without the port (e.g., "example.com").

```go
func (u URL) Hostname() string
```

--------------------------------

### Get Command Post-Run Handler

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

PostRunE returns the post-run cleanup hook.

```go
func (c Command[T, F]) PostRunE() func(ctx context.Context, cfg *T, flags F) error
```

--------------------------------

### Get Scope Name

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the name of the scope.

```go
func (s *Scope) Name() string
```

--------------------------------

### Get Command Pre-Run Handler

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

PreRunE returns the pre-run validation hook.

```go
func (c Command[T, F]) PreRunE() func(ctx context.Context, cfg *T, flags F) error
```

--------------------------------

### Get Command Aliases

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Aliases returns the alternative names for the command.

```go
func (c Command[T, F]) Aliases() []string
```

--------------------------------

### Get Command Long Description

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Long returns the long description shown in help.

```go
func (c Command[T, F]) Long() string
```

--------------------------------

### Get CLI Name

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Name returns the name of the CLI application, as defined during its creation.

```go
func (cli *CLI[T]) Name() string
```

--------------------------------

### Get URL Host

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the host part of the URL, including the port if present (e.g., "example.com:8080").

```go
func (u URL) Host() string
```

--------------------------------

### Get

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves a value from the context by key, returning the value and a boolean indicating if it was found.

```APIDOC
## Get

### Description
Retrieves a value associated with a key from the context.

### Function Signature
`func Get[T any](ctx context.Context, key any) (T, bool)`

### Parameters
* `ctx` (context.Context) - The context to retrieve the value from.
* `key` (any) - The key of the value to retrieve.

### Returns
* `T` - The retrieved value of type T.
* `bool` - True if the value was found, false otherwise.
```

--------------------------------

### Get Underlying url.URL

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the underlying *url.URL object. Returns nil if the URL was not properly initialized.

```go
func (u URL) URL() *url.URL
```

--------------------------------

### Get Context Path as String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path as a single string. This method is part of the FlowContextAccessor.

```go
func (a *FlowContextAccessor) PathString() string
```

--------------------------------

### Get Context Path

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path as a slice of strings. This method is part of the FlowContextAccessor.

```go
func (a *FlowContextAccessor) Path() []string
```

--------------------------------

### Get Full Scope Path

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the complete path of scopes from the root scope down to the current scope.

```go
func (s *Scope) Path() []string
```

--------------------------------

### Full Package Integration with DI

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

This pattern shows how to fully integrate the CLI package with the DI system by providing the CLI configuration directly to the do.New() function.

```go
injector := do.New(
    v2.Package[Config]("app", "My app", Config{}),
)
```

--------------------------------

### FlagRegistry.GenerateHelp Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Generates help text for all registered flags.

```go
func (r *FlagRegistry) GenerateHelp() string
```

--------------------------------

### Get Command Flags

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Flags returns the command-specific flags struct.

```go
func (c Command[T, F]) Flags() F
```

--------------------------------

### Get Command Deprecation Message

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Deprecated returns the deprecation message, if any.

```go
func (c Command[T, F]) Deprecated() string
```

--------------------------------

### Path Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path from the root context to this context as a slice of strings. Each string represents a command name in the path.

```go
func (b *BranchingFlowContext) Path() []string
```

--------------------------------

### FilePath.Join Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Joins a file path with additional components.

```go
func (fp FilePath) Join(elem ...string) FilePath
```

--------------------------------

### Command.Use

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use returns the command name and usage string.

```APIDOC
## Command.Use

### Description
Use returns the command name and usage string.

### Signature
```go
func (c Command[T, F]) Use() string
```
```

--------------------------------

### Get Command Run Handler

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

RunE returns the command handler function.

```go
func (c Command[T, F]) RunE() func(ctx context.Context, cfg *T, flags F) error
```

--------------------------------

### Get Output Format

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

OutputFormat returns the resolved output format, typically determined by the --output flag. Defaults to FormatTable if not specified.

```go
func (cli *CLI[T]) OutputFormat() OutputFormat
```

--------------------------------

### Command.Short

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Short returns the short description shown in help.

```APIDOC
## Command.Short

### Description
Short returns the short description shown in help.

### Signature
```go
func (c Command[T, F]) Short() string
```
```

--------------------------------

### Parse HostPort String (Panic on Error)

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a HostPort from a string, panicking if the format is invalid. Use when the input is known to be valid.

```go
func MustParseHostPort(s string) HostPort
```

--------------------------------

### Get Context Depth

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the current context depth. This method is part of the FlowContextAccessor.

```go
func (a *FlowContextAccessor) Depth() int
```

--------------------------------

### PathString Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path from the root context to this context as a dot-separated string. This provides a convenient string representation of the path.

```go
func (b *BranchingFlowContext) PathString() string
```

--------------------------------

### Get Duration in Milliseconds

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Milliseconds returns the Duration value represented in milliseconds as an int64.

```go
func (d Duration) Milliseconds() int64
```

--------------------------------

### Create CLI with Error Handling

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

NewCLI creates a new CLI application with typed configuration. It returns an error if initialization fails, providing a non-panicking alternative.

```go
func NewCLI[T any](name, short string, defaults T, opts ...CLIOption[T]) (*CLI[T], error)
```

--------------------------------

### Create Parent Command with Subcommands

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use NewParentCommand to create a parent command that includes subcommands. The long description and at least one subcommand are required.

```go
func NewParentCommand[T, F any](
	use string,
	long string,
	subcommands []Command[T, F],
	opts ...CommandOption[T, F],
) (Command[T, F], error)
```

```go
parent created: items
```

--------------------------------

### Create CLI with Panic on Failure

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

MustNewCLI creates a new CLI application or panics if initialization fails. Use this when a CLI application must be available.

```go
func MustNewCLI[T any](name, short string, defaults T, opts ...CLIOption[T]) *CLI[T]
```

--------------------------------

### Registering a Service Provider

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use Provide to register a service provider within a given scope. The provider is invoked lazily upon the first Invoke call. An error is returned only if the scope is nil.

```go
func Provide[T any](scope *Scope, provider func(do.Injector) (T, error)) error
```

--------------------------------

### Command.Version

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Version returns the version string.

```APIDOC
## Command.Version

### Description
Version returns the version string.

### Signature
```go
func (c Command[T, F]) Version() string
```
```

--------------------------------

### Short

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the short description of the CLI application.

```APIDOC
## Short

### Description
Returns the short description of the CLI application.

### Signature
```go
func (cli *CLI[T]) Short() string
```

### Returns
* `string` - The short description of the CLI.
```

--------------------------------

### Convert URL to String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the URL represented as a string.

```go
func (u URL) String() string
```

--------------------------------

### Get Port Component of HostPort

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the port component of a HostPort. This is a method on the HostPort struct.

```go
func (hp HostPort) Port() Port
```

--------------------------------

### Default Output Configuration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the default output configuration, which uses table format and writes to standard output. This provides a sensible default for most use cases.

```go
func DefaultOutputConfig() OutputConfig
```

--------------------------------

### Get Host Component of HostPort

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the host component of a HostPort. This is a method on the HostPort struct.

```go
func (hp HostPort) Host() string
```

--------------------------------

### Recommended CLI DI Integration Pattern

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

This pattern is recommended for managing dependency injection within the CLI. It involves creating a new CLI instance and then providing its scope and the CLI instance itself to the DI system.

```go
cli, err := v2.NewCLI[Config]("app", "My app", Config{})
if err != nil {
    return err
}
v2.ProvideValue(cli.Scope(), cli)
```

--------------------------------

### Get Underlying time.Duration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

The Duration method returns the underlying time.Duration value from a Duration object.

```go
func (d Duration) Duration() time.Duration
```

--------------------------------

### Set Output Format

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

SetOutputFormat allows setting the output format at runtime. This can override the format determined by flags.

```go
func (cli *CLI[T]) SetOutputFormat(format OutputFormat)
```

--------------------------------

### Get Command Group Name

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Group returns the command group name. Added in v1.0.0.

```go
func (c Command[T, F]) Group() string
```

--------------------------------

### Injecting Existing Scope with CLI

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

This pattern demonstrates how to inject an existing scope into the CLI. It's useful when you have an established DI scope and need to integrate the CLI into it.

```go
injector := do.New()
cli, err := v2.NewCLI[Config]("app", "My app", Config{})
if err != nil {
    return err
}
do.ProvideValue(injector, cli.Scope())
```

--------------------------------

### Branch Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new child context for a subcommand. The child inherits values and has its own cancellation.

```go
func (b *BranchingFlowContext) Branch(
	commandName string,
	opts ...FlowContextOption,
) (*BranchingFlowContext, func())
```

--------------------------------

### Get DI Scope

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Scope returns the dependency injection scope, which can be used for registering services.

```go
func (cli *CLI[T]) Scope() *Scope
```

--------------------------------

### FilePath Absolute Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the absolute path.

```go
func (fp FilePath) Absolute() string
```

--------------------------------

### Get

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves a typed value from the flow context. Returns the value and a boolean indicating if it was found.

```APIDOC
## Get

### Description
Retrieves a typed value from the flow context.

### Signature
```go
func Get[T any](ctx context.Context, key any) (T, bool)
```
```

--------------------------------

### Parse URL and Panic on Error

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a URL from a string, panicking if the string is not a valid URL. Use this only when the URL is known to be valid, such as for constants.

```go
func MustParseURL(s string) URL
```

--------------------------------

### ArgsFromContext

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves command-line arguments from the provided context.

```APIDOC
## ArgsFromContext

### Description
Extracts command-line arguments from a given context.

### Function Signature
`func ArgsFromContext(ctx context.Context) []string`

### Parameters
* `ctx` (context.Context) - The context from which to extract arguments.

### Returns
* `[]string` - A slice of strings representing the command-line arguments.
```

--------------------------------

### Marshal Duration to Text

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

MarshalText implements encoding.TextMarshaler for Duration, allowing it to be encoded as text, for example, in JSON or YAML.

```go
func (d Duration) MarshalText() ([]byte, error)
```

--------------------------------

### URL Structure

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Wraps url.URL with parsing validation and text marshaling. Use this for configuration fields that must be valid URLs.

```go
type URL struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### HostPort.String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the HostPort as a "host:port" string.

```APIDOC
## HostPort.String

### Description
String returns the host:port as a string.

### Signature
```go
func (hp HostPort) String() string
```
```

--------------------------------

### Package

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Defines a new CLI package with options.

```APIDOC
## Package

### Description
Defines a new CLI package, setting its name, short description, default values, and options.

### Function Signature
`func Package[T any](name, short string, defaults T, opts ...CLIOption[T]) func(do.Injector) T`

### Parameters
* `name` (string) - The name of the CLI package.
* `short` (string) - A short description of the CLI package.
* `defaults` (T) - The default values for the package's configuration.
* `opts` (...CLIOption[T]) - Options to configure the CLI package.

### Returns
* `func(do.Injector) T` - A function that provides the configured CLI package.
```

--------------------------------

### FilePath.Ext Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the file extension of a path.

```go
func (fp FilePath) Ext() string
```

--------------------------------

### Get Default Flag Value

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves the default value for a flag based on its type. This is useful for initializing flags.

```go
func (t FlagTag) DefaultValue() any
```

--------------------------------

### Email String Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the email address as a string.

```go
func (e Email) String() string
```

--------------------------------

### Get Long Description

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Long returns the long description of the CLI application, typically used for help messages.

```go
func (cli *CLI[T]) Long() string
```

--------------------------------

### Execute CLI Application

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Execute runs the CLI application. It wraps the provided context with a BranchingFlowContext for command path tracking and supports signal handling for graceful shutdown.

```go
func (cli *CLI[T]) Execute(ctx context.Context) error
```

--------------------------------

### Set Subcommands for a Command

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithSubcommands to set the subcommands for a command. This allows for hierarchical command structures.

```go
func WithSubcommands[T, F any](cmds ...Command[T, F]) CommandOption[T, F]
```

--------------------------------

### Get Function Signature

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves a typed value from the flow context. Returns the value and a boolean indicating if it was found.

```go
func Get[T any](ctx context.Context, key any) (T, bool)
```

--------------------------------

### WithShort

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the short description for a command.

```APIDOC
## WithShort

### Description
Sets the short description.

### Signature
```go
func WithShort[T, F any](short string) CommandOption[T, F]
```
```

--------------------------------

### NewCLI

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new CLI application with typed config. Returns an error if initialization fails (never panics). T is the application config type.

```APIDOC
## NewCLI

### Description
Creates a new CLI application with typed config. Returns an error if initialization fails (never panics). T is the application config type.

### Signature
```go
func NewCLI[T any](name, short string, defaults T, opts ...CLIOption[T]) (*CLI[T], error)
```

### Parameters
* `name` (string) - The name of the CLI application.
* `short` (string) - A short description of the CLI application.
* `defaults` (T) - The default configuration values for the application.
* `opts` (...CLIOption[T]) - Optional configuration options for the CLI.

### Returns
* `*CLI[T]` - A pointer to the initialized CLI application.
* `error` - An error if initialization fails.
```

--------------------------------

### Get Parent Scope

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the parent scope of the current scope. Returns nil if the current scope is a root scope.

```go
func (s *Scope) Parent() *Scope
```

--------------------------------

### Get DI Injector

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Injector returns the underlying dependency injection container, allowing for direct use of samber/do/v2 operations.

```go
func (cli *CLI[T]) Injector() do.Injector
```

--------------------------------

### Get Resolved Configuration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Config returns the resolved configuration object for the CLI application. This is the typed configuration provided during initialization.

```go
func (cli *CLI[T]) Config() *T
```

--------------------------------

### FilePath.String Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the original (cleaned) file path.

```go
func (fp FilePath) String() string
```

--------------------------------

### Parse HostPort String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a HostPort from a string, supporting formats like 'host:port', 'example.com:443', or ':8080'. Returns an error for invalid formats.

```go
func ParseHostPort(s string) (HostPort, error)
```

--------------------------------

### Get Underlying DI Injector

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the underlying dependency injection injector for the scope. This allows for direct operations with the DI container.

```go
func (s *Scope) Injector() do.Injector
```

--------------------------------

### Get Port as Integer

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the port number as an integer. Useful for using the port value in contexts that expect a standard int.

```go
func (p Port) Int() int
```

--------------------------------

### Log Format Constants

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Log format constants for different output formats.

```go
var (
	LogFormatText = LogFormat{/* contains filtered or unexported fields */}
	LogFormatJSON = LogFormat{/* contains filtered or unexported fields */}
)
```

--------------------------------

### Package Function for DI Integration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use this function to integrate Command Guard with samber/do for dependency injection. It follows best practices for library integration. CLI initialization errors are not returned directly; handle them separately or use WithCLIScope().

```go
func Package[T any](name, short string, defaults T, opts ...CLIOption[T]) func(do.Injector)
```

--------------------------------

### LogLevel.MarshalText

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Implements encoding.TextMarshaler for LogLevel. This allows LogLevel values to be easily marshaled into text format, for example, when encoding to JSON or other text-based formats.

```APIDOC
## LogLevel.MarshalText

### Description
Implements encoding.TextMarshaler for LogLevel.

### Signature
```go
func (l LogLevel) MarshalText() ([]byte, error)
```
```

--------------------------------

### NewParentCommand

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a parent command with subcommands. Both the long description and at least one subcommand are required.

```APIDOC
## NewParentCommand

### Description
Creates a parent command with subcommands. The long description and at least one subcommand are required. This makes it impossible to forget the Long description when adding subcommands.

### Signature
```go
func NewParentCommand[T, F any](
	use string,
	long string,
	subcommands []Command[T, F],
	opts ...CommandOption[T, F],
) (Command[T, F], error)
```

### Example
```go
parent created: items
```
```

--------------------------------

### Parse Port from String (Panic on Error)

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a Port from a string, panicking if the string is invalid. Use this only when the port value is known to be valid at compile time, such as for constants.

```go
func MustParsePort(s string) Port
```

--------------------------------

### Get Root Cobra Command

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

RootCommand returns the underlying cobra.Command instance that serves as the root of the CLI application's command tree.

```go
func (cli *CLI[T]) RootCommand() *cobra.Command
```

--------------------------------

### Convert HostPort to String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the HostPort as a 'host:port' string. This is a method on the HostPort struct.

```go
func (hp HostPort) String() string
```

--------------------------------

### NewHostPort

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a HostPort from host and port strings, returning an error if the format is invalid.

```APIDOC
## NewHostPort

### Description
NewHostPort creates a HostPort from host and port strings.

### Signature
```go
func NewHostPort(host, portStr string) (HostPort, error)
```
```

--------------------------------

### Get Branching Flow Context

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

FlowContext returns the BranchingFlowContext used for tracking command execution paths. This context is only available after Execute has been called.

```go
func (cli *CLI[T]) FlowContext() *BranchingFlowContext
```

--------------------------------

### Getting Value or Default

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

ValueOrDefault returns the dereferenced value if the pointer is not nil, otherwise it returns the provided default value. This is useful for handling optional fields gracefully.

```go
func ValueOrDefault[T any](v *T, def T) T
```

--------------------------------

### Package

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Registers a samber/do package function for DI integration, following best practices for library integration. Applications should handle CLI initialization errors separately or use WithCLIScope().

```APIDOC
## Package

### Description
Package returns a samber/do package function for DI integration. This follows samber/do best practices for library integration. Note: CLI initialization errors cannot be returned from Package() because do.Package expects a void function. Applications should call NewCLI() separately and handle errors, or use WithCLIScope() option for CLI-managed DI.

### Usage Patterns

**Pattern 1 (Recommended - let CLI manage DI):**
```go
cli, err := v2.NewCLI[Config]("app", "My app", Config{})
if err != nil {
    return err
}
v2.ProvideValue(cli.Scope(), cli)
```

**Pattern 2 (Inject existing scope):**
```go
injector := do.New()
cli, err := v2.NewCLI[Config]("app", "My app", Config{})
if err != nil {
    return err
}
do.ProvideValue(injector, cli.Scope())
```

**Pattern 3 (Full package integration):**
```go
injector := do.New(
    v2.Package[Config]("app", "My app", Config{}),
)
```
```

--------------------------------

### WithSubcommands

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the subcommands for a command.

```APIDOC
## WithSubcommands

### Description
Sets the subcommands.

### Signature
```go
func WithSubcommands[T, F any](cmds ...Command[T, F]) CommandOption[T, F]
```
```

--------------------------------

### MustNewCLI

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new CLI application or panics if initialization fails. This is the recommended API for new code (v2.1+). T represents the application config type, and commands can have any flags type.

```APIDOC
## MustNewCLI

### Description
Creates a new CLI application or panics. This is the recommended API for new code (v2.1+). T represents the application config type, and commands can have any flags type.

### Signature
```go
func MustNewCLI[T any](name, short string, defaults T, opts ...CLIOption[T]) *CLI[T]
```

### Parameters
* `name` (string) - The name of the CLI application.
* `short` (string) - A short description of the CLI application.
* `defaults` (T) - The default configuration values for the application.
* `opts` (...CLIOption[T]) - Optional configuration options for the CLI.

### Returns
* `*CLI[T]` - A pointer to the initialized CLI application.
```

--------------------------------

### Create New Executable Command

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

NewCommand creates a new executable command with the given options. The runE parameter is required and cannot be nil. Use NewParentCommand for commands with subcommands.

```go
func NewCommand[T, F any](
	use string,
	runE func(ctx context.Context, cfg *T, flags F) error,
	opts ...CommandOption[T, F],
) (Command[T, F], error)
```

--------------------------------

### WithRunE

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the command handler function.

```APIDOC
## WithRunE

### Description
Sets the command handler.

### Signature
```go
func WithRunE[T, F any](runE func(ctx context.Context, cfg *T, flags F) error) CommandOption[T, F]
```
```

--------------------------------

### Default Application Configuration Structure

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

The Config struct defines the default application configuration, including LogLevel, LogFormat, StrictMode, and ConfigFile. Custom configs should embed or mirror this structure.

```go
type Config struct {
	LogLevel   LogLevel  `default:"info"  flag:"log-level"  help:"Log level: debug, info, warn, error" short:"l"`
	LogFormat  LogFormat `default:"text"  flag:"log-format" help:"Log format: text, json"`
	StrictMode bool      `default:"false" flag:"strict"     help:"Enable strict mode validation"       short:"s"`
	ConfigFile string    `default:""      flag:"config"     help:"Path to config file"                 short:"c"`
}
```

--------------------------------

### Create New Root Scope

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new root scope for dependency management. This is the entry point for creating a scope hierarchy.

```go
func NewScope(name string) *Scope
```

--------------------------------

### Execute

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Runs the CLI application. The context is wrapped with a BranchingFlowContext for command path tracking. If WithSignalHandling was set, the context is cancelled on SIGINT/SIGTERM.

```APIDOC
## Execute

### Description
Runs the CLI application. The context is wrapped with a BranchingFlowContext for command path tracking. If WithSignalHandling was set, the context is cancelled on SIGINT/SIGTERM.

### Signature
```go
func (cli *CLI[T]) Execute(ctx context.Context) error
```

### Parameters
* `ctx` (context.Context) - The context for the execution.

### Returns
* `error` - An error if the execution fails.
```

--------------------------------

### BranchWithDeadline Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a child context with a deadline for a subcommand. This method parses a string deadline at runtime.

```go
func (b *BranchingFlowContext) BranchWithDeadline(
	commandName string,
	deadline string,
	opts ...FlowContextOption,
) (*BranchingFlowContext, func(), error)
```

--------------------------------

### Create HostPort from Host and Port Strings

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a HostPort from separate host and port strings. Returns an error if the port string is invalid.

```go
func NewHostPort(host, portStr string) (HostPort, error)
```

--------------------------------

### Ptr

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns a pointer to any value. Useful for optional configuration fields.

```APIDOC
## Ptr

### Description
Ptr returns a pointer to any value. Useful for optional config fields.

### Signature
```go
func Ptr[T any](v T) *T
```
```

--------------------------------

### Output Configuration Structure

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Holds the configuration for output formatting, including the desired format and the writer to use. Used to control how command results are presented.

```go
type OutputConfig struct {
	Format OutputFormat
	Writer io.Writer
}
```

--------------------------------

### SuggestCommand

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Suggests a command based on user input.

```APIDOC
## SuggestCommand

### Description
Provides a command suggestion based on partial user input and a list of valid commands.

### Function Signature
`func SuggestCommand(validCommands []string, input string) (string, bool)`

### Parameters
* `validCommands` ([]string) - A list of valid command names.
* `input` (string) - The user's input string.

### Returns
* `string` - The suggested command name.
* `bool` - True if a suggestion was found, false otherwise.
```

--------------------------------

### Set Version String for CLI

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithCLIVersion to set the version string for the CLI. This option is of type CLIOption.

```go
func WithCLIVersion[T any](version string) CLIOption[T]
```

--------------------------------

### WithPostRunE

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the post-run cleanup hook for a command.

```APIDOC
## WithPostRunE

### Description
Sets the post-run cleanup hook.

### Signature
```go
func WithPostRunE[T, F any](postRunE func(ctx context.Context, cfg *T, flags F) error) CommandOption[T, F]
```
```

--------------------------------

### Set Short Description for a Command

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithShort to set the short description for a command. This provides a brief summary of the command's purpose.

```go
func WithShort[T, F any](short string) CommandOption[T, F]
```

--------------------------------

### FilePath.Base Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the last component of a file path.

```go
func (fp FilePath) Base() string
```

--------------------------------

### Name

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the name of the CLI application.

```APIDOC
## Name

### Description
Returns the name of the CLI application.

### Signature
```go
func (cli *CLI[T]) Name() string
```

### Returns
* `string` - The name of the CLI.
```

--------------------------------

### ArgsFromContext Function Signature

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves positional arguments from the current command's context. Use this in RunE handlers to access positional arguments.

```go
func ArgsFromContext(ctx context.Context) []string
```

--------------------------------

### FlagRegistry.SetEnvPrefix Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets an environment variable prefix for this registry. Env tag lookups will prepend this prefix.

```go
func (r *FlagRegistry) SetEnvPrefix(prefix string)
```

--------------------------------

### FilePath.IsEmpty Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Checks if a file path is empty.

```go
func (fp FilePath) IsEmpty() bool
```

--------------------------------

### HostPort.IsEmpty

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Checks if both the host and port components of the HostPort are empty.

```APIDOC
## HostPort.IsEmpty

### Description
IsEmpty returns true if both host and port are empty.

### Signature
```go
func (hp HostPort) IsEmpty() bool
```
```

--------------------------------

### Root Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the root context of this context's tree. Use this to access the top-level context from any descendant.

```go
func (b *BranchingFlowContext) Root() *BranchingFlowContext
```

--------------------------------

### Parse Output Format from String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Parses a string into an OutputFormat. Used for converting string-based configuration or user input into a valid output format.

```go
func ParseOutputFormat(s string) (OutputFormat, error)
```

--------------------------------

### Set Command Visibility

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithHidden to set whether a command is hidden from help output. Accepts a boolean value.

```go
func WithHidden[T, F any](hidden bool) CommandOption[T, F]
```

--------------------------------

### Parent Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the parent context of this context, or nil if this is the root context. Use this to navigate up the context tree.

```go
func (b *BranchingFlowContext) Parent() *BranchingFlowContext
```

--------------------------------

### Parse Port from String (Return Error)

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new Port from a string. Accepts numeric strings (e.g., "8080") or named ports (e.g., "http", "https"). Returns an error if the port is not valid.

```go
func ParsePort(s string) (Port, error)
```

--------------------------------

### BranchWithDeadlineTime Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a child context with a deadline for a subcommand using a time.Time object. Prefer this over BranchWithDeadline.

```go
func (b *BranchingFlowContext) BranchWithDeadlineTime(
	commandName string,
	deadline time.Time,
	opts ...FlowContextOption,
) (*BranchingFlowContext, func())
```

--------------------------------

### Parse URL with Error Handling

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new URL from a string. Returns an error if the string is not a valid URL.

```go
func ParseURL(s string) (URL, error)
```

--------------------------------

### Enable/Disable Colored Output (Deprecated)

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

WithColor enables or disables colored output from fang. This option is deprecated and will be removed in v3.0. Use WithFang instead.

```go
func WithColor[T any](enabled bool) CLIOption[T]
```

--------------------------------

### FlagRegistry.ParseFlags Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Populates a configuration struct by parsing flags from a cobra command.

```go
func (r *FlagRegistry) ParseFlags(cmd *cobra.Command, cfg any) error
```

--------------------------------

### NewFlagRegistry Function

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new FlagRegistry instance from a configuration struct.

```go
func NewFlagRegistry(cfg any) (*FlagRegistry, error)
```

--------------------------------

### Duration String Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the duration as a string.

```go
func (d Duration) String() string
```

--------------------------------

### Command.PostRunE

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

PostRunE returns the post-run cleanup hook.

```APIDOC
## Command.PostRunE

### Description
PostRunE returns the post-run cleanup hook.

### Signature
```go
func (c Command[T, F]) PostRunE() func(ctx context.Context, cfg *T, flags F) error
```
```

--------------------------------

### FilePath.Dir Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the directory component of a file path.

```go
func (fp FilePath) Dir() string
```

--------------------------------

### Log Level Constants

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Log level constants for different logging severities.

```go
var (
	LogLevelDebug = LogLevel{/* contains filtered or unexported fields */}
	LogLevelInfo  = LogLevel{/* contains filtered or unexported fields */}
	LogLevelWarn  = LogLevel{/* contains filtered or unexported fields */}
	LogLevelError = LogLevel{/* contains filtered or unexported fields */}
)
```

--------------------------------

### NewScope

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a new root scope for managing services and configurations.

```APIDOC
## NewScope

### Description
Creates a new root scope.

### Signature
```go
func NewScope(name string) *Scope
```
```

--------------------------------

### OutputStyledTable Function Signature

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Renders a styled terminal table using lipgloss. Provides visually appealing table output.

```go
func OutputStyledTable(headers []string, rows [][]string) error
```

--------------------------------

### GenerateManPageCommand

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a cobra command that generates man pages. Add this as a subcommand to provide `myapp man` functionality.

```APIDOC
## GenerateManPageCommand

### Description
Creates a cobra command that generates man pages. Add this as a subcommand to provide `myapp man` functionality.

### Signature
```go
func GenerateManPageCommand[T any](cli *CLI[T]) (*cobra.Command, error)
```
```

--------------------------------

### Children Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the child contexts of this context. Use this to iterate over or inspect direct descendants.

```go
func (b *BranchingFlowContext) Children() []*BranchingFlowContext
```

--------------------------------

### Convert Port to String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the port number as a string. Useful for logging or display purposes.

```go
func (p Port) String() string
```

--------------------------------

### Timing Middleware Factory

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns a middleware that logs command execution duration. The provided log function receives the command name and duration, allowing for custom logging implementations.

```go
func TimingMiddleware[T any](log func(commandName string, d time.Duration)) Middleware[T]
```

--------------------------------

### Email Address Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the email address.

```go
func (e Email) Address() string
```

--------------------------------

### Set Fang Options

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithFangOptions to set fang options for the CLI's Execute method. Available since v1.0.0.

```go
func WithFangOptions[T any](opts ...fang.Option) CLIOption[T]
```

--------------------------------

### HostPort.Host

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the host component of the HostPort.

```APIDOC
## HostPort.Host

### Description
Host returns the host component.

### Signature
```go
func (hp HostPort) Host() string
```
```

--------------------------------

### TimingMiddleware

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns a middleware that logs command execution duration. The log function receives the command name and duration, allowing for performance monitoring.

```APIDOC
## TimingMiddleware

### Description
TimingMiddleware returns a middleware that logs command execution duration. The log function receives the command name and duration.

### Signature
```go
func TimingMiddleware[T any](log func(commandName string, d time.Duration)) Middleware[T]
```
```

--------------------------------

### Set CLI Configuration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

SetConfig updates the CLI application's configuration. Warning: This replaces the config pointer but does NOT reinitialize the FlagRegistry. Use with caution before Execute or if not using the typed flag system.

```go
func (cli *CLI[T]) SetConfig(cfg T)
```

--------------------------------

### FilePath.Exists Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Checks if a file path exists.

```go
func (fp FilePath) Exists() bool
```

--------------------------------

### Set Post-Run Cleanup Hook

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithPostRunE to set a post-run cleanup hook for a command. This function executes after the command's main logic and can return an error.

```go
func WithPostRunE[T, F any](
	postRunE func(ctx context.Context, cfg *T, flags F) error,
) CommandOption[T, F]
```

--------------------------------

### String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

String returns the URL as a formatted string.

```APIDOC
## String

### Description
String returns the URL as a string.

### Signature
```go
func (u URL) String() string
```
```

--------------------------------

### WithPreRunE

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the pre-run validation hook for a command.

```APIDOC
## WithPreRunE

### Description
Sets the pre-run validation hook.

### Signature
```go
func WithPreRunE[T, F any](preRunE func(ctx context.Context, cfg *T, flags F) error) CommandOption[T, F]
```
```

--------------------------------

### OutputStyledTable

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Renders a styled terminal table using lipgloss. This provides a visually appealing way to display tabular data.

```APIDOC
## OutputStyledTable

### Description
Renders a styled terminal table using lipgloss.

### Signature
```go
func OutputStyledTable(headers []string, rows [][]string) error
```
```

--------------------------------

### GenerateManPageCommand Function Signature

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Creates a cobra command that generates man pages. Add this as a subcommand to provide `myapp man` functionality.

```go
func GenerateManPageCommand[T any](cli *CLI[T]) (*cobra.Command, error)
```

--------------------------------

### SetValue Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets a value in this context and propagates it to all descendants. Use this to share data down the command tree.

```go
func (b *BranchingFlowContext) SetValue(key, value any)
```

--------------------------------

### Command Creation

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

CmdGuard provides functions to create new commands, both leaf and parent. `MustNewCommand` and `NewCommand` are used for leaf commands, while `MustNewParentCommand` and `NewParentCommand` are for parent commands that contain subcommands. These functions ensure type-safe command construction.

```APIDOC
## Command Creation

### Description
CmdGuard allows for the creation of type-safe CLI commands using constructor functions. These functions enforce valid states at compile time by making command fields unexported.

### Leaf Commands:
- **MustNewCommand[T, F any](use string, runE func(ctx context.Context, cfg *T, flags F) error, opts ...CommandOption[T, F]) Command[T, F]**: Creates a leaf command or panics if configuration is invalid. Use when command configuration is known at compile time.
- **NewCommand[T, F any](use string, runE func(ctx context.Context, cfg *T, flags F) error, opts ...CommandOption[T, F]) (Command[T, F], error)**: Creates a new executable leaf command. The `runE` parameter is required.

### Parent Commands:
- **MustNewParentCommand[T, F any](use string, long string, subcommands []Command[T, F], opts ...CommandOption[T, F]) Command[T, F]**: Creates a parent command or panics. Use when command configuration is known at compile time.
- **NewParentCommand[T, F any](use string, long string, subcommands []Command[T, F], opts ...CommandOption[T, F]) (Command[T, F], error)**: Creates a new parent command with subcommands.
```

--------------------------------

### ArgsFromContext

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves the positional arguments passed to the current command from the context. Use this in RunE handlers to access positional arguments.

```APIDOC
## ArgsFromContext

### Description
Retrieves the positional arguments passed to the current command. Use this in RunE handlers to access positional args, since cmdguard's RunE signature does not include a []string args parameter.

### Signature
```go
func ArgsFromContext(ctx context.Context) []string
```
```

--------------------------------

### FilePath.MarshalText Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Implements encoding.TextMarshaler for FilePath.

```go
func (fp FilePath) MarshalText() ([]byte, error)
```

--------------------------------

### Set Pre-Run Validation Hook

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Use WithPreRunE to set a pre-run validation hook for a command. This function executes before the command's main logic and can return an error.

```go
func WithPreRunE[T, F any](
	preRunE func(ctx context.Context, cfg *T, flags F) error,
) CommandOption[T, F]
```

--------------------------------

### Convert Log Level to String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the log level as a human-readable string. Useful for logging or display purposes.

```go
func (l LogLevel) String() string
```

--------------------------------

### Set Version String

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

SetVersion sets the version string for the CLI application. This is typically displayed with version flags.

```go
func (cli *CLI[T]) SetVersion(version string)
```

--------------------------------

### Add Middleware to Command Handlers

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

WithMiddleware adds middleware that wraps every command handler. Middleware are applied in order. Available since v1.0.0.

```go
func WithMiddleware[T any](mw ...Middleware[T]) CLIOption[T]
```

--------------------------------

### Execute CLI and Exit

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

ExecuteAndExit runs the CLI application and exits the program with the appropriate exit code based on the execution result.

```go
func (cli *CLI[T]) ExecuteAndExit(ctx context.Context)
```

--------------------------------

### MustGet

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Retrieves a value from the context by key, panicking if the value is not found.

```APIDOC
## MustGet

### Description
Retrieves a value associated with a key from the context, panicking if the key is not found.

### Function Signature
`func MustGet[T any](ctx context.Context, key any) T`

### Parameters
* `ctx` (context.Context) - The context to retrieve the value from.
* `key` (any) - The key of the value to retrieve.

### Returns
* `T` - The retrieved value of type T.
```

--------------------------------

### OutputResult Function Signature

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Renders data in the configured output format. This is a high-level function for displaying results.

```go
func OutputResult(cfg OutputConfig, data any) error
```

--------------------------------

### ExecuteWithArgs

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Runs the CLI application with specific arguments. This is useful for testing or programmatic invocation of the CLI.

```APIDOC
## ExecuteWithArgs

### Description
Runs the CLI application with specific arguments. This is useful for testing or programmatic invocation of the CLI.

### Signature
```go
func (cli *CLI[T]) ExecuteWithArgs(ctx context.Context, args []string) error
```

### Parameters
* `ctx` (context.Context) - The context for the execution.
* `args` ([]string) - A slice of strings representing the command-line arguments.

### Returns
* `error` - An error if the execution fails.
```

--------------------------------

### SetVersion

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the version string for the CLI application.

```APIDOC
## SetVersion

### Description
Sets the version string for the CLI application.

### Signature
```go
func (cli *CLI[T]) SetVersion(version string)
```

### Parameters
* `version` (string) - The version string to set.
```

--------------------------------

### Email Local Method

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the local part of the email (before @).

```go
func (e Email) Local() string
```

--------------------------------

### WithDeprecated

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Marks the command as deprecated.

```APIDOC
## WithDeprecated

### Description
Marks the command as deprecated.

### Signature
```go
func WithDeprecated[T, F any](msg string) CommandOption[T, F]
```
```

--------------------------------

### FlowContextAccessor.Path

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path as a slice of strings.

```APIDOC
## FlowContextAccessor.Path

### Description
Path returns the command path.

### Signature
```go
func (a *FlowContextAccessor) Path() []string
```
```

--------------------------------

### SetOutputFormat

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Sets the output format at runtime. Added in v1.0.0.

```APIDOC
## SetOutputFormat

### Description
Sets the output format at runtime. Added in v1.0.0.

### Signature
```go
func (cli *CLI[T]) SetOutputFormat(format OutputFormat)
```

### Parameters
* `format` (OutputFormat) - The desired output format.
```

--------------------------------

### BranchingFlowContext.Path

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Returns the command path from root to this context.

```APIDOC
## BranchingFlowContext.Path

### Description
Returns the command path from root to this context.

### Signature
```go
func (b *BranchingFlowContext) Path() []string
```
```

--------------------------------

### Validate Command Configuration

Source: https://pkg.go.dev/github.com/larsartmann/cmdguard/pkg/cmdguard/v2

Validate checks that the command is properly configured.

```go
func (c Command[T, F]) Validate() error
```
Tokens:
Raw