README
¶
go-clikit
The runtime GSI-HPC's command-line tools share. Report progress as spans
carried in a context.Context, and let the command choose how to show it: a
live tree on a terminal, a counter, plain lines for a CI log, or a JSONL
event log for programs. Run work in bounded pools that report their targets.
Escape untrusted text before it reaches a terminal. A library that reports
spans costs nothing when no command is listening.
Status
The packages were written for clusterctl, a
command-line tool for administering HPC clusters, and became a module of
their own when sind, which runs Slurm
clusters in Docker, set out to use them too. They moved here with their
history, as clusterctl v0.4.0 shipped them, and their first release will be
v0.1.0. progress/cliprogress was written here, from the command-line glue
clusterctl and sind each carried
(decision 21).
doc/architecture.md says how they fit together.
| Package | What it holds |
|---|---|
termtext |
escaping untrusted text for a terminal, and display width |
progress |
spans in a context.Context, the JSONL event log, TRACEPARENT |
progress/display |
the live tree, the counter, plain lines, the summary |
progress/cliprogress |
the words of --progress, a command's display and event log, the private log file |
progress/progresstest |
capturing and checking the events a command reports |
fanout |
bounded worker pools that report their targets as progress |
Install
$ go get github.com/GSI-HPC/go-clikit/progress
It needs Go 1.26 or newer: the module requires the oldest Go release the Go project still supports, and follows it up after each Go release (decision 2). It requires few modules, and never cobra outside a package about cobra (decision 3).
Versions
Releases are signed tags vX.Y.Z, and each has
release notes. The module
is at v0 while its API settles, so a minor release may change it; its notes
say how (decision 4).
Contributing
The repository carries a mise.toml, so the toolchain comes from
mise if you use it:
$ mise install # Go and golangci-lint, at the versions CI uses
$ make lint # golangci-lint
$ make test # tests under the race detector
$ make cover # every file at 100% coverage
$ make help # every other check CI runs
Commits are Conventional Commits.
How the module is built and why is in doc/, and a change that
takes a decision adds it to doc/decisions.md.
Instructions for coding agents are in
AGENTS.md. Report vulnerabilities as
SECURITY.md says.
AI disclosure
This project is developed with the help of AI coding tools. Changes written
by Anthropic's Claude Code agent are committed as
Claude <noreply@anthropic.com> and/or carry a Co-Authored-By: Claude …
trailer.
Licence
Copyright 2026 GSI Helmholtz Centre for Heavy Ion Research GmbH http://www.gsi.de
Apache-2.0. See LICENSE.
Documentation
¶
Overview ¶
Package clikit introduces the runtime that GSI-HPC's command-line tools share. It holds no API: each part of the kit is a package of its own, imported by its path:
github.com/GSI-HPC/go-clikit/termtext escaping untrusted text for a terminal, and display width github.com/GSI-HPC/go-clikit/progress spans carried in a context.Context, the JSONL event log, TRACEPARENT github.com/GSI-HPC/go-clikit/progress/display the live tree, the counter, plain lines for CI, the summary github.com/GSI-HPC/go-clikit/progress/cliprogress the words of --progress, a command's display, summary and event log github.com/GSI-HPC/go-clikit/progress/progresstest capturing and checking the events a command reports github.com/GSI-HPC/go-clikit/fanout bounded worker pools that report their targets as progress
A library package reports what it does through progress, which costs nothing when no command is listening, and runs work for many targets with fanout. A command decides how the work is shown: it creates a progress.Bus, attaches a display from progress/display and, if asked, an event log, and passes the Bus down in its context.Context, or has progress/cliprogress do so from its flags. The kit knows no program: a program's name, the noun for its targets and its rule for exit codes are parameters.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fanout works on many items at once, a bounded number at a time.
|
Package fanout works on many items at once, a bounded number at a time. |
|
Package progress reports what a command is doing while it runs.
|
Package progress reports what a command is doing while it runs. |
|
cliprogress
Package cliprogress is the command line's side of progress: the words a flag such as --progress takes, the rule that picks a display from them and from what the program found out about its streams, and a Run, which makes the Bus, the display, the summary and the event log of one command and takes them down again, in order, once the command has ended.
|
Package cliprogress is the command line's side of progress: the words a flag such as --progress takes, the rule that picks a display from them and from what the program found out about its streams, and a Run, which makes the Bus, the display, the summary and the event log of one command and takes them down again, in order, once the command has ended. |
|
display
Package display shows the progress of a command on its standard error, from the events of its progress.Bus: the live tree, a few rows at the bottom of a terminal that show the work under way and what of it failed; the counter, one line there that says how far the work has got; plain lines, one for each thing worth a line, for a log as much as a terminal; and the summary a display leaves behind once the command has ended.
|
Package display shows the progress of a command on its standard error, from the events of its progress.Bus: the live tree, a few rows at the bottom of a terminal that show the work under way and what of it failed; the counter, one line there that says how far the work has got; plain lines, one for each thing worth a line, for a log as much as a terminal; and the summary a display leaves behind once the command has ended. |
|
progresstest
Package progresstest captures the progress events of a test, draws them as a tree that does not depend on the order concurrent work happened in, and checks that they keep the promises the progress package makes to every sink.
|
Package progresstest captures the progress events of a test, draws them as a tree that does not depend on the order concurrent work happened in, and checks that they keep the promises the progress package makes to every sink. |
|
Package termtext makes untrusted text safe to write to a terminal, and measures how many columns text takes there.
|
Package termtext makes untrusted text safe to write to a terminal, and measures how many columns text takes there. |