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 and cobratree were written here, from the
command-line code clusterctl and sind each carried
(decision 21,
decision 24).
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 |
progress/mcpprogress |
a tool call's progress as MCP progress notifications |
progress/eventlog |
reading back the event log a program or its child wrote |
fanout |
bounded worker pools that report their targets as progress |
fanout/fanouttest |
counting the calls a fake is in the middle of, to prove a limit |
cliout |
a command's result as a table aligned by display width, and as JSON, escaped |
cobratree |
a strict cobra command tree, usage errors, the build info |
cobratree/cobratreetest |
running a command tree in a test, checking a manual's command lines |
localweb |
the guard of a local web server: its listener, the Host and cross-site checks, the headers |
localweb/session |
the launch token exchanged for a session cookie, and the CSRF token |
localweb/sse |
a page's live fragments as Server-Sent Events, and the topics they change in |
localweb/localwebtest |
a signed-in client and a reader of event streams, for a test of a local web server |
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/progress/mcpprogress a tool call's progress as MCP progress notifications github.com/GSI-HPC/go-clikit/progress/eventlog reading back the event log a program or its child wrote github.com/GSI-HPC/go-clikit/fanout bounded worker pools that report their targets as progress github.com/GSI-HPC/go-clikit/fanout/fanouttest counting the calls a fake is in the middle of, to prove a limit github.com/GSI-HPC/go-clikit/cliout a command's result as a table and as JSON, escaped for a terminal github.com/GSI-HPC/go-clikit/cobratree a strict cobra command tree, usage errors, the build info github.com/GSI-HPC/go-clikit/cobratree/cobratreetest running a command tree in a test, checking a manual's command lines github.com/GSI-HPC/go-clikit/localweb the guard of a local web server: listener, Host and cross-site checks, headers github.com/GSI-HPC/go-clikit/localweb/session the launch token exchanged for a session cookie, and the CSRF token github.com/GSI-HPC/go-clikit/localweb/sse a page's live fragments as Server-Sent Events, and the topics they change in github.com/GSI-HPC/go-clikit/localweb/localwebtest a signed-in client and a reader of event streams, for a test of a local server
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; an MCP server sends a tool call's progress with progress/mcpprogress, and a program reads back the event log it or a child wrote with progress/eventlog. A command built with cobra makes its tree strict about its command line with cobratree, and one that serves a page to its user guards the server with localweb. 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 cliout writes the result of a command for a person and for a program: a Table in columns aligned by the columns a terminal gives its text, and JSON, every string in either made safe for a terminal.
|
Package cliout writes the result of a command for a person and for a program: a Table in columns aligned by the columns a terminal gives its text, and JSON, every string in either made safe for a terminal. |
|
Package cobratree makes a cobra command tree strict about its command line, marks the errors of a command line as usage errors, and reads what the Go toolchain recorded about the binary, for its version command.
|
Package cobratree makes a cobra command tree strict about its command line, marks the errors of a command line as usage errors, and reads what the Go toolchain recorded about the binary, for its version command. |
|
cobratreetest
Package cobratreetest runs a cobra command tree in a test, and checks the command lines a program's manual and help show against the tree.
|
Package cobratreetest runs a cobra command tree in a test, and checks the command lines a program's manual and help show against the tree. |
|
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. |
|
fanouttest
Package fanouttest counts the calls a fake is in the middle of, so that a test can tell how many of them a fan-out ran at once: the requests a fake transport is asked to run, those a fake HTTP client sends to a service processor, the connections a scan dials.
|
Package fanouttest counts the calls a fake is in the middle of, so that a test can tell how many of them a fan-out ran at once: the requests a fake transport is asked to run, those a fake HTTP client sends to a service processor, the connections a scan dials. |
|
Package localweb is the guard of a web page that a command-line program serves to the user who started it, on the user's own machine: the listener, the server, and the checks a request passes before the program's handler sees it.
|
Package localweb is the guard of a web page that a command-line program serves to the user who started it, on the user's own machine: the listener, the server, and the checks a request passes before the program's handler sees it. |
|
localwebtest
Package localwebtest helps to test a local web server that uses the packages of localweb: a Client that signs in with the launch token and sends its requests as a page of the server's own origin does, and a Reader of the events of a stream.
|
Package localwebtest helps to test a local web server that uses the packages of localweb: a Client that signs in with the launch token and sends its requests as a page of the server's own origin does, and a Reader of the events of a stream. |
|
session
Package session lets into a local web server only the browser that opened the address the program printed: the address carries a launch token, which the first navigation exchanges for a session cookie, and each session has a CSRF token that every request that may change something sends back.
|
Package session lets into a local web server only the browser that opened the address the program printed: the address carries a launch token, which the first navigation exchanges for a session cookie, and each session has a CSRF token that every request that may change something sends back. |
|
sse
Package sse streams the live parts of a local web page as Server-Sent Events: each event is named after a fragment of the page and carries its HTML, which htmx's SSE extension swaps into the element of that name.
|
Package sse streams the live parts of a local web page as Server-Sent Events: each event is named after a fragment of the page and carries its HTML, which htmx's SSE extension swaps into the element of that name. |
|
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. |
|
eventlog
Package eventlog reads the event log that progress.Log writes, version 1 of the format doc/event-log.md describes: what a view of the runs a program made reads, and what a server reads back from a command it ran as a child, to send on the child's progress.
|
Package eventlog reads the event log that progress.Log writes, version 1 of the format doc/event-log.md describes: what a view of the runs a program made reads, and what a server reads back from a command it ran as a child, to send on the child's progress. |
|
mcpprogress
Package mcpprogress sends the progress of a call to an MCP tool, as the progress notifications of the Model Context Protocol: how many of the targets the call expects have ended, of how many, and a line for a person to read, such as "read the groups: 3/16 done, 1 failed".
|
Package mcpprogress sends the progress of a call to an MCP tool, as the progress notifications of the Model Context Protocol: how many of the targets the call expects have ended, of how many, and a line for a person to read, such as "read the groups: 3/16 done, 1 failed". |
|
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 and fills text to a number of them.
|
Package termtext makes untrusted text safe to write to a terminal, and measures how many columns text takes there and fills text to a number of them. |