How thesubh213/winitrix works
Winitrix is a Go-based, Windows-first CLI that coordinates updates across many package-manager ecosystems from one entry point. The binary entrypoint is main.go, and the command surface is built under cmd/ with Cobra-style subcommands and flags.
The top-level boundary is the CLI layer:
• winitrix runs the main update workflow.
• doctor, clean, stats, logs, config, schedule, install, and version are separate operational commands.
• Flags such as --silent, --json, --dry-run, --only, --exclude, and retry/timeouts alter the same core orchestration path rather than launching separate subsystems.
The core update flow lives behind cmd/root.go and is designed to branch into two execution modes:
• a TUI mode for interactive progress and user choice
• a silent/headless mode for non-interactive execution
Both modes use the same underlying ecosystem discovery and command execution logic, so the UI is a presentation layer, not the source of orchestration.
The main plugin boundary is pkg/ecosystem/. This package defines the package-manager abstraction and contains adapters for 21 ecosystems: Windows-native tools, Node.js, Python, Rust, DevOps tools, and developer utilities. Each adapter wraps a native CLI manager such as Winget, Scoop, Chocolatey, npm, pnpm, Yarn, Bun, Pip, Pipx, uv, Poetry, Conda, Cargo, Rustup, Docker, Terraform, Helm, Go tools, .NET tools, VS Code extensions, and WSL/Apt.
That ecosystem layer is responsible for detection, filtering, and execution semantics per manager. The manager.go interface is the key architectural seam: higher-level code can treat each ecosystem uniformly while individual adapters encapsulate manager-specific commands, capabilities, and failure modes.
Interactive progress is handled by pkg/tui/, which is a Bubble Tea state machine with styling via Lip Gloss. The TUI consumes orchestration events, renders progress and status, and lets the user observe or influence the update process without directly owning the update logic.
Several cross-cutting services sit between orchestration and the OS:
• pkg/runner/ executes subprocesses and abstracts command invocation
• pkg/elevation/ handles UAC/admin privilege escalation on Windows
• pkg/translator/ converts raw CLI and OS errors into human-readable guidance
• pkg/retry/ centralizes retry behavior and backoff
These packages form the execution boundary around external manager binaries and Windows privilege requirements.
Stateful behavior is kept local and file-based. pkg/config/ reads and writes TOML configuration, pkg/state/ persists run state, and pkg/report/ captures structured run results, including the JSON output path described in the README. pkg/paths/ centralizes per-user storage locations under AppData/LocalAppData, which is important because the app relies on local disk instead of any backend service.
Observability is also local and offline-first. pkg/logger/ writes debug logs, cmd/logs.go exposes those logs to users, and the logs --bundle path packages diagnostics, config, and state for troubleshooting. This is consistent with the project’s zero-telemetry stance: data flows stay on the machine unless the user explicitly exports them.
Pre-flight health checks are isolated in pkg/doctor/ and exposed through the doctor command. That subsystem focuses on environment readiness such as DNS/network checks and PATH or ecosystem health, so it acts as a diagnostic gate before running the heavier update workflow.
There are also Windows-specific operational integrations outside the main update loop:
• cmd/install_windows.go and cmd/install_auto_stub.go support user-profile installation and PATH setup
• cmd/schedule_windows.go and cmd/schedule_stub.go integrate with Windows Task Scheduler
• pkg/notify/ provides desktop notifications on Windows
These are platform boundaries, with stub files indicating compile-time differences for unsupported or non-Windows builds.
Packaging and release are handled separately from runtime logic. The repo includes a Windows installer script under installer/, plus GitHub Actions workflows for build and release automation. That means the shipped artifacts are a compiled Go binary plus a Windows installer/portable distribution, not a server-deployed application.
For an architecture diagram, the most important flows are: user command → CLI parsing/config loading → ecosystem detection/filtering → runner/elevation execution against external manager CLIs → result aggregation into report/state/logs → optional TUI, JSON output, notifications, or diagnostics. The main boundaries are between CLI orchestration, per-ecosystem adapters, OS-specific services, and local persistence.
Main entry points: root.go winitrix · manager.go manager · model.go tui · doctor.go doctor core
Components 27
CLI
Command surface and top-level orchestration
Core flow
Update orchestration, execution, and result handling
- tui · Interactive progress and control surface
pkg/tui/model.go
Ecosystems
Package-manager abstraction and adapters
- manager · Common package-manager contract
pkg/ecosystem/manager.go - filter · Ecosystem detection and targeting
pkg/ecosystem/filter.go - winget · Windows package manager adapter
pkg/ecosystem/winget.go - npm · Node ecosystem adapter
pkg/ecosystem/npm.go - pip · Python ecosystem adapter
pkg/ecosystem/pip.go - cargo · Rust ecosystem adapter
pkg/ecosystem/cargo.go - docker · DevOps tool adapter
pkg/ecosystem/docker.go - vscode · Developer tool adapter
pkg/ecosystem/vscode.go
Services
Cross-cutting execution and local persistence
- config · Reads and writes user settings
pkg/config/config.go - runner · Subprocess invocation boundary
pkg/runner/runner.go - elevation · Windows privilege escalation
pkg/elevation/elevation.go - translator · Turns raw failures into user-facing guidance
pkg/translator/translator.go - retry · Central retry policy
pkg/retry/retry.go - report · Structured run results and JSON output
pkg/report/report.go - state · Persisted run state
pkg/state/state.go - logger · Local debug logging
pkg/logger/logger.go - doctor core · Network, PATH, and environment diagnostics
pkg/doctor/doctor.go
Windows
Windows-specific operations and integrations
Release
Packaging and CI automation
- installer · Windows installer script
installer/winitrix.iss - release CI · Build and release automation
.github/workflows/release.yml
Connections 28
- main → winitrix: starts · Binary entrypoint hands control to CLI orchestration
- winitrix → config: loads · CLI bootstraps user configuration
- winitrix → filter: selects · Chooses which ecosystems participate in a run
- winitrix → manager: orchestrates · Top-level workflow uses the common manager contract
- manager → winget: implemented by · Representative ecosystem adapters implement the interface
- manager → npm: implemented by · Representative ecosystem adapters implement the interface
- manager → pip: implemented by · Representative ecosystem adapters implement the interface
- manager → cargo: implemented by · Representative ecosystem adapters implement the interface
- manager → docker: implemented by · Representative ecosystem adapters implement the interface
- manager → vscode: implemented by · Representative ecosystem adapters implement the interface
- winitrix → runner: executes · All external manager commands go through the process runner
- winitrix → elevation: elevates · Windows privilege escalation when required
- winitrix → retry: retries · Shared retry and backoff behavior
- winitrix → translator: explains · Converts low-level failures into guidance
- winitrix → report: emits · Aggregates structured results and JSON output
- winitrix → state: persists · Stores run state locally
- winitrix → logger: logs · Writes local debug logs
- winitrix → tui: renders · Interactive mode presents orchestration progress
- winitrix → notify: notifies · Optional Windows desktop notifications
- doctor → doctor core: invokes · Doctor command delegates to diagnostics subsystem
- logs → logger: reads · Log command surfaces local diagnostics
- install → elevation: uses · Installer path may require admin rights
- schedule → notify: integrates · Scheduled runs can surface notifications
- doctor core → runner: probes · Diagnostics may run external checks
- doctor core → translator: maps · Diagnostics turn failures into readable guidance
- tui → report: consumes · UI consumes orchestration progress and results
- tui → filter: observes · Interactive flow reflects selected ecosystems
- installer → release CI: shipped by · Installer is built and published via release automation