cliprogress · go-clikit

cliprogress is the command line’s side of progress. It has the words of --progress, the rule that picks a display from them and from what the program found out about its streams, and a cliprogress.Session, which makes the Bus, the display, the summary and the event log of one command, and takes them down in order.

--progress auto|tty|counter|plain|none
--progress-log FILE

How auto picks: the tree only where a person watches a terminal.

Use it#

The program reads its flag and its variable, asks the system about its streams, and passes what it found in cliprogress.Options. The package reads no environment.

clock := time.Date(2026, 10, 9, 12, 0, 0, 0, time.UTC)
r, err := cliprogress.Start(context.Background(), cliprogress.Options{
	Program: "prog",
	Mode:    cliprogress.Setting{Flag: "--progress", Given: true, Value: "plain"},
	Stderr:  os.Stdout,
	Now:     func() time.Time { return clock },
})
if err != nil {
	fmt.Println(err) // a usage error
	return
}
ctx, cmd := progress.Start(r.Context(), progress.KindCommand, "delete cluster")
_, step := progress.Start(ctx, progress.KindStep, "mesh")
clock = clock.Add(2 * time.Second)
failed := errors.New("network sind-mesh has active endpoints")
step.End(failed)
cmd.End(failed)
r.Finish(true)

[0:00] delete cluster › mesh: start
[0:02] delete cluster › mesh: failed in 2.0s
prog: delete cluster: failed in 2.0s

ExampleStart in progress/cliprogress/example_test.go. CI runs it and checks its output.

Name	What it does
`cliprogress.Start`	writes the notes, picks the display, opens the log, makes the Bus
`cliprogress.Session.Writer`, `cliprogress.Session.Lines`	the writers that go through the display
`cliprogress.Session.Finish`	closes the Bus, takes the display off, closes the log, writes the summary
`cliprogress.Choose`	the rule alone, for a program that draws by itself
`cliprogress.IsTerminal`, `cliprogress.TerminalSize`, `cliprogress.InForeground`, `cliprogress.UTF8Locale`	what the program asks the system
`cliprogress.ThemeFor`	the colours that `NO_COLOR`, `TERM` and `COLORTERM` allow
`cliprogress.Ask`, `cliprogress.Yes`	a question, with no display drawn over it

CAUTION

The flag refuses what it cannot have: --progress tty without a terminal is a usage error. The variable fails no command, because a profile sets it once for every script. It shows nothing there, and writes a note only for a word that it does not take.

The event log file#

The log is appended to a file that only the user can read, mode 0600. A file that is there already must be the user’s, and nobody else may read or write it. Options.DefaultLog keeps a log unasked, and Options.RotateAt moves it aside before it grows without end (decision 31).

Fixed interfaces#

The words that cliprogress.Modes names, in their order.
The texts of the errors and notes that the package returns and writes, the refusals of the log file included (decision 21).
The rule of ThemeFor.