README
¶
Lazylab
Keyboard-driven terminal UI for GitLab projects, pipelines, jobs, and merge requests.
Background
Lazylab navigates GitLab the way lazygit navigates git. A multi-panel TUI with vim-style keys, pipeline auto-refresh, and a yazi-inspired file explorer. For scripting, lazylab does not reinvent a CLI: press y on any focused item to copy the equivalent glab command to your clipboard, or Y to browse every glab command available for it. The TUI is for interactive discovery; glab is for execution.
Install
go install github.com/GF6599/lazylab/cmd/lazylab@latest
Or build from source:
git clone https://github.com/GF6599/lazylab.git
cd lazylab && go build ./cmd/lazylab
Requires Go 1.26+ and a GitLab personal access token with api scope, or an authenticated glab (see Configuration).
Usage
TUI
export GITLAB_TOKEN=glpat-xxxx
lazylab
The UI opens on the alternate screen. Press ? for the contextual help overlay, which lists every keybinding for the focused panel. Quit with q or Ctrl+C.
To explore the UI without a token, pass --demo for fake data.
Emitting glab commands
lazylab is TUI-only. Rather than ship its own scripting CLI, it generates glab commands for whatever you have focused:
ycopies the most usefulglabcommand for the focused project, pipeline, job, or merge request to the clipboard.Yopens a preview overlay listing everyglabcommand for that item (j/kto move,enteroryto copy,escto close).
Every emitted command carries -R <group/project>, so it targets the project you were browsing regardless of your shell's working directory. Paste it, run it, or drop it into a script. Executing the commands needs glab on your PATH.
Configuration
A GitLab token is the only required value, and you can skip even that when glab is logged in (see below). Everything else has a default. Precedence (highest first): CLI flags > env vars (GITLAB_* prefix) > config file > glab credentials > compiled defaults.
Run lazylab --help for the flag surface. Defaults and validation rules live in internal/config/config.go.
Config files are optional. Viper parses YAML, TOML, and JSON. Point at one with --config <path> or $LAZYLAB_CONFIG.
glab credentials
If no token is supplied by flag, env, or config file, lazylab falls back to the credentials glab has stored (from glab auth login). It borrows both the token and the host glab is configured for, so a glab-authenticated user, including on self-hosted GitLab, can run lazylab with no further setup. An explicit --host / GITLAB_HOST is still honored; glab only fills what you leave unset.
Architecture
| Package | Role |
|---|---|
cmd/lazylab |
Cobra root command that loads config and launches the TUI. |
internal/config |
Viper-driven loader with flag/env/file/default precedence. |
internal/gitlab |
Thin wrapper around client-go for projects, pipelines, jobs, MRs. |
internal/ui |
Bubble Tea model: multi-panel layout, state machines, caching. |
internal/glabcmd |
Maps a focused entity to its glab commands (pure, no I/O). |
internal/glabauth |
Reads glab's stored token/host so GITLAB_TOKEN is optional. |
internal/redacting |
slog handler that scrubs tokens before they reach stderr. |
internal/demo |
In-memory gitlab.Service for --demo runs. |
Caching
The TUI persists three files under the OS cache directory (~/Library/Caches/lazylab on macOS, ~/.cache/lazylab on Linux), each keyed by GitLab host:
projects_<host>.jsonholds the project list. Force-refresh withCtrl+R.favorites_<host>.jsonholds pinned projects.preferences_<host>.jsonholds layout, theme, and tab state.
Pipeline status lives in an in-memory LRU (last 100 projects) with a 5-second refresh tick. Delete the files on disk to start over.
Development
The project ships a justfile. Run just --list for the recipe surface. Tests use go test -race ./...; coverage targets >80% for internal/gitlab, per CLAUDE.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lazylab
command
Package main is the entrypoint for lazylab.
|
Package main is the entrypoint for lazylab. |
|
internal
|
|
|
config
Package config resolves lazylab's runtime configuration from multiple sources with a strict precedence order: CLI flags beat environment variables, which beat config file values, which beat credentials stored by the glab CLI (when injected via WithGlabResolver), which beat compiled defaults.
|
Package config resolves lazylab's runtime configuration from multiple sources with a strict precedence order: CLI flags beat environment variables, which beat config file values, which beat credentials stored by the glab CLI (when injected via WithGlabResolver), which beat compiled defaults. |
|
demo
Package demo provides a stateless DemoService implementing gitlab.Service with hardcoded fake data.
|
Package demo provides a stateless DemoService implementing gitlab.Service with hardcoded fake data. |
|
diffutil
Package diffutil parses unified-diff text and renders snippets.
|
Package diffutil parses unified-diff text and renders snippets. |
|
gitlab
Package gitlab provides a TUI-oriented facade over gitlab.com/gitlab-org/api/client-go.
|
Package gitlab provides a TUI-oriented facade over gitlab.com/gitlab-org/api/client-go. |
|
glabauth
Package glabauth reads the GitLab credentials that the glab CLI has stored, so lazylab can authenticate without a separately-configured GITLAB_TOKEN when glab is already logged in.
|
Package glabauth reads the GitLab credentials that the glab CLI has stored, so lazylab can authenticate without a separately-configured GITLAB_TOKEN when glab is already logged in. |
|
glabcmd
Package glabcmd maps a focused lazylab entity to the equivalent glab CLI commands.
|
Package glabcmd maps a focused lazylab entity to the equivalent glab CLI commands. |
|
redacting
Package redacting strips GitLab tokens and other secret-shaped values from strings before they reach user-visible output (logs, stderr, TUI status lines, CLI tables).
|
Package redacting strips GitLab tokens and other secret-shaped values from strings before they reach user-visible output (logs, stderr, TUI status lines, CLI tables). |
|
ui
highlight.go implements syntax highlighting for file previews using glamour.
|
highlight.go implements syntax highlighting for file previews using glamour. |