WinTUI

A terminal user interface for winget (Windows Package Manager), built with Go and the Charmbracelet TUI libraries.

Browse, search, install, upgrade, and manage Windows packages without leaving the terminal. WinTUI features a split-panel workspace, batch operations with a single UAC prompt, and a headless CLI mode for scripting.

Install

Requirements: Windows 10/11 with winget installed.

winget install kts982.WinTUI

Or install manually:

# Run a release binary
.\wintui.exe

# Or build/install with Go 1.26+
go install github.com/kts982/wintui@latest

# Or clone and build from source
git clone https://github.com/kts982/wintui.git
cd wintui
go build -o wintui.exe .

Pre-built binaries are available on GitHub Releases — both .exe and .zip for Windows amd64 and arm64:

gh release download --repo kts982/wintui --pattern '*windows_amd64.exe'

Features

Unified Packages Screen

Split-panel layout — package list on the left, detail summary on the right
Bordered sections — Updates Available, Installed, Search Results, and Install Queue with package counts and active focus highlighting
Normalized package actions — press Space to stage the focused package, g to apply staged changes, or use i / u / x for direct install, upgrade, and uninstall accelerators
Search & Install — press s to search the winget catalog, Space to queue packages, i to install the focused result or the full install queue
Upgrade / Uninstall — stage packages across sections, then apply them together, or use u / x on the focused package or current selection
Export / Import — press e to drop the installed package list as a dated JSON on your Desktop, or Shift+I to open the import overlay (scans Desktop / home / cwd for export files, lets you toggle which entries to install). The same flow is also headless via wintui export and wintui import
Package Details — press Enter or → for a full detail overlay with version picker (v), homepage (o), release notes (n when available), Auto/Ask/Hold package policy, a live command preview showing exactly what winget will run (including per-package overrides), and scrollable metadata
Batch Execution Modal — review selected packages, press ? to preview the exact winget command for each one, watch live progress with per-package spinners and the most recent winget output line, view compact results with Ctrl+E retry (elevated when needed, plain retry for process-in-use failures)
Version Selection — pick a specific version to install or upgrade to from the detail panel
Self-upgrade handoff — WinTUI can check for its own winget update before launch and close so an inline PowerShell handoff can run winget upgrade kts982.WinTUI after the current process exits, without dropping a script or helper executable
Headless CLI — wintui check, wintui list [query] (filter installed packages by name/id, like winget list), wintui show <id>, wintui upgrade --all, wintui upgrade --auto, wintui upgrade --id <pkg>, wintui upgrade --self, wintui notes <id>, wintui theme, wintui config (list/get/set/unset any global setting), wintui rules (list/show/set/clear per-package rules), wintui cleanup scan (read-only cleanup status), wintui doctor (verdict-first readiness check), wintui history (a log of WinTUI-originated upgrades), and wintui fix --portable (pin portable packages to user scope) for scripts, Task Scheduler, or CI without launching the TUI; --json works on check, list, show, doctor, notes, history, fix --portable, config, rules, and cleanup scan. WinTUI is also the human audit surface for agent-driven installs: whatever an AI agent installs or updates through winget (including the WinGet MCP server upgrade tools) shows up in wintui check, wintui list, and the Packages tab under the same policy, holds, and history. Help, usage, errors, and --version are styled with fang to match your theme, with shell completions via wintui completion <shell> (package IDs complete from the cache on upgrade --id and show, and from history on history)
wintui notes <id> — render a package's latest-version release notes (themed markdown via a small built-in renderer) when the winget manifest provides them, with a URL fallback otherwise; wintui check --notes renders the notes for every pending update inline, so you can review what you're about to install before upgrading
wintui theme [name] [--list] — show, list, or set the color theme from the CLI (also surfaced as an INFO row in wintui doctor)
wintui config list|get|set|unset — the CLI control plane for the global settings the TUI's Settings tab edits: the same 16 keys from one registry, human-readable values (install_mode silent, source all, auto_elevate off, cleanup_min_age 3d), strict validation (a typo is an error, never silently normalized), unset restores the real default, and every write is a delta over settings.json so a running TUI keeps its unrelated keys; --json returns self-describing objects
wintui rules list|show|set|clear — per-package rules from the CLI: rules show <id> prints the explicit rule next to the effective value for every field (policy, hold, scope, architecture, elevation) so inheritance is visible; rules set <id> --policy auto --scope user --ignore-version 155.0 --elevate never changes only the fields you pass in one write (a version hold is never silently turned into a permanent one); rules clear <id> [field…]; case-insensitive IDs, strict validation, --json with an explicit hold union (none / all / version)
wintui cleanup scan — the read-only half of the Cleanup tab from the CLI: measures what every registered target would reclaim (TARGET / GROUP / ENABLED / SIZE / ITEMS / KEPT / ADMIN / STATUS), --enabled for the set that starts checked in the TUI, --target <id> to pick targets; admin-only targets are reported as needs_admin rather than walked unelevated (a partial walk would lie), a walk that skipped unreadable entries is marked partial with a lower-bound size, and a Core Temp target whose entries are all newer than the age floor is recent with the KEPT column saying what was left alone — never a bare 0 B that contradicts Explorer. Never deletes and never elevates — deletion stays in the TUI where each removal is confirmed; --json for scripts
wintui upgrade --self — upgrade WinTUI itself from the CLI via the startup self-update handoff (the other upgrade modes deliberately skip the running binary), so CLI-only users stay current without launching the TUI
wintui history [id] — a log of the install/upgrade/uninstall operations WinTUI itself runs (TUI batches and headless upgrade / import), newest first, so scheduled CLI upgrades leave a trace; pass an id for that package's timeline. --limit / --since / --failed-only / --json, and exit 1 when a selector matches nothing (a "did WinTUI touch this?" predicate). Records WinTUI-originated actions only — winget has no event feed for external winget / Store changes. Stored at %APPDATA%\wintui\history.json
wintui fix --portable — pins portable winget packages (CLIs like claude, gum, ffmpeg) to user scope so a future winget upgrade can't strip them from PATH (winget-cli #4044/#5099); writes a per-package scope: user + elevate: false override, idempotent, with --dry-run to preview. wintui upgrade also nudges toward it when an at-risk portable package is about to upgrade

System Utilities

Health Tab — slim WinTUI / winget readiness panel: WinTUI version + path, winget version, source freshness, cached upgrade counts (visible / auto / held + cache age), privileges + Auto Elevate context, system drive free space, and a neutral Settings summary line. Loads instantly — no fresh winget calls or disk scans
wintui doctor — verdict-first headless health (OK / WARN: N issues / FAIL: N issues, exit 0/1/2). --verbose adds the per-row table; --full re-adds verbose system diagnostics (RAM, Defender, drives, ping, Windows PowerShell); --dev-tools appends a developer-tools detection group; --json emits structured output for scripts
Toast notifications — opt-in (off by default). When enabled, fires a single Windows toast on TUI batch finish, on wintui upgrade --auto/--all finish, and when wintui check finds updates. AUMID-attributed as "WinTUI" via a one-time Start Menu shortcut drop on first toast
History Tab — browse the action-history log inside the TUI: newest-first batch list with a detail pane, per-batch drill-down showing each package's record and cross-batch timeline, failed-only filter (f), and reload on r. Read-only over the same %APPDATA%\wintui\history.json the CLI writes, so batches from concurrent wintui upgrade runs appear on tab switch
Cleanup tab — registry-driven multi-target cleanup with grouped panels (Core Temp, Caches, Developer caches, GPU shader caches, WinTUI self-update scratch), per-target sizing, age-aware scrubbing (Core Temp targets only remove entries older than the cleanup_min_age floor — 1d by default, off / 3d / 7d from Settings or wintui config; what the floor kept is shown next to the size, never hidden behind a bare "0 B"), and an elevated helper for admin-only paths (%WINDIR%\Temp, system minidumps). Configurable auto-scan policy (safe / all / off); developer caches default to off and opt-in toggles persist across sessions. Includes an opt-in, default-unchecked "WinTUI action history" target — a privacy reset that clears the log the History tab renders
Settings — persistent config for winget options (scope, architecture, silent/interactive, force, purge, etc.)

UX

Disk-persistent cache — instant startup from cached data, background refresh for always-fresh results, per-package incremental updates after actions
Update count badge in the tab bar — see available updates at a glance before winget finishes refreshing
5-tab layout: Packages, Cleanup, Health, History, Settings
Boxed tab bar with animated gradient ASCII logo
Context-sensitive help bar that adapts to the active section
Full help panel on ? with grouped keybindings
Fuzzy filter (/) on the installed package list
Per-tab screen state preserved across tab switches
Built-in elevated helper — silent + auto-elevate runs everything elevated upfront, avoiding UAC popups from installers
Ctrl+E elevated retry on the result modal when auto-elevate is off
Responsive layout — detail panel hides on narrow terminals, compact header on small screens

Themes

Eight curated palettes ship in the box. Each one has matching Dark and Light variants — WinTUI detects your terminal background at startup and picks the right one, so themes read correctly on both without any configuration.

Open Settings (tab 5), arrow down to Color Theme, then use ← / → (or Space) to cycle. Changes apply live.

Theme gallery — click to expand all eight stills


Sweet Pink — the default	WinTUI Midnight
Catppuccin	Nord
Dracula	Tokyo Night
Ember	Monochrome

See the theme gallery for full-size screenshots and notes on each palette, including the opt-in Theme Background setting that tints your terminal background via OSC 11.

Usage

.\wintui.exe

Tip: Some operations require administrator privileges. The subtitle bar shows ● admin / ● user status. Enable Silent mode + Auto Elevate in Settings for hands-off elevated operations, or press Ctrl+E on the result modal when a package fails. WinTUI's own update is handled by closing WinTUI and letting winget replace the released binary; after the handoff finishes, start wintui again manually.

Headless CLI

# Human-readable upgrade check (honors per-package update policy)
wintui check

# Exit code 1 when visible updates are available
wintui check ; if ($LASTEXITCODE -eq 1) { "Updates available" }

# Machine-readable output
wintui check --json
wintui list --json > packages.json

# Filter installed packages by name/id — "is Firefox installed?" (exit 1 if not)
wintui list firefox

# Inspect what WinTUI would pass to winget for a given package
wintui show Mozilla.Firefox --json

# Upgrade everything that is not held
wintui upgrade --all

# Upgrade only packages marked Auto
wintui upgrade --auto

# Upgrade specific packages by ID (repeatable; pipe-friendly)
wintui upgrade --id Mozilla.Firefox --id Microsoft.VisualStudioCode

# Upgrade WinTUI itself (the modes above skip the running binary)
wintui upgrade --self

# Read release notes — one package, or every pending update before upgrading
wintui notes Git.Git
wintui check --notes

# Show/set the color theme
wintui theme --list
wintui theme nord

# Change a setting from the CLI (validated; unset restores the default)
wintui config set install_mode silent
wintui config unset source

# Per-package rules: see what applies and why, then change one field
wintui rules show Git.Git
wintui rules set Git.Git --policy auto --scope user

# How much junk has piled up? (read-only; deleting stays in the TUI)
wintui cleanup scan

# Review what WinTUI has upgraded (scheduled runs leave a trace now)
wintui history
wintui history Mozilla.Firefox          # one package's timeline

# Pin portable packages to user scope so a future upgrade can't drop them from PATH
wintui fix --portable --dry-run
wintui fix --portable

# Export and re-import package lists across machines
wintui export --output packages.json
wintui import packages.json --dry-run     # preview before installing
wintui import packages.json               # install the safe subset

# Enable Tab completion (this session); add to $PROFILE to make it permanent
wintui completion powershell | Out-String | Invoke-Expression

Completion isn't automatic — PowerShell can't introspect an external .exe, so the completer must be registered once (in your $PROFILE to persist). See docs/cli.md → Enabling shell completions for the persistent / cached setup and the MenuComplete tip.

The old root flags --check and --list have been removed; use wintui check and wintui list. --all / --auto / --id deliberately skip the running WinTUI binary; use wintui upgrade --self to update WinTUI itself from the CLI (it runs the same startup handoff and ignores the Auto Update setting since you asked for it explicitly).

Further documentation:

Keyboard Shortcuts

Packages Screen

Key	Action
`↑↓` / `j/k`	Navigate
`PgUp` / `PgDn`	Jump 10 rows up / down
`Home` / `End`	Jump to top / bottom of the cursor's section
`Space`	Stage package / queue search result
`Enter` / `→` / `l`	Open package details
`←` / `Esc` / `h`	Close details / cancel
`Esc`	Dismiss search results / close details
`s`	Search & install (search winget catalog)
`/`	Filter installed packages
`g`	Apply staged changes
`u`	Upgrade selected or focused package
`x`	Uninstall selected or focused package
`t`	Cycle focused winget/msstore package update policy: Ask → Auto → Hold
`i`	Install queued packages or focused search result
`a`	Stage all available updates
`v`	Pick version (in detail view)
`c`	Reset to latest version (in detail view)
`o`	Open homepage (in detail view)
`n`	Open release notes URL (in detail view, when available)
`p`	Open per-package rules editor (detail view or list)
`i`	Toggle ignore on the focused package (in detail view)
`?`	Expand winget command preview for each item (in batch confirm modal)
`r`	Refresh package data
`Ctrl+E`	Retry failed packages (result modal) — elevated retry for permission failures, plain retry for items blocked by a running process
`?`	Toggle full help panel

Global

Key	Action
`1-5`	Switch tabs
`Tab` / `Shift+Tab`	Cycle tabs
`q`	Quit

Settings

Configurable from the Settings tab or from the CLI with wintui config (same keys, validated values, see docs/cli.md → config), stored in %APPDATA%\wintui\settings.json. On the Settings tab, s saves and R (Shift+R) resets these settings to their defaults; per-package rules and cleanup opt-ins are kept:

Setting	Options
Install Scope	user / machine / auto
Action Mode	auto / silent / interactive
Architecture	x64 / x86 / arm64 / auto
Default Source	winget / msstore / auto
Force	skip non-security issues
Allow Reboot	permit reboots during install
Skip Dependencies	don't process dependencies
Purge on Uninstall	delete all package files
Include Unknown Versions	show packages with unknown versions
Auto Elevate	automatically request admin rights
WinTUI Auto Update	check for and apply WinTUI's own update before launch
Toast Notifications	Windows toast on TUI batch finish, scheduled `wintui upgrade --auto/--all`, and `wintui check` finding updates (off by default)
Color Theme	Sweet Pink, WinTUI Midnight, Catppuccin, Nord, Dracula, Tokyo Night, Ember, or Monochrome
Theme Background	terminal / theme background tinting
Cleanup Auto Scan	safe / all / off — what the Cleanup tab measures when opened
Cleanup Min Age	off / 1d / 3d / 7d — the Core Temp cleanup targets only remove entries older than this (1d by default; 7d was the pre-v2.12 rule)

Action Mode: Silent + Auto Elevate runs all install/upgrade/uninstall operations through the elevated helper upfront, avoiding UAC popups from installers that elevate themselves.

Auto Elevate (without silent mode) retries automatically on hard permission errors. When a batch finishes with failures, the result modal offers Ctrl+E to retry only the failed elevation-candidate packages.

Theme Background defaults to terminal, which leaves your terminal's own background untouched. Set it to theme if you want WinTUI to request the active palette's background color; support varies by terminal, so unsupported terminals simply keep their existing background.

Per-Package Rules

Any of the settings above can be overridden for a specific package, and winget/msstore-managed packages can be marked Ask, Auto, or Hold for updates. Press t from the package list to cycle the focused package through Ask → Auto → Hold, or open a package's detail view and press p for the full rules editor. From the CLI, wintui rules show <id> prints the explicit rule next to the effective value and wintui rules set <id> --policy auto --scope user changes only the fields you pass; package IDs are case-insensitive.

Supported rules: update_policy, scope, architecture, elevate, ignore, ignore_version. Auto and Hold packages show [AUTO] / [HOLD] badges in the package list. Held packages are omitted from normal upgrade actions with an (N held) count on the section header.

For the full rule reference and behavior details, see Per-package rules.

For deeper behavior details and examples, see:

Development

# Run the full validation suite
.\scripts\check.ps1 -Mode full

# Optional: enable git hooks
git config core.hooksPath .githooks

The validation suite runs gofmt, go test, go vet, staticcheck, and go build.

Optional Git hooks are included in .githooks/pre-commit and .githooks/pre-push.

Maintainers can regenerate demo.gif from demo.cast with agg.

Built With

Bubble Tea — TUI framework
Bubbles — TUI components
Lip Gloss — Terminal styling
Harmonica — Spring-physics animations

License

MIT

Name		Name	Last commit message	Last commit date
.githooks		.githooks
.github		.github
docs		docs
packaging/winget		packaging/winget
scripts		scripts
testdata/winget		testdata/winget
winres		winres
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yaml		.goreleaser.yaml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
admin_windows.go		admin_windows.go
app.go		app.go
app_test.go		app_test.go
atomicfile.go		atomicfile.go
batch_status.go		batch_status.go
cache.go		cache.go
cleanup.go		cleanup.go
cleanup_engine.go		cleanup_engine.go
cleanup_engine_test.go		cleanup_engine_test.go
cleanup_min_age_test.go		cleanup_min_age_test.go
cleanup_targets.go		cleanup_targets.go
cleanup_targets_test.go		cleanup_targets_test.go
cleanup_test.go		cleanup_test.go
cleanup_wire.go		cleanup_wire.go
cleanup_wire_test.go		cleanup_wire_test.go
cli.go		cli.go
cli_cleanup.go		cli_cleanup.go
cli_cleanup_test.go		cli_cleanup_test.go
cli_color.go		cli_color.go
cli_color_test.go		cli_color_test.go
cli_completion.go		cli_completion.go
cli_completion_test.go		cli_completion_test.go
cli_config.go		cli_config.go
cli_config_test.go		cli_config_test.go
cli_export.go		cli_export.go
cli_fang.go		cli_fang.go
cli_fix.go		cli_fix.go
cli_fix_test.go		cli_fix_test.go
cli_heartbeat_test.go		cli_heartbeat_test.go
cli_history.go		cli_history.go
cli_history_test.go		cli_history_test.go
cli_list_test.go		cli_list_test.go
cli_markdown.go		cli_markdown.go
cli_notes.go		cli_notes.go
cli_notes_test.go		cli_notes_test.go
cli_rules.go		cli_rules.go
cli_rules_test.go		cli_rules_test.go
cli_test.go		cli_test.go
cli_theme.go		cli_theme.go
cli_theme_test.go		cli_theme_test.go
cli_upgrade_self_windows_test.go		cli_upgrade_self_windows_test.go
cli_upgrade_test.go		cli_upgrade_test.go
config.go		config.go
config_race_test.go		config_race_test.go
config_test.go		config_test.go
config_twowriter_test.go		config_twowriter_test.go
demo.gif		demo.gif
detail.go		detail.go
detail_test.go		detail_test.go
doctor_test.go		doctor_test.go
elevate_windows.go		elevate_windows.go
elevation.go		elevation.go
elevation_test.go		elevation_test.go
exec_modal.go		exec_modal.go
exec_paths_windows.go		exec_paths_windows.go
exec_paths_windows_test.go		exec_paths_windows_test.go
execution.go		execution.go
execution_test.go		execution_test.go
filter.go		filter.go
genlocales.go		genlocales.go
go.mod		go.mod
go.sum		go.sum
healthcheck.go		healthcheck.go
healthcheck_mcp_test.go		healthcheck_mcp_test.go
helper.go		helper.go
helper_test.go		helper_test.go
history.go		history.go
history_build_test.go		history_build_test.go
history_tab.go		history_tab.go
history_tab_test.go		history_tab_test.go
history_test.go		history_test.go
history_writepoint_test.go		history_writepoint_test.go
identity.go		identity.go
identity_test.go		identity_test.go
import.go		import.go
import_test.go		import_test.go
keys.go		keys.go
layout.go		layout.go
layout_test.go		layout_test.go
main.go		main.go
mouse_wheel_test.go		mouse_wheel_test.go
override_keys.go		override_keys.go
override_keys_test.go		override_keys_test.go
planner.go		planner.go
planner_test.go		planner_test.go
powershell_inline_windows.go		powershell_inline_windows.go

Navigation Menu

Repository navigation

About

Repository files navigation

WinTUI

Install

Features

Themes

Usage

Headless CLI

Keyboard Shortcuts

Packages Screen

Global

Settings

Per-Package Rules

Development

Built With

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

WinTUI

Install

Features

Themes

Usage

Headless CLI

Keyboard Shortcuts

Packages Screen

Global

Settings

Per-Package Rules

Development

Built With

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages