console

package
v0.87.1 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 22 Imported by: 0

README

Console Package

Terminal UI formatting, rendering, and interactive console helpers for gh-aw.

Overview

The console package defines the terminal-facing presentation layer used by gh-aw. It formats diagnostic messages, compiler-style errors, banners, tables, sections, and reflected struct output, and it provides convenience print helpers that route human-readable output to stderr. The package distinguishes between Format* functions, which produce formatted strings, and Render* functions, which build structured output such as tables, boxes, or composed sections.

The package is designed to adapt to the execution environment. Native builds detect TTY availability, honor accessibility-oriented environment variables, and degrade ANSI output through the color-profile writer so output respects terminal capabilities and settings such as NO_COLOR. For interactive workflows it also provides spinners, progress bars, confirmation dialogs, secret prompts, and themed huh form constructors, while WASM builds expose simpler fallback implementations or explicit “not available” errors where interactivity is unsupported.

Public API

Types
Type Kind Description
CompilerError struct Structured diagnostic with source position, severity-like type string, message, optional source context, and optional hint text.
ErrorPosition struct Source location with file, line, and column fields.
FormField struct Declarative form field description used by WASM-only RunForm, including type, labels, bound value, options, and validation callback.
ListItem struct Interactive list item value created by NewListItem; its fields are intentionally unexported.
ProgressBar struct Progress-bar controller returned by NewProgressBar and NewIndeterminateProgressBar, with Update for rendering determinate or indeterminate progress.
SelectOption struct Label/value pair used by select-oriented APIs.
SpinnerWrapper struct Spinner controller with lifecycle methods Start, Stop, StopWithMessage, and UpdateMessage.
TableConfig struct Table-rendering configuration including headers, rows, optional title/total row, and optional TTY override.
TreeNode struct Tree node with a display value and child nodes; rendered by RenderTree in WASM builds.
Functions
Function Signature Description
ClearLine func ClearLine() Clears the current stderr terminal line when stderr is a TTY.
ClearScreen func ClearScreen() Clears the stderr terminal screen when stderr is a TTY.
ConfirmAction func ConfirmAction(title, affirmative, negative string) (bool, error) Presents a confirmation prompt; native builds use huh, non-TTY mode falls back to text input, and WASM reports unsupported behavior.
FormatBanner func FormatBanner() string Returns the embedded gh-aw ASCII banner, styled in native TTY mode and empty in WASM.
FormatCommandMessage func FormatCommandMessage(command string) string Formats a command-prefixed message ($ ...).
FormatCommandMessageStderr func FormatCommandMessageStderr(command string) string Formats a command-prefixed message for stderr styling.
FormatCountMessage func FormatCountMessage(message string) string Formats a count-style message (# ...) in WASM builds.
FormatError func FormatError(err CompilerError) string Formats a CompilerError including location, severity prefix, context lines, and hint text.
FormatErrorChain func FormatErrorChain(err error) string Formats an error and unwrap chain into a readable multi-line diagnostic.
FormatErrorMessage func FormatErrorMessage(message string) string Formats a simple error message with an error prefix.
FormatErrorStderr func FormatErrorStderr(err CompilerError) string Formats a CompilerError using stderr-aware styling rules.
FormatErrorTextStderr func FormatErrorTextStderr(text string) string Applies error styling to plain stderr text.
FormatErrorWithSuggestions func FormatErrorWithSuggestions(message string, suggestions []string) string Formats an error message followed by actionable suggestions.
FormatFileSize func FormatFileSize(size int64) string Formats byte counts into human-readable sizes.
FormatInfoMessage func FormatInfoMessage(message string) string Formats an informational message with an i prefix.
FormatInfoMessageStderr func FormatInfoMessageStderr(message string) string Formats an informational message for stderr styling.
FormatListHeader func FormatListHeader(header string) string Formats a list header in WASM builds.
FormatListItem func FormatListItem(item string) string Formats a bullet list item.
FormatListItemStderr func FormatListItemStderr(item string) string Formats a bullet list item for stderr styling.
FormatLocationMessage func FormatLocationMessage(message string) string Formats a location-style message (~ ...) in WASM builds.
FormatNumber func FormatNumber(n int) string Formats integers with grouping for display.
FormatProgressMessage func FormatProgressMessage(message string) string Formats a progress/activity message with a ▸ prefix.
FormatProgressMessageStderr func FormatProgressMessageStderr(message string) string Formats a progress/activity message for stderr styling.
FormatPromptMessage func FormatPromptMessage(message string) string Formats a prompt message with a ? prefix.
FormatSectionHeader func FormatSectionHeader(header string) string Formats a section header.
FormatSectionHeaderStderr func FormatSectionHeaderStderr(header string) string Formats a section header for stderr styling.
FormatSuccessMessage func FormatSuccessMessage(message string) string Formats a success message with a checkmark prefix.
FormatSuccessMessageStderr func FormatSuccessMessageStderr(message string) string Formats a success message for stderr styling.
FormatTableHeaderStderr func FormatTableHeaderStderr(text string) string Formats table-header text for stderr output.
FormatTokens func FormatTokens(tokens int) string Formats token counts into readable grouped text.
FormatVerboseMessage func FormatVerboseMessage(message string) string Formats verbose output with a » prefix.
FormatWarningMessage func FormatWarningMessage(message string) string Formats a warning message with a warning prefix.
FormatWarningMessageStderr func FormatWarningMessageStderr(message string) string Formats a warning message for stderr styling.
IsAccessibleMode func IsAccessibleMode() bool Returns whether accessibility mode should be enabled based on environment variables.
IsCancelled func IsCancelled(err error) bool Reports whether an error represents user cancellation from a huh form.
LayoutEmphasisBox func LayoutEmphasisBox(content string, color any) string Returns a simple emphasized block layout in WASM builds.
LayoutInfoSection func LayoutInfoSection(label, value string) string Returns a simple labeled info line in WASM builds.
LayoutJoinVertical func LayoutJoinVertical(sections ...string) string Joins multiple sections vertically in WASM builds.
LayoutTitleBox func LayoutTitleBox(title string, width int) string Returns a simple title-box layout in WASM builds.
LogVerbose func LogVerbose(verbose bool, message string) Prints a verbose message to stderr only when verbose mode is enabled.
NewConfirmForm func NewConfirmForm(confirm *huh.Confirm) *huh.Form Wraps a confirm field in a themed, accessibility-aware huh form.
NewForm func NewForm(groups ...*huh.Group) *huh.Form Creates a themed, accessibility-aware huh form.
NewIndeterminateProgressBar func NewIndeterminateProgressBar() *ProgressBar Creates an indeterminate progress bar; available in WASM builds.
NewInputForm func NewInputForm(input *huh.Input) *huh.Form Wraps an input field in a themed, accessibility-aware huh form.
NewListItem func NewListItem(title, description, value string) ListItem Constructs a ListItem for interactive list APIs.
NewProgressBar func NewProgressBar(total int64) *ProgressBar Creates a progress bar for a known total amount of work.
NewSelectForm func NewSelectForm[T comparable](selectField *huh.Select[T]) *huh.Form Wraps a select field in a themed, accessibility-aware huh form.
NewSpinner func NewSpinner(message string) *SpinnerWrapper Creates a spinner configured for stderr TTY and accessibility conditions.
PrintBanner func PrintBanner() Prints the banner to stderr in native builds; no-op in WASM.
PrintCommandMessage func PrintCommandMessage(command string) Prints a formatted command message to stderr.
PrintErrorMessage func PrintErrorMessage(message string) Prints a formatted error message to stderr.
PrintInfoMessage func PrintInfoMessage(message string) Prints a formatted info message to stderr.
PrintSectionHeader func PrintSectionHeader(header string) Prints a formatted section header to stderr.
PrintSuccessMessage func PrintSuccessMessage(message string) Prints a formatted success message to stderr.
PrintWarningMessage func PrintWarningMessage(message string) Prints a formatted warning message to stderr.
PromptInput func PromptInput(title, description, placeholder string) (string, error) Requests plain-text input in WASM builds, where it currently reports unsupported interactivity.
PromptInputWithValidation func PromptInputWithValidation(title, description, placeholder string, validate func(string) error) (string, error) Requests validated plain-text input in WASM builds, where it currently reports unsupported interactivity.
PromptMultiSelect func PromptMultiSelect(title, description string, options []SelectOption, limit int) ([]string, error) Requests multiple selections in WASM builds, where it currently reports unsupported interactivity.
PromptSecretInput func PromptSecretInput(title, description string) (string, error) Requests masked secret input in native TTY mode; unavailable in non-TTY and WASM environments.
PromptSelect func PromptSelect(title, description string, options []SelectOption) (string, error) Requests a single selection in WASM builds, where it currently reports unsupported interactivity.
RenderComposedSections func RenderComposedSections(sections []string) Writes multiple rendered sections to stderr with spacing and terminal-aware composition.
RenderErrorBox func RenderErrorBox(title string) []string Renders an error-emphasis box, with TTY and plain-text variants.
RenderInfoSection func RenderInfoSection(content string) []string Renders an informational section with left-border emphasis or plain indentation.
RenderStruct func RenderStruct(v any) string Reflectively renders structs, slices, arrays, and maps into structured console output.
RenderTable func RenderTable(config TableConfig) string Renders a table from TableConfig, optionally including a title and total row.
RenderTitleBox func RenderTitleBox(title string, width int) []string Renders a titled box suitable for section headings.
RenderTree func RenderTree(root TreeNode) string Renders a TreeNode hierarchy in WASM builds.
ResetTimeLocation func ResetTimeLocation() Clears the configured time.Time display location override.
RunForm func RunForm(fields []FormField) error Executes declarative forms in WASM builds, where it currently reports unsupported interactivity.
SetTimeLocation func SetTimeLocation(location *time.Location) Sets the location used when rendering time.Time values.
ShowInteractiveList func ShowInteractiveList(title string, items []ListItem) (string, error) Shows a single-selection interactive list; native builds use huh and non-TTY mode falls back to numbered text input.
ShowWelcomeBanner func ShowWelcomeBanner(description string) Clears the screen and prints the interactive welcome banner and description to stderr.
ToRelativePath func ToRelativePath(path string) string Converts an absolute path to a cwd-relative display path when possible.
Constants
Constant Type Value Description
(none) — — pkg/console exposes no exported constants in current source.

Usage Examples

Formatting and printing diagnostic output
fmt.Fprintln(os.Stderr, console.FormatErrorChain(err))
console.PrintSuccessMessage("Workflow compiled")
console.PrintCommandMessage("gh aw compile .github/workflows/example.md")

The formatting functions return strings, while the Print* helpers write directly to stderr.

Rendering reflected structs and tables
type Overview struct {
    Name   string `console:"header:Workflow"`
    Tokens int    `console:"header:Token Count"`
}

output := console.RenderStruct([]Overview{{
    Name:   "agentic-token-audit",
    Tokens: 1200,
}})
fmt.Print(output)

RenderStruct uses reflection and console struct tags such as header, title, omitempty, and - to choose headings, omit zero values, and build tables for slices of structs.

Spinner lifecycle
spinner := console.NewSpinner("Compiling workflow...")
spinner.Start()
// long-running work
spinner.StopWithMessage("✓ Workflow compiled")

Native spinners render on stderr only when stderr is a TTY and accessibility mode is not enabled.

Progress bars
bar := console.NewProgressBar(totalBytes)
fmt.Fprintf(os.Stderr, "\r%s", bar.Update(currentBytes))

On native TTYs, Update returns a rendered progress bar. In non-TTY mode, it returns plain text such as 50% (512MB/1GB).

Design Decisions

The package preserves a strong separation between formatting and rendering. Format* helpers are string-producing utilities for single messages, while Render* helpers handle multi-line layout and composition. This convention is documented in doc.go and is reflected throughout the exported API.

The native implementation is terminal-aware. Styling is applied only when appropriate for the destination stream, and stdout-oriented rendering is degraded through the color-profile writer so environment variables such as NO_COLOR, COLORTERM, and TERM are respected. Diagnostic output is intended for stderr, while structured machine-readable output is expected to remain on stdout.

Interactive helpers deliberately degrade or refuse operation outside native TTY contexts. ConfirmAction and ShowInteractiveList provide plain-text fallbacks for non-TTY native runs, while secret input remains unavailable without a TTY. WASM-specific files provide explicit fallback implementations so exported APIs remain available across build targets even when rich interactivity is unsupported.

Spinner coordination is intentionally global in native builds: only one spinner may actively render at a time. Additional concurrent spinners become suppressed instead of competing for the same stderr line, avoiding flicker and escape-sequence corruption.

Dependencies

Internal dependencies include pkg/styles for shared visual styling, pkg/tty for terminal detection, pkg/colorwriter for stream-aware ANSI degradation, pkg/logger for debug logging, and pkg/stringutil for text formatting support during reflective rendering.

External dependencies include Charmbracelet libraries: lipgloss and lipgloss/table for styling and layout, bubbletea and bubbles/progress/bubbles/spinner for progress and spinner components, and huh for interactive forms and prompts.

Thread Safety

SetTimeLocation and ResetTimeLocation are safe for concurrent use; the package protects the configured time location with an RW mutex. Native SpinnerWrapper lifecycle methods use mutexes and a wait group internally, and the implementation includes global coordination so only one spinner renders at a time.

ProgressBar.Update mutates the progress bar instance and should be treated as operating on shared mutable state. The implementation does not expose separate synchronization for callers, so concurrent access to the same instance should be externally coordinated.

Render*, Format*, and most constructor-style helpers are otherwise side-effect free apart from reading environment state or writing to stderr/stdout through explicit print-oriented APIs.

This specification is automatically maintained by the spec-extractor workflow.

Documentation

Overview

Package console provides terminal UI components and formatting utilities for the gh-aw CLI.

Naming Convention: Format* vs Render*

Functions in this package follow a consistent naming convention:

  • Format* functions return a formatted string for a single item or message. They are pure string transformations with no side effects. Examples: FormatSuccessMessage, FormatErrorMessage, FormatFileSize, FormatCommandMessage, FormatProgressMessage.

  • Render* functions produce multi-element or structured output (tables, boxes, trees, structs). They may return strings, slices of strings, or write directly to output. They are used when the output requires layout or structural composition. Examples: RenderTable, RenderStruct, RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderTree, RenderComposedSections.

Output Routing

All diagnostic output (messages, warnings, errors) should be written to stderr. Structured data output (JSON, hashes, graphs) should be written to stdout. Prefer Print* helpers (or fmt.Fprintln(os.Stderr, ...) with Format* helpers) for diagnostic output.

Package console provides terminal UI components including spinners for long-running operations.

Spinner Component

The spinner provides visual feedback during long-running operations with a minimal dot animation (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏). It automatically adapts to the environment:

  • TTY Detection: Spinners only animate in terminal environments (disabled in pipes/redirects)
  • Accessibility: Respects ACCESSIBLE environment variable to disable animations
  • Color Adaptation: Uses lipgloss adaptive colors for light/dark terminal themes

Implementation

This spinner uses idiomatic Bubble Tea patterns with tea.NewProgram() for proper message handling and rendering pipeline integration. It includes thread-safe lifecycle management:

  • Thread-safe start/stop tracking with mutex protection
  • Safe to call Stop/StopWithMessage before Start (no-op or message-only)
  • Prevents multiple concurrent Start calls
  • No deadlock when stopping before goroutine initializes
  • Leverages Bubble Tea's message passing for updates

Usage Example 

spinner := console.NewSpinner("Loading...")
spinner.Start()
// Long-running operation
spinner.Stop()

Accessibility

Spinners respect the ACCESSIBLE environment variable. When ACCESSIBLE is set to any value, spinner animations are disabled to support screen readers and accessibility tools. 

export ACCESSIBLE=1
gh aw compile workflow.md  # Spinners will be disabled

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClearLine 

func ClearLine()

ClearLine clears the current line in the terminal if stderr is a TTY Uses ANSI escape codes: \r moves cursor to start, \033[K clears to end of line

func ClearScreen 

func ClearScreen()

ClearScreen clears the terminal screen if stderr is a TTY Uses ANSI escape codes for cross-platform compatibility

func ConfirmAction 

func ConfirmAction(title, affirmative, negative string) (bool, error)

ConfirmAction shows an interactive confirmation dialog using Bubble Tea (huh) Returns true if the user confirms, false if they cancel or an error occurs

func FormatBanner 

func FormatBanner() string

FormatBanner returns the ASCII logo formatted with purple GitHub color theme. It applies the purple color styling when running in a terminal (TTY).

func FormatCommandMessage 

func FormatCommandMessage(command string) string

FormatCommandMessage formats a command execution message

func FormatCommandMessageStderr added in v0.83.0 

func FormatCommandMessageStderr(command string) string

FormatCommandMessageStderr formats a command execution message for stderr output.

func FormatError 

func FormatError(err CompilerError) string

FormatError formats a CompilerError with Rust-like rendering

func FormatErrorChain added in v0.59.1 

func FormatErrorChain(err error) string

FormatErrorChain formats an error and its full unwrapped chain in a reading-friendly way. For wrapped errors (fmt.Errorf with %w), each level of the chain is shown on a new indented line. For errors whose message contains newlines (e.g. errors.Join), each line is indented after the first.

func FormatErrorMessage 

func FormatErrorMessage(message string) string

FormatErrorMessage formats a simple error message (for stderr output)

func FormatErrorStderr added in v0.85.2 

func FormatErrorStderr(err CompilerError) string

FormatErrorStderr formats a CompilerError for stderr with stderr TTY detection.

func FormatErrorTextStderr added in v0.82.3 

func FormatErrorTextStderr(text string) string

FormatErrorTextStderr formats plain error-styled text for stderr output.

func FormatErrorWithSuggestions 

func FormatErrorWithSuggestions(message string, suggestions []string) string

FormatErrorWithSuggestions formats an error message with actionable suggestions

func FormatFileSize 

func FormatFileSize(size int64) string

FormatFileSize formats file sizes in a human-readable way (e.g., "1.2 KB", "3.4 MB")

func FormatInfoMessage 

func FormatInfoMessage(message string) string

FormatInfoMessage formats an informational message

func FormatInfoMessageStderr added in v0.81.5 

func FormatInfoMessageStderr(message string) string

FormatInfoMessageStderr formats an informational message for stderr output.

func FormatListItem 

func FormatListItem(item string) string

FormatListItem formats an item in a list

func FormatListItemStderr added in v0.81.5 

func FormatListItemStderr(item string) string

FormatListItemStderr formats a list item for stderr output.

func FormatNumber 

func FormatNumber(n int) string

FormatNumber formats large numbers in a human-readable way (e.g., "1k", "1.2k", "1.12M")

func FormatProgressMessage 

func FormatProgressMessage(message string) string

FormatProgressMessage formats a progress/activity message

func FormatProgressMessageStderr added in v0.83.0 

func FormatProgressMessageStderr(message string) string

FormatProgressMessageStderr formats a progress message for stderr output.

func FormatPromptMessage 

func FormatPromptMessage(message string) string

FormatPromptMessage formats a user prompt message

func FormatSectionHeader 

func FormatSectionHeader(header string) string

FormatSectionHeader formats a section header with proper styling

func FormatSectionHeaderStderr added in v0.81.5 

func FormatSectionHeaderStderr(header string) string

FormatSectionHeaderStderr formats a section header for stderr output.

func FormatSuccessMessage 

func FormatSuccessMessage(message string) string

FormatSuccessMessage formats a success message with styling

func FormatSuccessMessageStderr added in v0.81.5 

func FormatSuccessMessageStderr(message string) string

FormatSuccessMessageStderr formats a success message for stderr output.

func FormatTableHeaderStderr added in v0.82.3 

func FormatTableHeaderStderr(text string) string

FormatTableHeaderStderr formats table header text for stderr output.

func FormatTokens added in v0.79.8 

func FormatTokens(tokens int) string

FormatTokens formats a token count as a compact human-readable string. Zero is rendered as "-"; values below 1000 are rendered as plain integers; values in the thousands are rendered with one decimal place and a "K" suffix; values in the millions are rendered with one decimal place and an "M" suffix.

Examples: 

FormatTokens(0)        // "-"
FormatTokens(500)      // "500"
FormatTokens(1500)     // "1.5K"
FormatTokens(1200000)  // "1.2M"

func FormatVerboseMessage 

func FormatVerboseMessage(message string) string

FormatVerboseMessage formats verbose debugging output

func FormatWarningMessage 

func FormatWarningMessage(message string) string

FormatWarningMessage formats a warning message

func FormatWarningMessageStderr added in v0.83.0 

func FormatWarningMessageStderr(message string) string

FormatWarningMessageStderr formats a warning message for stderr output.

func IsAccessibleMode 

func IsAccessibleMode() bool

IsAccessibleMode detects if accessibility mode should be enabled based on environment variables. Accessibility mode is enabled when: - ACCESSIBLE environment variable is set to any value - TERM environment variable is set to "dumb" - NO_COLOR environment variable is set to any value

This function should be used by UI components to determine whether to: - Disable animations and spinners - Simplify interactive elements - Use plain text instead of fancy formatting

func IsCancelled added in v0.82.8 

func IsCancelled(err error) bool

IsCancelled reports whether err represents a deliberate user cancellation (Ctrl-C / Esc before form submission, i.e. huh.ErrUserAborted). Use this to distinguish graceful cancellation from genuine failures.

func LogVerbose 

func LogVerbose(verbose bool, message string)

LogVerbose outputs a verbose message to stderr only when verbose mode is enabled. This is a convenience helper to avoid repetitive if-verbose checks throughout the codebase.

func NewConfirmForm added in v0.82.3 

func NewConfirmForm(confirm *huh.Confirm) *huh.Form

NewConfirmForm creates a themed, accessibility-aware single-confirm form.

func NewForm added in v0.82.3 

func NewForm(groups ...*huh.Group) *huh.Form

NewForm creates a huh form with gh-aw's default theme and accessibility mode.

func NewInputForm added in v0.82.3 

func NewInputForm(input *huh.Input) *huh.Form

NewInputForm creates a themed, accessibility-aware single-input form.

func NewSelectForm added in v0.82.3 

func NewSelectForm[T comparable](selectField *huh.Select[T]) *huh.Form

NewSelectForm creates a themed, accessibility-aware single-select form.

func PrintBanner 

func PrintBanner()

PrintBanner prints the ASCII logo to stderr with purple GitHub color theme. This is used by the --banner flag to display the logo at the start of command execution.

func PrintCommandMessage added in v0.83.0 

func PrintCommandMessage(command string)

PrintCommandMessage formats and prints a command message to stderr.

func PrintErrorMessage added in v0.83.0 

func PrintErrorMessage(message string)

PrintErrorMessage formats and prints a simple error message to stderr.

func PrintInfoMessage added in v0.83.0 

func PrintInfoMessage(message string)

PrintInfoMessage formats and prints an info message to stderr.

func PrintSectionHeader added in v0.83.0 

func PrintSectionHeader(header string)

PrintSectionHeader formats and prints a section header to stderr.

func PrintSuccessMessage added in v0.83.0 

func PrintSuccessMessage(message string)

PrintSuccessMessage formats and prints a success message to stderr.

func PrintWarningMessage added in v0.83.0 

func PrintWarningMessage(message string)

PrintWarningMessage formats and prints a warning message to stderr.

func PromptSecretInput added in v0.42.14 

func PromptSecretInput(title, description string) (string, error)

PromptSecretInput shows an interactive password input prompt with masking The input is masked for security and includes validation Returns the entered secret value or an error

func RenderComposedSections 

func RenderComposedSections(sections []string)

RenderComposedSections composes and outputs a slice of sections to stderr

func RenderErrorBox 

func RenderErrorBox(title string) []string

RenderErrorBox renders an error/warning message with a rounded border box

func RenderInfoSection 

func RenderInfoSection(content string) []string

RenderInfoSection renders an info section with left border emphasis

func RenderStruct 

func RenderStruct(v any) string

RenderStruct renders a Go struct to console output using reflection and struct tags. It supports: - Rendering structs as markdown-style headers with key-value pairs - Rendering slices as tables using the console table renderer - Rendering maps as markdown headers

Struct tags: - `console:"title:My Title"` - Sets the title for a section - `console:"header:Column Name"` - Sets the column header name for table columns - `console:"omitempty"` - Skips zero values - `console:"-"` - Skips the field entirely

func RenderTable 

func RenderTable(config TableConfig) string

RenderTable renders a formatted table using lipgloss/table package

func RenderTitleBox 

func RenderTitleBox(title string, width int) []string

RenderTitleBox renders a title with a double border box in TTY mode

func ResetTimeLocation added in v0.77.5 

func ResetTimeLocation()

ResetTimeLocation clears any configured location override for rendered times.

func SetTimeLocation added in v0.77.5 

func SetTimeLocation(location *time.Location)

SetTimeLocation configures the location used when rendering time.Time values.

func ShowInteractiveList 

func ShowInteractiveList(title string, items []ListItem) (string, error)

ShowInteractiveList displays an interactive list using huh.Select with arrow key navigation. Returns the selected item's value, or an error if cancelled or failed.

Use this for standalone pickers outside a form context; prefer huh.Select directly when building a multi-field form with WithTheme/WithAccessible applied to the whole form.

func ShowWelcomeBanner added in v0.45.5 

func ShowWelcomeBanner(description string)

ShowWelcomeBanner clears the screen and displays the welcome banner for interactive commands. Use this at the start of interactive commands (add, trial, init) for a consistent experience.

func ToRelativePath 

func ToRelativePath(path string) string

ToRelativePath converts an absolute path to a relative path from the current working directory If the relative path contains "..", returns the absolute path instead for clarity

Types

type CompilerError 

type CompilerError struct {
	Position ErrorPosition
	Type     string // "error", "warning", "info"
	Message  string
	Context  []string // Source code lines for context
	Hint     string   // Optional hint for fixing the error
}

CompilerError represents a structured compiler error with position information

type ErrorPosition 

type ErrorPosition struct {
	File   string
	Line   int
	Column int
}

ErrorPosition represents a position in a source file

type FormField added in v0.42.14 

type FormField struct {
	Type        string // "input", "password", "confirm", "select"
	Title       string
	Description string
	Placeholder string
	Value       any                // Pointer to the value to store the result
	Options     []SelectOption     // For select fields
	Validate    func(string) error // For input/password fields
}

FormField represents a generic form field configuration

type ListItem 

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

ListItem represents an item in an interactive list

func NewListItem 

func NewListItem(title, description, value string) ListItem

NewListItem creates a new list item with title, description, and value

type ProgressBar 

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

ProgressBar provides a reusable progress bar component with TTY detection and graceful fallback to text-based progress for non-TTY environments.

Modes:

  • Determinate: When total size is known (shows percentage and progress)
  • Indeterminate: When total size is unknown (shows activity indicator)

Visual Features:

  • Scaled color blend effect from purple to cyan (adaptive for light/dark terminals)
  • Smooth color transitions using bubbles v2 blend capabilities
  • Blend scales with filled portion for enhanced visual feedback
  • Works well in both light and dark terminal themes

The gradient provides visual appeal without affecting functionality:

  • TTY mode: Visual progress bar with smooth gradient transitions
  • Non-TTY mode: Text-based percentage with human-readable byte sizes

func NewProgressBar 

func NewProgressBar(total int64) *ProgressBar

NewProgressBar creates a new progress bar with the specified total size (determinate mode) The progress bar automatically adapts to TTY/non-TTY environments

func (*ProgressBar) Update 

func (p *ProgressBar) Update(current int64) string

Update updates the current progress and returns a formatted string In determinate mode:

  • TTY: Returns a visual progress bar with gradient and percentage
  • Non-TTY: Returns text percentage with human-readable sizes

In indeterminate mode:

  • TTY: Returns a pulsing progress indicator
  • Non-TTY: Returns processing indicator with current value

type SelectOption added in v0.42.14 

type SelectOption struct {
	Label string
	Value string
}

SelectOption represents a selectable option with a label and value

type SpinnerWrapper 

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

SpinnerWrapper wraps the spinner functionality with TTY detection and Bubble Tea program

func NewSpinner 

func NewSpinner(message string) *SpinnerWrapper

NewSpinner creates a new spinner with the given message using MiniDot style. Automatically disabled when not running in a TTY or when ACCESSIBLE env var is set.

func (*SpinnerWrapper) Start 

func (s *SpinnerWrapper) Start()

func (*SpinnerWrapper) Stop 

func (s *SpinnerWrapper) Stop()

func (*SpinnerWrapper) StopWithMessage 

func (s *SpinnerWrapper) StopWithMessage(msg string)

func (*SpinnerWrapper) UpdateMessage 

func (s *SpinnerWrapper) UpdateMessage(message string)

type TableConfig 

type TableConfig struct {
	Headers   []string
	Rows      [][]string
	Title     string
	ShowTotal bool
	TotalRow  []string
	// TTYFunc overrides the default stdout TTY check used to determine whether
	// to apply styling. Set this when the rendered string will be written to a
	// file descriptor other than stdout (e.g. tty.IsStderrTerminal for stderr).
	TTYFunc func() bool
}

TableConfig represents configuration for table rendering

type TreeNode 

type TreeNode struct {
	Value    string
	Children []TreeNode
}

TreeNode represents a node in a hierarchical tree structure

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.