cli

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2026 License: EUPL-1.2 Imports: 23 Imported by: 0

Documentation

Overview

Package cli provides the CLI runtime and utilities.

Package cli provides the CLI runtime and utilities.

Package cli provides the CLI runtime and utilities.

The CLI uses the Core framework for its own runtime. Usage is simple: 

cli.Init(cli.Options{AppName: "core"})
defer cli.Shutdown()

cli.Success("Done!")
cli.Error("Failed")
if cli.Confirm("Proceed?") { ... }

// When you need the Core instance
c := cli.Core()

Package cli provides semantic CLI output with zero external dependencies.

Index

Constants

View Source 
const (
	// LogLevelQuiet suppresses all output.
	LogLevelQuiet = log.LevelQuiet
	// LogLevelError shows only error messages.
	LogLevelError = log.LevelError
	// LogLevelWarn shows warnings and errors.
	LogLevelWarn = log.LevelWarn
	// LogLevelInfo shows info, warnings, and errors.
	LogLevelInfo = log.LevelInfo
	// LogLevelDebug shows all messages including debug.
	LogLevelDebug = log.LevelDebug
)

Log level constants aliased from the log package.

View Source 
const (
	ColourBlue50     = "#eff6ff"
	ColourBlue100    = "#dbeafe"
	ColourBlue200    = "#bfdbfe"
	ColourBlue300    = "#93c5fd"
	ColourBlue400    = "#60a5fa"
	ColourBlue500    = "#3b82f6"
	ColourBlue600    = "#2563eb"
	ColourBlue700    = "#1d4ed8"
	ColourGreen400   = "#4ade80"
	ColourGreen500   = "#22c55e"
	ColourGreen600   = "#16a34a"
	ColourRed400     = "#f87171"
	ColourRed500     = "#ef4444"
	ColourRed600     = "#dc2626"
	ColourAmber400   = "#fbbf24"
	ColourAmber500   = "#f59e0b"
	ColourAmber600   = "#d97706"
	ColourOrange500  = "#f97316"
	ColourYellow500  = "#eab308"
	ColourEmerald500 = "#10b981"
	ColourPurple500  = "#a855f7"
	ColourViolet400  = "#a78bfa"
	ColourViolet500  = "#8b5cf6"
	ColourIndigo500  = "#6366f1"
	ColourCyan500    = "#06b6d4"
	ColourGray50     = "#f9fafb"
	ColourGray100    = "#f3f4f6"
	ColourGray200    = "#e5e7eb"
	ColourGray300    = "#d1d5db"
	ColourGray400    = "#9ca3af"
	ColourGray500    = "#6b7280"
	ColourGray600    = "#4b5563"
	ColourGray700    = "#374151"
	ColourGray800    = "#1f2937"
	ColourGray900    = "#111827"
)

Tailwind colour palette (hex strings)

View Source 
const (
	// AppName is the CLI application name.
	AppName = "core"
)

Variables

View Source 
var (
	SuccessStyle = NewStyle().Bold().Foreground(ColourGreen500)
	ErrorStyle   = NewStyle().Bold().Foreground(ColourRed500)
	WarningStyle = NewStyle().Bold().Foreground(ColourAmber500)
	InfoStyle    = NewStyle().Foreground(ColourBlue400)
	DimStyle     = NewStyle().Dim().Foreground(ColourGray500)
	MutedStyle   = NewStyle().Foreground(ColourGray600)
	BoldStyle    = NewStyle().Bold()
	KeyStyle     = NewStyle().Foreground(ColourGray400)
	ValueStyle   = NewStyle().Foreground(ColourGray200)
	AccentStyle  = NewStyle().Foreground(ColourCyan500)
	LinkStyle    = NewStyle().Foreground(ColourBlue500).Underline()
	HeaderStyle  = NewStyle().Bold().Foreground(ColourGray200)
	TitleStyle   = NewStyle().Bold().Foreground(ColourBlue500)
	CodeStyle    = NewStyle().Foreground(ColourGray300)
	NumberStyle  = NewStyle().Foreground(ColourBlue300)
	RepoStyle    = NewStyle().Bold().Foreground(ColourBlue500)
)

Core styles

View Source 
var AppVersion = "dev"

AppVersion is set at build time via ldflags: 

go build -ldflags="-X github.com/host-uk/core/pkg/cli.AppVersion=v1.0.0"

Functions

func ArbitraryArgs 

func ArbitraryArgs() cobra.PositionalArgs

ArbitraryArgs returns a PositionalArgs that accepts any arguments.

func As 

func As(err error, target any) bool

As finds the first error in err's tree that matches target. This is a re-export of errors.As for convenience.

func Blank added in v0.0.3 

func Blank()

Blank prints an empty line.

func BoolFlag 

func BoolFlag(cmd *Command, ptr *bool, name, short string, def bool, usage string)

BoolFlag adds a boolean flag to a command. The value will be stored in the provided pointer. 

var verbose bool
cli.BoolFlag(cmd, &verbose, "verbose", "v", false, "Enable verbose output")

func Choose 

func Choose[T any](prompt string, items []T, opts ...ChooseOption[T]) T

Choose prompts the user to select from a list of items. Returns the selected item. Uses simple numbered selection for terminal compatibility. 

choice := Choose("Select a file:", files)
choice := Choose("Select a file:", files, WithDisplay(func(f File) string { return f.Name }))

func ChooseAction 

func ChooseAction[T any](verb, subject string, items []T, opts ...ChooseOption[T]) T

ChooseAction prompts for selection using grammar composition. 

file := ChooseAction("select", "file", files)

func ChooseMulti 

func ChooseMulti[T any](prompt string, items []T, opts ...ChooseOption[T]) []T

ChooseMulti prompts the user to select multiple items from a list. Returns the selected items. Uses space-separated numbers or ranges. 

choices := ChooseMulti("Select files:", files)
choices := ChooseMulti("Select files:", files, WithDisplay(func(f File) string { return f.Name }))

Input format:

  • "1 3 5" - select items 1, 3, and 5
  • "1-3" - select items 1, 2, and 3
  • "1 3-5" - select items 1, 3, 4, and 5
  • "" (empty) - select none

func ChooseMultiAction 

func ChooseMultiAction[T any](verb, subject string, items []T, opts ...ChooseOption[T]) []T

ChooseMultiAction prompts for multiple selections using grammar composition. 

files := ChooseMultiAction("select", "files", files)

func ColorEnabled added in v0.0.4 

func ColorEnabled() bool

ColorEnabled returns true if ANSI color output is enabled.

func Confirm 

func Confirm(prompt string, opts ...ConfirmOption) bool

Confirm prompts the user for yes/no confirmation. Returns true if the user enters "y" or "yes" (case-insensitive).

Basic usage: 

if Confirm("Delete file?") { ... }

With options: 

if Confirm("Save changes?", DefaultYes()) { ... }
if Confirm("Dangerous!", Required()) { ... }
if Confirm("Auto-continue?", Timeout(30*time.Second)) { ... }

func ConfirmAction 

func ConfirmAction(verb, subject string, opts ...ConfirmOption) bool

ConfirmAction prompts for confirmation of an action using grammar composition. 

if ConfirmAction("delete", "config.yaml") { ... }
if ConfirmAction("save", "changes", DefaultYes()) { ... }

func ConfirmDangerousAction 

func ConfirmDangerousAction(verb, subject string) bool

ConfirmDangerousAction prompts for double confirmation of a dangerous action. Shows initial question, then a "Really verb subject?" confirmation. 

if ConfirmDangerousAction("delete", "config.yaml") { ... }

func Context 

func Context() context.Context

Context returns the CLI's root context. Cancelled on SIGINT/SIGTERM.

func Core 

func Core() *framework.Core

Core returns the CLI's framework Core instance.

func Dim 

func Dim(msg string)

Dim prints dimmed text.

func DimStr 

func DimStr(msg string) string

DimStr returns dim-styled string.

func Echo added in v0.0.3 

func Echo(key string, args ...any)

Echo translates a key via i18n.T and prints with newline. No automatic styling - use Success/Error/Warn/Info for styled output.

func Err 

func Err(format string, args ...any) error

Err creates a new error from a format string. This is a direct replacement for fmt.Errorf.

func Error 

func Error(msg string)

Error prints an error message with cross (red).

func ErrorStr 

func ErrorStr(msg string) string

ErrorStr returns error-styled string.

func Errorf added in v0.0.3 

func Errorf(format string, args ...any)

Errorf prints a formatted error message.

func ExactArgs 

func ExactArgs(n int) cobra.PositionalArgs

ExactArgs returns a PositionalArgs that accepts exactly N arguments.

func Execute 

func Execute() error

Execute runs the CLI root command. Returns an error if the command fails.

func Fatal 

func Fatal(err error)

Fatal prints an error message and exits with code 1.

func FatalWrap 

func FatalWrap(err error, msg string)

FatalWrap prints a wrapped error message and exits with code 1. Does nothing if err is nil. 

cli.FatalWrap(err, "load config")  // Prints "✗ load config: <error>" and exits

func FatalWrapVerb 

func FatalWrapVerb(err error, verb, subject string)

FatalWrapVerb prints a wrapped error using i18n grammar and exits with code 1. Does nothing if err is nil. 

cli.FatalWrapVerb(err, "load", "config")  // Prints "✗ Failed to load config: <error>" and exits

func Fatalf 

func Fatalf(format string, args ...any)

Fatalf prints a formatted error message and exits with code 1.

func FormatAge 

func FormatAge(t time.Time) string

FormatAge formats a time as human-readable age (e.g., "2h ago", "3d ago").

func GhAuthenticated 

func GhAuthenticated() bool

GhAuthenticated checks if the GitHub CLI is authenticated. Returns true if 'gh auth status' indicates a logged-in user.

func GitClone 

func GitClone(ctx context.Context, org, repo, path string) error

GitClone clones a GitHub repository to the specified path. Prefers 'gh repo clone' if authenticated, falls back to SSH.

func Glyph added in v0.0.3 

func Glyph(code string) string

Glyph converts a shortcode (e.g. ":check:") to its symbol based on the current theme.

func Hint added in v0.0.3 

func Hint(label, message string)

Hint prints a labelled hint: "label: message" 

cli.Hint("install", "composer require vimeo/psalm")
cli.Hint("fix", "core php fmt --fix")

func Info 

func Info(msg string)

Info prints an info message with info symbol (blue).

func InfoStr 

func InfoStr(msg string) string

InfoStr returns info-styled string.

func Infof added in v0.0.3 

func Infof(format string, args ...any)

Infof prints a formatted info message.

func Init 

func Init(opts Options) error

Init initialises the global CLI runtime. Call this once at startup (typically in main.go or cmd.Execute).

func IntFlag 

func IntFlag(cmd *Command, ptr *int, name, short string, def int, usage string)

IntFlag adds an integer flag to a command. The value will be stored in the provided pointer. 

var count int
cli.IntFlag(cmd, &count, "count", "n", 10, "Number of items")

func Is 

func Is(err, target error) bool

Is reports whether any error in err's tree matches target. This is a re-export of errors.Is for convenience.

func IsStderrTTY 

func IsStderrTTY() bool

IsStderrTTY returns true if stderr is a terminal.

func IsStdinTTY 

func IsStdinTTY() bool

IsStdinTTY returns true if stdin is a terminal.

func IsTTY 

func IsTTY() bool

IsTTY returns true if stdout is a terminal.

func Join 

func Join(errs ...error) error

Join returns an error that wraps the given errors. This is a re-export of errors.Join for convenience.

func Label 

func Label(word, value string)

Label prints a "Label: value" line.

func LogDebug 

func LogDebug(msg string)

LogDebug logs a debug message if log service is available.

func LogError 

func LogError(msg string)

LogError logs an error message if log service is available.

func LogInfo 

func LogInfo(msg string)

LogInfo logs an info message if log service is available.

func LogWarn 

func LogWarn(msg string)

LogWarn logs a warning message if log service is available.

func Main 

func Main()

Main initialises and runs the CLI application. This is the main entry point for the CLI. Exits with code 1 on error.

func MaximumNArgs 

func MaximumNArgs(n int) cobra.PositionalArgs

MaximumNArgs returns a PositionalArgs that accepts maximum N arguments.

func MinimumNArgs 

func MinimumNArgs(n int) cobra.PositionalArgs

MinimumNArgs returns a PositionalArgs that accepts minimum N arguments.

func MultiSelect added in v0.0.3 

func MultiSelect(label string, options []string) ([]string, error)

MultiSelect presents checkboxes (space-separated numbers).

func NewI18nService 

func NewI18nService(opts I18nOptions) func(*framework.Core) (any, error)

NewI18nService creates an i18n service factory.

func NewLogService 

func NewLogService(opts LogOptions) func(*framework.Core) (any, error)

NewLogService creates a log service factory with CLI styling.

func NoArgs 

func NoArgs() cobra.PositionalArgs

NoArgs returns a PositionalArgs that accepts no arguments.

func Pad added in v0.0.3 

func Pad(s string, width int) string

Pad right-pads a string to width.

func PersistentBoolFlag 

func PersistentBoolFlag(cmd *Command, ptr *bool, name, short string, def bool, usage string)

PersistentBoolFlag adds a persistent boolean flag (inherited by subcommands).

func PersistentStringFlag 

func PersistentStringFlag(cmd *Command, ptr *string, name, short, def, usage string)

PersistentStringFlag adds a persistent string flag (inherited by subcommands).

func Print added in v0.0.3 

func Print(format string, args ...any)

Print outputs formatted text (no newline). Glyph shortcodes like :check: are converted.

func Println added in v0.0.3 

func Println(format string, args ...any)

Println outputs formatted text with newline. Glyph shortcodes like :check: are converted.

func Progress added in v0.0.3 

func Progress(verb string, current, total int, item ...string)

Progress prints a progress indicator that overwrites the current line. Uses i18n.Progress for gerund form ("Checking...").

func ProgressDone added in v0.0.3 

func ProgressDone()

ProgressDone clears the progress line.

func Prompt added in v0.0.3 

func Prompt(label, defaultVal string) (string, error)

Prompt asks for text input with a default value.

func Question 

func Question(prompt string, opts ...QuestionOption) string

Question prompts the user for text input. 

name := Question("Enter your name:")
name := Question("Enter your name:", WithDefault("Anonymous"))
name := Question("Enter your name:", RequiredInput())

func QuestionAction 

func QuestionAction(verb, subject string, opts ...QuestionOption) string

QuestionAction prompts for text input using grammar composition. 

name := QuestionAction("rename", "old.txt")

func RegisterCommands 

func RegisterCommands(fn CommandRegistration)

RegisterCommands registers a function that adds commands to the CLI. Call this in your package's init() to register commands. 

func init() {
    cli.RegisterCommands(AddCommands)
}

func AddCommands(root *cobra.Command) {
    root.AddCommand(myCmd)
}

func Result added in v0.0.3 

func Result(passed bool, message string)

Result prints a result line: "✓ message" or "✗ message" 

cli.Result(passed, "All tests passed")
cli.Result(false, "3 tests failed")

func RootCmd 

func RootCmd() *cobra.Command

RootCmd returns the CLI's root cobra command.

func Run 

func Run(ctx context.Context) error

Run blocks until context is cancelled or signal received. Simple helper for daemon mode without advanced features. 

cli.Init(cli.Options{AppName: "myapp"})
defer cli.Shutdown()
cli.Run(cli.Context())

func RunWithTimeout 

func RunWithTimeout(timeout time.Duration) func()

RunWithTimeout wraps Run with a graceful shutdown timeout. The returned function should be deferred to replace cli.Shutdown(). 

cli.Init(cli.Options{AppName: "myapp"})
shutdown := cli.RunWithTimeout(30 * time.Second)
defer shutdown()
cli.Run(cli.Context())

func Scanln 

func Scanln(a ...any) (int, error)

Scanln reads from stdin.

func Section added in v0.0.3 

func Section(name string)

Section prints a section header: "── SECTION ──" 

cli.Section("audit")  // ── AUDIT ──

func Select added in v0.0.3 

func Select(label string, options []string) (string, error)

Select presents numbered options and returns the selected value.

func SetColorEnabled added in v0.0.4 

func SetColorEnabled(enabled bool)

SetColorEnabled enables or disables ANSI color output. This overrides the NO_COLOR environment variable check.

func Severity added in v0.0.3 

func Severity(level, message string)

Severity prints a severity-styled message. 

cli.Severity("critical", "SQL injection")  // red, bold
cli.Severity("high", "XSS vulnerability")  // orange
cli.Severity("medium", "Missing CSRF")     // amber
cli.Severity("low", "Debug enabled")       // gray

func Shutdown 

func Shutdown()

Shutdown gracefully shuts down the CLI.

func Sprint 

func Sprint(args ...any) string

Sprint formats using default formats (fmt.Sprint wrapper).

func Sprintf 

func Sprintf(format string, args ...any) string

Sprintf formats a string (fmt.Sprintf wrapper).

func StringFlag 

func StringFlag(cmd *Command, ptr *string, name, short, def, usage string)

StringFlag adds a string flag to a command. The value will be stored in the provided pointer. 

var output string
cli.StringFlag(cmd, &output, "output", "o", "", "Output file path")

func StringSliceFlag 

func StringSliceFlag(cmd *Command, ptr *[]string, name, short string, def []string, usage string)

StringSliceFlag adds a string slice flag to a command. The value will be stored in the provided pointer. 

var tags []string
cli.StringSliceFlag(cmd, &tags, "tag", "t", nil, "Tags to apply")

func Styled 

func Styled(style *AnsiStyle, text string) string

Styled returns text with a style applied.

func Styledf 

func Styledf(style *AnsiStyle, format string, args ...any) string

Styledf returns formatted text with a style applied.

func Success 

func Success(msg string)

Success prints a success message with checkmark (green).

func SuccessStr 

func SuccessStr(msg string) string

SuccessStr returns success-styled string.

func Successf added in v0.0.3 

func Successf(format string, args ...any)

Successf prints a formatted success message.

func T 

func T(key string, args ...map[string]any) string

T translates a key using the CLI's i18n service. Falls back to the global i18n.T if CLI not initialised.

func Task added in v0.0.3 

func Task(label, message string)

Task prints a task header: "[label] message" 

cli.Task("php", "Running tests...")  // [php] Running tests...
cli.Task("go", i18n.Progress("build"))  // [go] Building...

func Text added in v0.0.3 

func Text(args ...any)

Text prints arguments like fmt.Println, but handling glyphs.

func Truncate 

func Truncate(s string, max int) string

Truncate shortens a string to max length with ellipsis.

func UseASCII added in v0.0.3 

func UseASCII()

UseASCII switches the glyph theme to ASCII and disables colors.

func UseEmoji added in v0.0.3 

func UseEmoji()

UseEmoji switches the glyph theme to Emoji.

func UseRenderBoxed added in v0.0.3 

func UseRenderBoxed()

UseRenderBoxed sets the render style to boxed (Unicode box drawing).

func UseRenderFlat added in v0.0.3 

func UseRenderFlat()

UseRenderFlat sets the render style to flat (no borders).

func UseRenderSimple added in v0.0.3 

func UseRenderSimple()

UseRenderSimple sets the render style to simple (--- separators).

func UseUnicode added in v0.0.3 

func UseUnicode()

UseUnicode switches the glyph theme to Unicode.

func Warn added in v0.0.3 

func Warn(msg string)

Warn prints a warning message with warning symbol (amber).

func WarnStr added in v0.0.3 

func WarnStr(msg string) string

WarnStr returns warning-styled string.

func Warnf added in v0.0.3 

func Warnf(format string, args ...any)

Warnf prints a formatted warning message.

func Wrap 

func Wrap(err error, msg string) error

Wrap wraps an error with a message. Returns nil if err is nil. 

return cli.Wrap(err, "load config")  // "load config: <original error>"

func WrapAction 

func WrapAction(err error, verb string) error

WrapAction wraps an error using i18n grammar for "Failed to verb". Uses the i18n.ActionFailed function for proper grammar composition. Returns nil if err is nil. 

return cli.WrapAction(err, "connect")  // "Failed to connect: <original error>"

func WrapVerb 

func WrapVerb(err error, verb, subject string) error

WrapVerb wraps an error using i18n grammar for "Failed to verb subject". Uses the i18n.ActionFailed function for proper grammar composition. Returns nil if err is nil. 

return cli.WrapVerb(err, "load", "config")  // "Failed to load config: <original error>"

Types

type AnsiStyle added in v0.0.3 

type AnsiStyle struct {
	// contains filtered or unexported fields
}

AnsiStyle represents terminal text styling. Use NewStyle() to create, chain methods, call Render().

func NewStyle added in v0.0.3 

func NewStyle() *AnsiStyle

NewStyle creates a new empty style.

func (*AnsiStyle) Background added in v0.0.3 

func (s *AnsiStyle) Background(hex string) *AnsiStyle

Background sets background color from hex string.

func (*AnsiStyle) Bold added in v0.0.3 

func (s *AnsiStyle) Bold() *AnsiStyle

Bold enables bold text.

func (*AnsiStyle) Dim added in v0.0.3 

func (s *AnsiStyle) Dim() *AnsiStyle

Dim enables dim text.

func (*AnsiStyle) Foreground added in v0.0.3 

func (s *AnsiStyle) Foreground(hex string) *AnsiStyle

Foreground sets foreground color from hex string.

func (*AnsiStyle) Italic added in v0.0.3 

func (s *AnsiStyle) Italic() *AnsiStyle

Italic enables italic text.

func (*AnsiStyle) Render added in v0.0.3 

func (s *AnsiStyle) Render(text string) string

Render applies the style to text. Returns plain text if NO_COLOR is set or colors are disabled.

func (*AnsiStyle) Underline added in v0.0.3 

func (s *AnsiStyle) Underline() *AnsiStyle

Underline enables underlined text.

type CheckBuilder added in v0.0.3 

type CheckBuilder struct {
	// contains filtered or unexported fields
}

CheckBuilder provides fluent API for check results.

func Check added in v0.0.3 

func Check(name string) *CheckBuilder

Check starts building a check result line. 

cli.Check("audit").Pass()
cli.Check("fmt").Fail().Duration("2.3s")
cli.Check("test").Skip()

func (*CheckBuilder) Duration added in v0.0.3 

func (c *CheckBuilder) Duration(d string) *CheckBuilder

Duration adds duration to the check result.

func (*CheckBuilder) Fail added in v0.0.3 

func (c *CheckBuilder) Fail() *CheckBuilder

Fail marks the check as failed.

func (*CheckBuilder) Message added in v0.0.3 

func (c *CheckBuilder) Message(msg string) *CheckBuilder

Message adds a custom message instead of status.

func (*CheckBuilder) Pass added in v0.0.3 

func (c *CheckBuilder) Pass() *CheckBuilder

Pass marks the check as passed.

func (*CheckBuilder) Print added in v0.0.3 

func (c *CheckBuilder) Print()

Print outputs the check result.

func (*CheckBuilder) Skip added in v0.0.3 

func (c *CheckBuilder) Skip() *CheckBuilder

Skip marks the check as skipped.

func (*CheckBuilder) String added in v0.0.3 

func (c *CheckBuilder) String() string

String returns the formatted check line.

func (*CheckBuilder) Warn added in v0.0.3 

func (c *CheckBuilder) Warn() *CheckBuilder

Warn marks the check as warning.

type ChooseOption 

type ChooseOption[T any] func(*chooseConfig[T])

ChooseOption configures Choose behaviour.

func Display 

func Display[T any](fn func(T) string) ChooseOption[T]

Display sets a custom display function for items. Alias for WithDisplay for shorter syntax. 

Choose("Select:", items, Display(func(f File) string { return f.Name }))

func Filter 

func Filter[T any]() ChooseOption[T]

Filter enables type-to-filter functionality. Users can type to narrow down the list of options. Note: This is a hint for interactive UIs; the basic CLI Choose implementation uses numbered selection which doesn't support filtering.

func Multi 

func Multi[T any]() ChooseOption[T]

Multi allows multiple selections. Use ChooseMulti instead of Choose when this option is needed.

func WithDefaultIndex 

func WithDefaultIndex[T any](idx int) ChooseOption[T]

WithDefaultIndex sets the default selection index (0-based).

func WithDisplay 

func WithDisplay[T any](fn func(T) string) ChooseOption[T]

WithDisplay sets a custom display function for items.

type Command 

type Command = cobra.Command

Command is the cobra command type. Re-exported for convenience so packages don't need to import cobra directly.

func NewCommand 

func NewCommand(use, short, long string, run func(cmd *Command, args []string) error) *Command

NewCommand creates a new command with a RunE handler. This is the standard way to create commands that may return errors. 

cmd := cli.NewCommand("build", "Build the project", "", func(cmd *cli.Command, args []string) error {
    // Build logic
    return nil
})

func NewGroup 

func NewGroup(use, short, long string) *Command

NewGroup creates a new command group (no RunE). Use this for parent commands that only contain subcommands. 

devCmd := cli.NewGroup("dev", "Development commands", "")
devCmd.AddCommand(buildCmd, testCmd)

func NewRun 

func NewRun(use, short, long string, run func(cmd *Command, args []string)) *Command

NewRun creates a new command with a simple Run handler (no error return). Use when the command cannot fail. 

cmd := cli.NewRun("version", "Show version", "", func(cmd *cli.Command, args []string) {
    cli.Println("v1.0.0")
})

func WithArgs 

func WithArgs(cmd *Command, args cobra.PositionalArgs) *Command

WithArgs sets the Args validation function for a command. Returns the command for chaining. 

cmd := cli.NewCommand("build", "Build", "", run).WithArgs(cobra.ExactArgs(1))

func WithExample 

func WithExample(cmd *Command, example string) *Command

WithExample sets the Example field for a command. Returns the command for chaining.

type CommandRegistration 

type CommandRegistration func(root *cobra.Command)

CommandRegistration is a function that adds commands to the root.

type Composite added in v0.0.3 

type Composite struct {
	// contains filtered or unexported fields
}

Composite represents an HLCRF layout node.

func Layout added in v0.0.3 

func Layout(variant string) *Composite

Layout creates a new layout from a variant string.

func ParseVariant added in v0.0.3 

func ParseVariant(variant string) (*Composite, error)

ParseVariant parses a variant string like "H[LC]C[HCF]F".

func (*Composite) C added in v0.0.3 

func (c *Composite) C(items ...any) *Composite

C adds content to Content region.

func (*Composite) F added in v0.0.3 

func (c *Composite) F(items ...any) *Composite

F adds content to Footer region.

func (*Composite) H added in v0.0.3 

func (c *Composite) H(items ...any) *Composite

H adds content to Header region.

func (*Composite) L added in v0.0.3 

func (c *Composite) L(items ...any) *Composite

L adds content to Left region.

func (*Composite) R added in v0.0.3 

func (c *Composite) R(items ...any) *Composite

R adds content to Right region.

func (*Composite) Render added in v0.0.3 

func (c *Composite) Render()

Render outputs the layout to terminal.

func (*Composite) String added in v0.0.3 

func (c *Composite) String() string

String returns the rendered layout.

type ConfirmOption 

type ConfirmOption func(*confirmConfig)

ConfirmOption configures Confirm behaviour.

func DefaultYes 

func DefaultYes() ConfirmOption

DefaultYes sets the default response to "yes" (pressing Enter confirms).

func Required 

func Required() ConfirmOption

Required prevents empty responses; user must explicitly type y/n.

func Timeout 

func Timeout(d time.Duration) ConfirmOption

Timeout sets a timeout after which the default response is auto-selected. If no default is set (not Required and not DefaultYes), defaults to "no". 

Confirm("Continue?", Timeout(30*time.Second))  // Auto-no after 30s
Confirm("Continue?", DefaultYes(), Timeout(10*time.Second))  // Auto-yes after 10s

type Daemon 

type Daemon struct {
	// contains filtered or unexported fields
}

Daemon manages daemon lifecycle.

func NewDaemon 

func NewDaemon(opts DaemonOptions) *Daemon

NewDaemon creates a daemon runner with the given options.

func (*Daemon) HealthAddr 

func (d *Daemon) HealthAddr() string

HealthAddr returns the health server address, or empty if disabled.

func (*Daemon) Run 

func (d *Daemon) Run(ctx context.Context) error

Run blocks until the context is cancelled or a signal is received. Handles graceful shutdown with the configured timeout.

func (*Daemon) SetReady 

func (d *Daemon) SetReady(ready bool)

SetReady sets the daemon readiness status for health checks.

func (*Daemon) Start 

func (d *Daemon) Start() error

Start initialises the daemon (PID file, health server). Call this after cli.Init().

func (*Daemon) Stop 

func (d *Daemon) Stop() error

Stop performs graceful shutdown.

type DaemonOptions 

type DaemonOptions struct {
	// PIDFile path for single-instance enforcement.
	// Leave empty to skip PID file management.
	PIDFile string

	// ShutdownTimeout is the maximum time to wait for graceful shutdown.
	// Default: 30 seconds.
	ShutdownTimeout time.Duration

	// HealthAddr is the address for health check endpoints.
	// Example: ":8080", "127.0.0.1:9000"
	// Leave empty to disable health checks.
	HealthAddr string

	// HealthChecks are additional health check functions.
	HealthChecks []HealthCheck

	// OnReload is called when SIGHUP is received.
	// Use for config reloading. Leave nil to ignore SIGHUP.
	OnReload func() error
}

DaemonOptions configures daemon mode execution.

type GlyphTheme added in v0.0.3 

type GlyphTheme int

GlyphTheme defines which symbols to use. 

const (
	// ThemeUnicode uses standard Unicode symbols.
	ThemeUnicode GlyphTheme = iota
	// ThemeEmoji uses Emoji symbols.
	ThemeEmoji
	// ThemeASCII uses ASCII fallback symbols.
	ThemeASCII
)

type HealthCheck 

type HealthCheck func() error

HealthCheck is a function that returns nil if healthy.

type HealthServer 

type HealthServer struct {
	// contains filtered or unexported fields
}

HealthServer provides a minimal HTTP health check endpoint.

func NewHealthServer 

func NewHealthServer(addr string) *HealthServer

NewHealthServer creates a health check server.

func (*HealthServer) AddCheck 

func (h *HealthServer) AddCheck(check HealthCheck)

AddCheck registers a health check function.

func (*HealthServer) Addr 

func (h *HealthServer) Addr() string

Addr returns the actual address the server is listening on. Useful when using port 0 for dynamic port assignment.

func (*HealthServer) SetReady 

func (h *HealthServer) SetReady(ready bool)

SetReady sets the readiness status.

func (*HealthServer) Start 

func (h *HealthServer) Start() error

Start begins serving health check endpoints. Endpoints:

  • /health - liveness probe (always 200 if server is up)
  • /ready - readiness probe (200 if ready, 503 if not)

func (*HealthServer) Stop 

func (h *HealthServer) Stop(ctx context.Context) error

Stop gracefully shuts down the health server.

type I18nOptions 

type I18nOptions struct {
	// Language overrides auto-detection (e.g., "en-GB", "de")
	Language string
	// Mode sets the translation mode (Normal, Strict, Collect)
	Mode i18n.Mode
}

I18nOptions configures the i18n service.

type I18nService 

type I18nService struct {
	*framework.ServiceRuntime[I18nOptions]
	// contains filtered or unexported fields
}

I18nService wraps i18n as a Core service.

func (*I18nService) AvailableLanguages 

func (s *I18nService) AvailableLanguages() []string

AvailableLanguages returns all available languages.

func (*I18nService) ClearMissingKeys 

func (s *I18nService) ClearMissingKeys()

ClearMissingKeys resets the collected missing keys.

func (*I18nService) Language 

func (s *I18nService) Language() string

Language returns the current language.

func (*I18nService) MissingKeys 

func (s *I18nService) MissingKeys() []i18n.MissingKey

MissingKeys returns all missing keys collected in collect mode. Call this at the end of a QA session to report missing translations.

func (*I18nService) Mode 

func (s *I18nService) Mode() i18n.Mode

Mode returns the current translation mode.

func (*I18nService) OnStartup 

func (s *I18nService) OnStartup(ctx context.Context) error

OnStartup initialises the i18n service.

func (*I18nService) SetLanguage 

func (s *I18nService) SetLanguage(lang string)

SetLanguage changes the current language.

func (*I18nService) SetMode 

func (s *I18nService) SetMode(mode i18n.Mode)

SetMode changes the translation mode.

func (*I18nService) T 

func (s *I18nService) T(key string, args ...map[string]any) string

T translates a key with optional arguments.

type LogLevel 

type LogLevel = log.Level

LogLevel aliases for backwards compatibility.

type LogOptions 

type LogOptions = log.Options

LogOptions configures the log service.

type LogService 

type LogService struct {
	*log.Service
}

LogService wraps log.Service with CLI styling.

func Log 

func Log() *LogService

Log returns the CLI's log service, or nil if not available.

type Mode 

type Mode int

Mode represents the CLI execution mode. 

const (
	// ModeInteractive indicates TTY attached with coloured output.
	ModeInteractive Mode = iota
	// ModePipe indicates stdout is piped, colours disabled.
	ModePipe
	// ModeDaemon indicates headless execution, log-only output.
	ModeDaemon
)

func DetectMode 

func DetectMode() Mode

DetectMode determines the execution mode based on environment. Checks CORE_DAEMON env var first, then TTY status.

func (Mode) String 

func (m Mode) String() string

String returns the string representation of the Mode.

type Options 

type Options struct {
	AppName  string
	Version  string
	Services []framework.Option // Additional services to register

	// OnReload is called when SIGHUP is received (daemon mode).
	// Use for configuration reloading. Leave nil to ignore SIGHUP.
	OnReload func() error
}

Options configures the CLI runtime.

type PIDFile 

type PIDFile struct {
	// contains filtered or unexported fields
}

PIDFile manages a process ID file for single-instance enforcement.

func NewPIDFile 

func NewPIDFile(path string) *PIDFile

NewPIDFile creates a PID file manager.

func (*PIDFile) Acquire 

func (p *PIDFile) Acquire() error

Acquire writes the current PID to the file. Returns error if another instance is running.

func (*PIDFile) Path 

func (p *PIDFile) Path() string

Path returns the PID file path.

func (*PIDFile) Release 

func (p *PIDFile) Release() error

Release removes the PID file.

type QueryTranslate 

type QueryTranslate struct {
	Key  string
	Args map[string]any
}

QueryTranslate requests a translation.

type QuestionOption 

type QuestionOption func(*questionConfig)

QuestionOption configures Question behaviour.

func RequiredInput 

func RequiredInput() QuestionOption

RequiredInput prevents empty responses.

func WithDefault 

func WithDefault(value string) QuestionOption

WithDefault sets the default value shown in brackets.

func WithValidator 

func WithValidator(fn func(string) error) QuestionOption

WithValidator adds a validation function for the response.

type Region added in v0.0.3 

type Region rune

Region represents one of the 5 HLCRF regions. 

const (
	// RegionHeader is the top region of the layout.
	RegionHeader Region = 'H'
	// RegionLeft is the left sidebar region.
	RegionLeft Region = 'L'
	// RegionContent is the main content region.
	RegionContent Region = 'C'
	// RegionRight is the right sidebar region.
	RegionRight Region = 'R'
	// RegionFooter is the bottom region of the layout.
	RegionFooter Region = 'F'
)

type RenderStyle added in v0.0.3 

type RenderStyle int

RenderStyle controls how layouts are rendered. 

const (
	// RenderFlat uses no borders or decorations.
	RenderFlat RenderStyle = iota
	// RenderSimple uses --- separators between sections.
	RenderSimple
	// RenderBoxed uses Unicode box drawing characters.
	RenderBoxed
)

Render style constants for layout output.

type Renderable added in v0.0.3 

type Renderable interface {
	Render() string
}

Renderable is anything that can be rendered to terminal.

type SignalOption 

type SignalOption func(*signalService)

SignalOption configures signal handling.

func WithReloadHandler 

func WithReloadHandler(fn func() error) SignalOption

WithReloadHandler sets a callback for SIGHUP.

type Slot added in v0.0.3 

type Slot struct {
	// contains filtered or unexported fields
}

Slot holds content for a region.

type StringBlock added in v0.0.3 

type StringBlock string

StringBlock is a simple string that implements Renderable.

func (StringBlock) Render added in v0.0.3 

func (s StringBlock) Render() string

Render returns the string content.

type Table 

type Table struct {
	Headers []string
	Rows    [][]string
	Style   TableStyle
}

Table renders tabular data with aligned columns. HLCRF is for layout; Table is for tabular data - they serve different purposes.

func NewTable added in v0.0.3 

func NewTable(headers ...string) *Table

NewTable creates a table with headers.

func (*Table) AddRow added in v0.0.3 

func (t *Table) AddRow(cells ...string) *Table

AddRow adds a row to the table.

func (*Table) Render 

func (t *Table) Render()

Render prints the table to stdout.

func (*Table) String added in v0.0.3 

func (t *Table) String() string

String renders the table.

type TableStyle added in v0.0.3 

type TableStyle struct {
	HeaderStyle *AnsiStyle
	CellStyle   *AnsiStyle
	Separator   string
}

TableStyle configures the appearance of table output.

func DefaultTableStyle added in v0.0.3 

func DefaultTableStyle() TableStyle

DefaultTableStyle returns sensible defaults.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.