Skip to main content

troubleshooting

Start with doctor​

bluefin-cli doctor

This runs six checks (cmd/doctor.go) and prints ✓ (pass), ! (warning — not fatal), or ✗ (failure) for each:

CheckWhat it verifiesTypical fix
Package managerbrew on PATH (or coldbrew/apk on Alpine/musl systems)See Homebrew not found below
Shell integrationThe shell experience is enabled for your current shellbluefin-cli shell <shell> on
Managed toolseza, fzf, starship are installedInstall via the TUI's Shell Experience menu
GitHub reachablehttps://api.github.com responds to a HEAD requestCheck network/proxy/firewall; required for updates and bundle downloads
Self-update viableThe install directory is writable (direct installs only; skipped for package-manager installs)Fix directory permissions, or install via a package manager instead
VersionCompares your version against the latest GitHub releasebluefin-cli update, or your package manager's upgrade command

Two useful flags:

bluefin-cli doctor --fix # applies safe automatic fixes (shell integration, missing tools)
bluefin-cli doctor --bench # measures shell startup cost vs. a bare shell (bash/zsh/fish only)

--fix handles three cases. It enables shell integration, sets up coldbrew on Alpine/musl systems, and installs eza, fzf, and starship when they are missing. It does not fix network or Homebrew PATH issues; use the manual steps above.

Common issues​

Homebrew is installed but not found​

doctor checks common install locations (/opt/homebrew/bin/brew, /usr/local/bin/brew, /home/linuxbrew/.linuxbrew/bin/brew) and tells you to run:

eval "$(/opt/homebrew/bin/brew shellenv)" # adjust path to match your system

Add that line to your shell's rc file to make it permanent, or re-run bluefin-cli shell <shell> on to let bluefin-cli manage it.

No package manager on Alpine / postmarketOS​

Homebrew's Ruby bootstrap does not run on musl libc, so bluefin-cli uses coldbrew instead on Alpine-based systems. If doctor reports coldbrew is "not set up yet", run:

bluefin-cli doctor --fix

This installs coldbrew rootless and sandboxed. Until it's set up, package installs fall back to sudo apk add one package at a time.

Shell integration isn't picking up changes​

  • Nushell cannot evaluate a string, so bluefin-cli shell nu on writes the init script to ~/.config/nushell/bluefin-cli.nu and config.nu reads it from there. If you change your tool configuration, re-run bluefin-cli shell nu on to regenerate that file. Do not edit it directly, because a re-run writes over your changes.
  • ash (busybox, used on Alpine) has no rc-file convention. bluefin-cli writes ~/.ashrc and exports ENV from ~/.profile so ash picks it up. atuin, starship, and carapace have no ash target, so bluefin-cli skips them there.
  • PowerShell: by default, PowerShell scopes a function inside another function to the parent. The generated script marks each user-facing function global:. If the shell acts in a strange way after a manual edit, check that each function keeps the global: prefix.

Windows: install.ps1 fails with an execution-policy error​

By default, the execution policy of PowerShell blocks a script that you downloaded. Run PowerShell as yourself (not elevated) and either bypass for the single command:

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.ps1 | iex"

or set a less restrictive policy for your user account (see Microsoft's Set-ExecutionPolicy documentation for the tradeoffs before you change this system-wide).

Wallpaper or theme install fails on Windows/WSL​

Wallpaper and Windows-theme registration use LOCALAPPDATA and WSL-specific detection (WSL_DISTRO_NAME, WSL_INTEROP, and /proc markers — see internal/env/env.go). Detection can be wrong — for example, in a container whose /proc content resembles WSL. In that case, installs that depend on the Windows filesystem fail or silently no-op. Run bluefin-cli doctor first. A failed package-manager or network check often explains a downstream wallpaper or theme error. The wallpaper code itself is usually not at fault.

Bundle install fails to download​

Curated bundles ship embedded in the binary and are used first. If a bundle isn't embedded (or you're on an older build), bluefin-cli falls back to a download from bundles.base_url (see Configuration). If that fails:

  • Check bluefin-cli doctor's "GitHub reachable" result — the default base URL is a raw.githubusercontent.com URL and needs the same network access.
  • If you're behind a mirror or air-gapped network, point BLUEFIN_BUNDLES_BASE_URL and BLUEFIN_BUNDLES_DEFAULT_PATH at your own mirror (see Configuration).

go test ./... passes locally but CI's containerized suite fails (or vice versa)​

go test ./... and just test are not the same suite. just test builds a Podman container and runs go test ./test/... inside it — a narrower, integration-focused path that assumes a Linux container environment. If one passes and the other does not, the cause is usually a host-specific assumption. A common case: a tool on your PATH that is not in the container, or vice versa. Run both before you open a PR; see the contributor guide.

Still stuck?​

Search existing issues — many platform quirks (especially Windows/WSL edge cases) are already tracked there with workarounds. The setup guides also show platform limits:

If you don't find a match, open a new issue with your bluefin-cli doctor output and the command that failed.