govmr
Blazingly fast, asynchronous Go version manager with a rich Terminal UI.
Features • Installation • Quick Setup • Usage • Architecture
Demo
Features
- Non-Blocking Async Engine: Powered by Tokio and Ratatui. Fetching releases, streaming downloads, and decompressing archives happen entirely on background threads without locking the UI.
- Cancellable Background Operations: Abort in-flight downloads and archive extractions instantly by pressing
corEscwithout leaving orphaned files behind. - Transparent Shim Dispatch: Zero environment pollution. Switches toolchains in place via
~/.govmr/shimwithout spawning subshells or requiring terminal reloads. - Dual Engine: Use the interactive TUI for visual tracking, or invoke the script-friendly CLI for headless automation and CI/CD pipelines.
- Intelligent Version Matching: Automatically resolves prefixes (e.g.,
1.22resolves to the latest stable release of1.22.x). - Rich Customization: 19 built-in color themes across Dark/Light families, browsable via a live-preview TUI picker.
- Docked Operation Log: IDE-style log panel (
Lto toggle) with live tailing, focus-based scrolling, and 1MiB rotation for post-mortem debugging. - Cross-Platform Parity: First-class support for Linux, macOS, and Windows.
Installation
Install Script
Linux & macOS
|
To install a specific version:
|
Windows (PowerShell)
irm https://raw.githubusercontent.com/seyallius/govmr/v1.0.0/install.ps1 | iex
To install a specific version:
iex "& { $( irm https://raw.githubusercontent.com/seyallius/govmr/v1.0.0/install.ps1 ) } -Version v1.0.0"
Cargo Binstall (Fastest if you have cargo installed)
If you have cargo-binstall installed, fetch and install pre-compiled binaries directly:
Cargo (Build from Source)
GitHub Releases
Download signed, pre-built binary archives for your architecture directly from
the GitHub Releases page and extract govmr into your system
$PATH.
🪄 Automatic Shell Completions
Zero configuration required. On its very first run, govmr automatically generates and installs shell completion
scripts for:
- Bash (
~/.local/share/bash-completion/completions/govmr) - Zsh (
~/.local/share/zsh/site-functions/_govmr) - Fish (
~/.config/fish/completions/govmr.fish) - PowerShell (
~/.config/powershell/govmr.ps1on Unix,~/Documents/PowerShell/govmr.ps1on Windows)
✨ How It Works
- First run →
govmrdetects your active shell via$SHELL - Generates → Writes the completion script to
~/.govmr/completions/ - Symlinks → Creates a symlink to your shell's standard discovery directory
- Updates intelligently → Content-aware staleness detection rewrites the script only when the CLI changes (new commands, flags, themes)
🧠 Smart Features
- Content-aware regeneration: Not just timestamp-based — compares the actual script content byte-for-byte. Add a new subcommand? The script gets updated automatically.
- Single source of truth: All completion scripts live in
~/.govmr/completions/as canonical files, with symlinks pointing to shell discovery directories. No scattered files across your system. - Clean uninstall: Running
govmr uninstallremoves every completion symlink and~/.govmr/completions/— no orphaned files left behind.
🔄 Reloading Completions
After govmr updates its completion script (e.g., after a self-update or adding new commands), open a new terminal
window or source the script manually:
# Bash
# Zsh
# Fish
# PowerShell
💡 Tip: Opening a new terminal tab/window is usually the easiest way to reload completions — your shell automatically scans its discovery directories on startup.
🧪 Test It!
# Command completions
# → install use delete list theme update uninstall help
# Argument completions (themes)
# → gocyan newisland cursordark midnight tokyonight mocha ...
PATH Setup
govmr uses a centralized shim directory (~/.govmr/shim). Add this directory to your $PATH once to allow shims
(go, gofmt) to intercept and dispatch calls to the active Go runtime.
🪄 The Easy Way (TUI Auto-Fix)
You usually don't need to configure this manually.
Just launch the TUI by running govmr. If the shim directory is missing from your PATH, an interactive setup overlay
will appear automatically. Simply press f, and GoVMR will safely and idempotently apply the correct PATH fix for
your OS:
- Windows: Updates the persistent User PATH via PowerShell in a hidden window.
- Linux/macOS: Appends the export line to your shell profile (
~/.zshrc,~/.bashrc, or~/.config/fish/config.fish) with an idempotency guard.
🛠️ The Manual Way (Headless / CI)
If you are running headless or prefer manual configuration, use the commands below:
Linux / macOS
Add the shim directory to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish):
# Bash / Zsh
# Fish
fish_add_path $HOME/.govmr/shim
Reload your current session:
Windows
PowerShell (Recommended)
Set the persistent User environment variable without truncating system strings:
$shimDir = "$HOME\.govmr\shim"
$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($currentPath -notlike "*$shimDir*")
{
[Environment]::SetEnvironmentVariable("Path", "$shimDir;$currentPath", "User")
$env:Path = "$shimDir;" + $env:Path
}
Command Prompt (Legacy)
⚠️ Warning:
setxtruncates the PATH variable to 1024 characters. If your PATH is long, this can silently corrupt it. We strongly recommend using the PowerShell method above or the TUI'sfkey.
setx PATH "%USERPROFILE%\.govmr\shim;%PATH%"
Terminal User Interface (TUI)
Launch the interactive interface with:
Keybindings & Navigation
| Keybinding | Action |
|---|---|
Tab |
Switch between Available Versions and Installed Versions tabs |
↑ / k, ↓ / j |
Navigate through list rows |
i |
Download and install the selected version |
u |
Activate/Switch to the selected version |
d |
Delete the selected version (prompts confirmation modal; cannot delete active version) |
c / Esc |
Cancel an ongoing background download or extraction |
r |
Refresh the remote version index from go.dev |
T |
Open the color theme picker |
L |
Toggle the docked operation log panel |
f |
Apply permanent PATH fix (when PATH setup overlay is active) |
q / Ctrl+C |
Gracefully quit govmr |
j/k, ↑/↓, PgUp/PgDn (help open) |
Scroll the keyboard help panel |
h |
PATH setup overlay — only while the shim is missing; inert once configured |
? |
Toggle the keyboard reference panel (dims the dashboard) |
U |
Self-update govmr (confirmation prompt) |
X |
Self-uninstall govmr (confirmation prompt, then optional purge prompt) |
CLI Documentation
govmr includes a complete non-interactive command-line interface for terminal workflows, scripts, and CI runners.
Command Overview
govmr [COMMAND]
Commands:
install Download and install a specified Go version
use Switch the active system Go version to an installed release
delete Remove an installed Go version from disk
list List all locally installed Go versions
theme View or change the TUI color theme
help Print this message or the help of the given subcommand(s)
Subcommands
govmr install <VERSION>
Downloads, verifies, extracts, and automatically activates a Go toolchain.
# Install an exact patch version
# Install the latest stable release for a minor release line
govmr use <VERSION>
Updates the global shim pointer in ~/.govmr/shim to the target installation.
# Switch to a specific installed version
# Switch to the highest installed patch of a series
Notes:
- If the requested version is not installed locally,
govmrprints an actionable error asking to install it first. - Re-pointing happens instantly via file shims; existing terminals execute the updated binary without restarting.
govmr list
Lists all locally installed toolchains and marks the active version.
govmr delete <VERSION>
Removes an installed Go toolchain from ~/.govmr/versions.
Notes:
- The CLI deletes immediately without a prompt. Use the TUI (
dkey) if you prefer interactive confirmation. - Safety check: You cannot delete the currently active toolchain. Run
govmr use <OTHER_VERSION>first.
govmr theme [NAME]
Lists available color themes or applies one permanently.
# List all 19 available themes
# Apply and save the Midnight theme
govmr update
Checks GitHub for the latest release and automatically downloads/replaces the current binary.
govmr uninstall
Removes the govmr executable from your system.
# Remove binary only (keeps ~/.govmr and installed Go versions)
# Remove binary AND purge ~/.govmr (deletes all installed Go versions, config, and logs)
How It Works
~/.govmr/shim/
[Terminal Invocation] ───────> [ go / gofmt ]
│
┌───────────────────┴───────────────────┐
▼ ▼
(Unix: POSIX wrapper) (Windows: go.bat)
#!/usr/bin/env bash @echo off
exec "/path/to/active/go" "$@" "%USERPROFILE%\.govmr\versions\...\go.exe" %*
- Isolation: Every Go toolchain resides in its own sandboxed directory under
~/.govmr/versions/go<VERSION>/. - Shim Multiplexing: Rather than modifying shell variables like
GOROOTor prepending different binary paths on every switch,govmrmaintains standard shims (go,gofmt) inside~/.govmr/shim/.
- On Linux and macOS, shims are minimal shell wrappers delegating standard inputs and exit codes.
- On Windows, shims are generated as
go.batandgofmt.batfiles forwarding%*arguments to the target binary.
- Download Cleanup: Partial downloads are kept in
~/.govmr/downloads/and verified with magic-byte sniffing. Failed or canceled transfers clean up temporary files automatically to prevent disk bloat.
Development
# Clone the repository
# Run tests
# Check documentation validity
# Build optimized release binary
License
This project is licensed under the MIT License