cliui

package
v0.22.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package cliui owns inline terminal presentation, not authentication or storage.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanInteract

func CanInteract(in io.Reader, out io.Writer) bool

CanInteract requires terminal input and the supplied stderr writer; NO_COLOR does not disable interaction.

func ChoiceName added in v0.13.0

func ChoiceName(choice string) string

ChoiceName is a choice's name: what is before a comma or a colon, which says what it does ("no" of "no, skip it"). Typing the name chooses it.

func PickOrg

func PickOrg(ctx context.Context, in io.Reader, out io.Writer, title string, orgs []OrgChoice, cloud *CloudChoices, allowURL bool) (int, string, error)

PickOrg returns the original stored index, or -1 plus a canonical URL: a cloud server's origin, or the URL entered. With allowURL, it offers cloud's servers after orgs, showing those without an origin as upcoming, and cloud's support email under the list. Esc or Ctrl-C returns context.Canceled. Callers own interaction policy and pass stderr as out.

func ReadEntry added in v0.18.0

func ReadEntry(ctx context.Context, in io.Reader, out io.Writer, opts EntryOptions) (string, error)

ReadEntry reads one entry of a console at a terminal, as a shell reads a line: the prompt, then what the person types, ended by Enter, and left on screen after the prompt. Up and Down step through the history; Ctrl-C clears the entry, or on an empty one shows opts.Leave; Ctrl-D on an empty entry is io.EOF. The program ends with the entry, so whatever runs next has the terminal to itself. Callers pass stdout as out.

func RunActivity

func RunActivity(ctx context.Context, in io.Reader, out io.Writer, initial string, work func(context.Context, func(string), func(string)) error) error

RunActivity runs work in a Tea command and waits for its cleanup even after cancellation or a UI error. Progress labels must be bounded and nonsecret. The second callback prints persistent user messages above the activity; callers handle plain mode and final output.

func SafeText

func SafeText(s string) string

SafeText strips terminal escapes and flattens untrusted display text into one plain line.

func Width added in v0.15.1

func Width(w io.Writer) int

Width is how wide to wrap text written to w: the terminal's width, capped at maxWidth, or 0, no wrapping, when w isn't a terminal.

func Wrap added in v0.15.1

func Wrap(text string, width, indent int) []string

Wrap splits text into lines that fit width after an indent of that many columns; 0, or a width too narrow to read, doesn't wrap.

Types

type CloudChoices added in v0.21.0

type CloudChoices struct {
	Servers      []cloudapi.CloudServer
	SupportEmail string
}

CloudChoices are the cloud servers login offers besides organization URL entry, and the address to email for another region, which login shows under them, linked.

type EntryOptions added in v0.18.0

type EntryOptions struct {
	Prompt  string   // before the entry: "query> "
	History []string // earlier entries, oldest first, for Up and Down
	Leave   string   // the hint shown under the prompt after Ctrl-C on an empty entry, in Status's place
	// Warning, Context, Aside and Status share the line under the prompt
	// while typing, each styled: on the left, Warning, what the next entry
	// would fail for, where the eye lands, then Context, where the session
	// is; on the right, Aside, a state (a server's), then Status at the far
	// right, a notice's badge. Too narrow, Context is cut short with … first,
	// then Aside, then Status, then Warning. "" for none.
	Warning string
	Context string
	Aside   string
	Status  string
	// Refresh, when set, gives Aside again a few times a second while
	// typing: for what changes under it, a server starting.
	Refresh func() string
	// Ends reports whether the text typed is a whole entry, for Enter to end
	// it rather than start a line (AQL's ;;); nil, Enter always ends it.
	// Alt+Enter and Ctrl+Enter end it whatever it holds.
	Ends func(text string) bool
}

EntryOptions are what ReadEntry shows and remembers.

type OrgChoice

type OrgChoice struct {
	Name string
	URL  string
}

OrgChoice is a stored organization's display name and canonical URL, never credentials.

type Printer

type Printer struct {
	Styles TerminalStyles
	// contains filtered or unexported fields
}

Printer writes a command's progress, warnings, questions and outcomes as lines told apart at a glance: each kind has its mark, colored on a terminal, and a line too long for the terminal wraps under its text, not under its mark. Sections are separated by a blank line. Off a terminal, it writes the same marks without color or wrapping.

func NewPrinter

func NewPrinter(w io.Writer) *Printer

NewPrinter prints to w, styled and wrapped when w is a terminal.

func (*Printer) Detail

func (p *Printer) Detail(text string)

Detail quotes text from elsewhere (a server's message, say), indented under the line before it, its own line breaks kept and its terminal escapes removed.

func (*Printer) Fail

func (p *Printer) Fail(format string, a ...any)

Fail says something did not work.

func (*Printer) Gap

func (p *Printer) Gap()

Gap separates what comes next from what came before with a blank line.

func (*Printer) Input added in v0.13.0

func (p *Printer) Input(question string)

Input writes a question that takes a line of text, leaving the cursor after it for the answer.

func (*Printer) Note

func (p *Printer) Note(format string, a ...any)

Note adds to the line before it, indented under its text.

func (*Printer) Open

func (p *Printer) Open()

Open writes a pending section's heading now, before something else writes to the same place: a question asked through another Printer, say.

func (*Printer) Question

func (p *Printer) Question(question string, choices ...string)

Question writes a question with its choices, the last the default, leaving the cursor after it for the answer. A choice can say what it does after its name, following a comma or a colon ("no, skip it"); the question then lists its choices one to a line, and names the default by its name alone.

func (*Printer) Section

func (p *Printer) Section(title string)

Section starts a group of lines under a heading, written with its first line: a section with nothing in it shows nothing.

func (*Printer) Step

func (p *Printer) Step(format string, a ...any)

Step says what is being done now.

func (*Printer) Success

func (p *Printer) Success(format string, a ...any)

Success says something was done.

func (*Printer) Warn

func (p *Printer) Warn(format string, a ...any)

Warn says something the reader should act on, though the command goes on.

type TerminalStyles

type TerminalStyles struct {
	Heading, Muted, Accent, Selection, Success, Warning, Error, Link, Code, Key lipgloss.Style
	// contains filtered or unexported fields
}

TerminalStyles gives auth views a shared hierarchy; its zero value renders plain text.

func NewTerminalStyles

func NewTerminalStyles(out io.Writer) TerminalStyles

NewTerminalStyles styles only terminal output, respecting NO_COLOR, CI and TERM=dumb. Hues: violet, anfra's accent, for what can be acted on; bright blue for a key; green, yellow and red for tones; everything else by weight. Violet is the one color not of the user's terminal palette, converted to what the terminal shows (the nearest of 256 colors; magenta, of 16), and mid-light, for light and dark backgrounds alike. A command to run is a code span, a violet chip; of 16 colors, bold magenta, without a fill.

func (TerminalStyles) LinkTo added in v0.21.0

func (s TerminalStyles) LinkTo(text, url string) string

LinkTo renders text in the Link style as a hyperlink to url (OSC 8), which a terminal that supports them makes clickable and others show as the text. Plain text when the styles are off.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL