Help us shape the future of Go! Take the 2026 Go Developer Survey

clihelp

package
v1.42.0 Latest Latest
Warning

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

 Go to latest Published: Oct 24, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package clihelp owns local onboarding, help-topic routing, and safe command recovery. Feature commands supply complete guidance through command metadata.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Configure 

func Configure(root *cli.Command, args []string) ([]string, bool, error)

Configure keeps onboarding in CLI help, never in a shell startup file or an API command's output. Normalize help before Run so the framework still owns parsing, parent links and rendering, while help skips request setup. Commands marked "local-help" only display guidance. Existing authored guides remain intact, with "local-help-full" preferred when supplied.

func DescribeRequestInputs added in v1.39.0 

func DescribeRequestInputs(root *cli.Command)

DescribeRequestInputs annotates generated handlers before handwritten commands and aliases are installed. Generated handlers consume URL path inputs in declaration order; a handwritten flag's URL location alone does not establish positional syntax.

func DisplayInvocation added in v1.39.0 

func DisplayInvocation(root *cli.Command) string

DisplayInvocation escapes local help metadata for display, using openai when the invocation has not been configured. It never reads API response data.

func Invocation 

func Invocation(fallback string, args []string) string

Invocation returns a copyable executable name for help examples without interpreting argv as shell syntax or displaying terminal controls.

func RecoveryAt added in v1.39.0 

func RecoveryAt(command *cli.Command, name string, remaining []string, helpRequested bool, output ...io.Writer) string

RecoveryAt emits help for declared command names. A corrected group can retain an exact descendant path, but never an operand or an option value. Running the original operation requires keeping its private request context.

func RecoveryMessage added in v1.39.0 

func RecoveryMessage(command *cli.Command, output ...io.Writer) string

RecoveryMessage uses parsed positions, never the diagnostic text or original argv. The parser has already removed recognized flags and values.

func RunWithPager added in v1.42.0 

func RunWithPager(ctx context.Context, root *cli.Command, argv []string, run func() error) (returnErr error)

RunWithPager keeps bare interactive help at its first line. Explicit help, nonterminal streams, and CI retain the framework's ordinary output path.

func SearchResults added in v1.40.5 

func SearchResults(command *cli.Command, matches []commandsuggest.Candidate) string

SearchResults uses the help palette and layout without opening a terminal picker.

func ShellSafeCommandPath added in v1.40.3 

func ShellSafeCommandPath(command *cli.Command) bool

ShellSafeCommandPath checks whether command names can remain literal shell words. Explicitly authored examples and quoted executable invocations use separate paths.

func SuggestCommand added in v1.39.0 

func SuggestCommand(commands []*cli.Command, provided string) string

SuggestCommand takes a list of commands and a provided string to suggest a command name, ignoring case. A name within one edit of the input is always suggested and outranks every other name, because jaro-winkler undervalues typos in short names ("rn" for "run") and misranks long names that share a prefix. Otherwise the closest name must exceed suggestionThreshold. Returns an empty string when no command is sufficiently similar; the upstream urfave/cli error formatter omits the suggestion clause in that case.

func SuggestedCommand added in v1.40.3 

func SuggestedCommand(command *cli.Command, outputs []io.Writer, text string) string

An output is supplied only by the human-readable presenter. Formatting an error for JSON or a diagnostic comparison must not register an action.

func SuggestedCommandPath added in v1.40.3 

func SuggestedCommandPath(command *cli.Command, outputs []io.Writer, text string) string

Automatically derived paths must consist of literal shell words. Explicit examples use SuggestedCommand and retain their author's intended quoting.

func VisibleCommands added in v1.38.0 

func VisibleCommands(command *cli.Command) []*cli.Command

VisibleCommands gives help and completion the same order without changing parser definitions. Actions precede groups; equal ranks retain source order. Curated commands can preserve their complete declaration order through metadata.

func WithinOneEdit added in v1.39.0 

func WithinOneEdit(a, b string) bool

WithinOneEdit reports whether a and b differ by at most one insertion, deletion, substitution, or transposition of adjacent characters.

Types

type Content added in v1.39.0 

type Content struct {
	Summary           string
	InputNote         string
	Description       string
	Examples          []Example
	GlobalOptionsNote string
	Notes             string
}

Content supplies complete handwritten guidance without changing command behavior. Command examples omit the executable; the renderer supplies the safe invocation.

type Example added in v1.39.0 

type Example struct {
	Description string
	Command     string
}

func CommandExamples added in v1.40.3 

func CommandExamples(command *cli.Command, path string) []Example

CommandExamples returns the same declared examples that complete help renders. The returned slice can be modified without changing help's definitions.

type FlagGroup added in v1.29.0 

type FlagGroup struct {
	Title string
	Names []string
	// Owner restricts a group to flags declared by this command. Nil matches by name.
	Owner *cli.Command
}

FlagGroup is presentation metadata supplied by handwritten features. It never changes parser order, categories, flag aliases or request defaults.

type FlagLabel added in v1.39.0 

type FlagLabel struct {
	Owner *cli.Command
	Names []string
	Label string
}

FlagLabel supplies a semantic value label only for flags declared by Owner.

type FlagUsage added in v1.39.0 

type FlagUsage struct {
	Owner *cli.Command
	Names []string
	Usage string
}

FlagUsage supplies display-only guidance for flags declared by Owner.

type PagerError added in v1.42.0 

type PagerError struct{ Cause error }

PagerError preserves the cause while exposing only safe recovery guidance.

func (*PagerError) Error added in v1.42.0 

func (e *PagerError) Error() string

func (*PagerError) Unwrap added in v1.42.0 

func (e *PagerError) Unwrap() error

type SuggestedText added in v1.40.3 

type SuggestedText struct {
	io.Writer
	// contains filtered or unexported fields
}

Escape the complete readable result before adding trusted insertion links. The writer carries only explicitly declared commands, never discovered prose.

func NewSuggestedText added in v1.40.3 

func NewSuggestedText(out io.Writer, command *cli.Command) *SuggestedText

NewSuggestedText prepares readable output containing explicitly declared suggestions.

func NewSuggestedTextTo added in v1.40.3 

func NewSuggestedTextTo(out, destination io.Writer, command *cli.Command) *SuggestedText

NewSuggestedTextTo separates a wrapped writer from its terminal destination.

func (*SuggestedText) WriteText added in v1.40.3 

func (p *SuggestedText) WriteText(text string) error

WriteText escapes text before rendering trusted insertion links.

type UnknownTopicError added in v1.38.0 

type UnknownTopicError struct {
	Parent    *cli.Command
	Topic     string
	Remaining []string
}

UnknownTopicError retains the last valid group for safe local recovery guidance. Presenters can suggest declared commands without echoing an untrusted topic.

func (*UnknownTopicError) Error added in v1.38.0 

func (e *UnknownTopicError) Error() string

func (*UnknownTopicError) ExitCode added in v1.38.0 

func (*UnknownTopicError) ExitCode() int

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.