README
¶
___ _ _
/ __| | | |
| (_ | |_| |
\___|\___/
gu
A k9s-style terminal UI for GitLab and GitHub.
Browse groups, read merge requests, watch pipelines, review diffs and land cross-repo feature stacks — without leaving the terminal or opening a browser.
Why
glab and gh are excellent at single commands. They are less good at the
thing you actually do all day: looking around. Which of my merge requests is
red? What is blocking this stack? What changed in that file?
gu is that view. It borrows k9s's shape — a category sidebar, a resource pane,
: commands, / filters — and points it at both providers at once.
| Knows where you are | A repository opens that project; a directory of repositories opens the group they share; anywhere else, your account. It reads the remotes — nothing to configure. |
| Two accounts, one host | A profile is a pair of CLI config directories, not a hostname, because personal and work accounts routinely share gitlab.com. |
| Rich merge-request pages | A description card, an activity feed of comments and events, a details sidebar, and the pipeline as a graph with each job's run time. |
| Real diff review | Select a line, a block or a run of words and comment on exactly that. Suggest a change the author applies in one click. Published as threads, not a dozen notifications. |
| Cross-repo stacks | One feature over several repositories, in dependency order, with a merge that refuses until it is genuinely ready. |
| Read-only when you want it | A viewer mode enforced below the UI, not by hiding buttons. |
Install
brew tap atomic-blend/gu https://gitlab.com/atomic-blend/gu-cli/homebrew-gu
brew install gu
Or from source: go install gitlab.com/atomic-blend/gu-cli/gu@latest.
Authentication is delegated to the official CLIs — gu performs no OAuth and
stores no tokens of its own:
glab auth login # GitLab
gh auth login # GitHub
Use it
cd ~/work/backend/auth && gu # → that project
cd ~/work/backend && gu # → that group
gu ~/work/apps # → a given path
gu --read-only # → a viewer; every mutation refused
Then ? for the keys, 1–9 for the categories, / to filter, : for the
command bar, enter to go in and esc to come back.
Documentation
| Installation · Authentication · Your first session | Getting started |
| Navigating · Keys | Driving it |
| Merge requests & issues · Reviewing a diff | The daily loop |
| Pipelines & jobs · Boards · Cross-repo stacks | Everything else |
| Config file · Profiles · Read-only | Settings, all optional |
| Architecture · Releasing · Demo | Working on gu |
Development
make test # hermetic, offline
make test-integration # against the real GitLab API
make lint # every pre-commit hook
make help # every target
Branch from main, Conventional Commits, everything through a merge request,
and never bypass the hooks. The demo above is recorded rather than drawn —
docs/development/demo.md is how to remake it.
Built with Bubble Tea, Lip Gloss and Glamour.
Licence
GNU AGPL v3. Fork it, run it, change it — publish your changes under the same terms.
Documentation
¶
Overview ¶
Command gu is a k9s-style terminal UI for browsing and operating GitLab and GitHub repositories, groups, issues and merge requests.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd wires gu's command-line entry point: it resolves the profile, detects context, authenticates through the CLIs, and starts the TUI.
|
Package cmd wires gu's command-line entry point: it resolves the profile, detects context, authenticates through the CLIs, and starts the TUI. |
|
internal
|
|
|
auth
Package auth obtains API tokens by delegating entirely to the glab and gh CLIs.
|
Package auth obtains API tokens by delegating entirely to the glab and gh CLIs. |
|
config
Package config loads gu's user configuration and resolves settings that have more than one possible source.
|
Package config loads gu's user configuration and resolves settings that have more than one possible source. |
|
ctxdetect
Package ctxdetect works out what the user is looking at: a specific project, a GitLab group, or nothing in particular.
|
Package ctxdetect works out what the user is looking at: a specific project, a GitLab group, or nothing in particular. |
|
diff
Package diff models a unified diff: the files it touches, their hunks, and the lines within them, down to the runs that changed inside a single line.
|
Package diff models a unified diff: the files it touches, their hunks, and the lines within them, down to the runs that changed inside a single line. |
|
forge
Package forge defines gu's provider-neutral view of a code-hosting service.
|
Package forge defines gu's provider-neutral view of a code-hosting service. |
|
forge/github
Package github implements forge.Forge against the GitHub REST API.
|
Package github implements forge.Forge against the GitHub REST API. |
|
forge/gitlab
Package gitlab implements forge.Forge against the GitLab REST API.
|
Package gitlab implements forge.Forge against the GitLab REST API. |
|
httpcache
Package httpcache caches provider responses on disk, so a screen you have already seen is drawn from the last answer while a fresh one is fetched.
|
Package httpcache caches provider responses on disk, so a screen you have already seen is drawn from the last answer while a fresh one is fetched. |
|
profile
Package profile resolves which account identity gu should act as.
|
Package profile resolves which account identity gu should act as. |
|
recent
Package recent remembers which projects were opened, so the home screen can offer the common path in one keypress rather than three levels of explorer.
|
Package recent remembers which projects were opened, so the home screen can offer the common path in one keypress rather than three levels of explorer. |
|
stack
Package stack models a feature that spans several repositories: a set of merge requests with a dependency order between them.
|
Package stack models a feature that spans several repositories: a set of merge requests with a dependency order between them. |
|
ui
Package ui implements gu on top of the ninebox shell.
|
Package ui implements gu on top of the ninebox shell. |