Skip to main content

configuration

bluefin-cli stores its settings in a YAML config file and reads a small set of environment variables. This page documents both.

Config file​

The config file lives at ~/.config/bluefin-cli/config.yaml; Viper manages it. You normally never edit it by hand — commands like bluefin-cli theme <flavor> and the TUI's settings screen call viper.Set and persist the file for you. The file is plain YAML if you want to inspect or script against it.

Location​

bluefin-cli resolves the config directory in this order (internal/env.GetConfigDir):

  1. ~/.config/bluefin-cli if that directory already exists.
  2. $HOMEBREW_PREFIX/etc/bluefin-cli if the HOMEBREW_PREFIX environment variable is set.
  3. ~/.config/bluefin-cli otherwise (created on first write).

For steps on each platform, see the setup guides for Linux, macOS, and Windows.

Keys​

KeyDefaultSet by
themecatppuccinReserved default; the active flavor is tracked under ui.flavor below.
ui.flavorautobluefin-cli theme <flavor>, or the Settings screen in the TUI menu. auto follows your terminal's reported scheme.
ui.dark_modetrueThe Settings screen in the TUI menu.
bundles.base_urlhttps://raw.githubusercontent.com/projectbluefin/common/main/system_filesNot currently exposed as a command flag; override via config file or environment variable (see below) if you need a different source for downloaded (non-embedded) bundles.
bundles.default_pathshared/usr/share/ublue-os/homebrewSame as above.
game.high_score0The hidden dino game in the TUI header.
update.last_checkunsetbluefin-cli menu, to throttle the update check to once per 24h.
profile.gist_idunsetbluefin-cli profile sync, to remember which GitHub Gist a profile is synced to.

Example​

theme: catppuccin
ui:
flavor: mocha
dark_mode: true
game:
high_score: 1337

Environment variables​

BLUEFIN_* config overrides​

The config sets up Viper with SetEnvPrefix("BLUEFIN") and AutomaticEnv() (internal/config/config.go), so an environment variable can override any key in the table above. Uppercase the key and replace . with _. An environment variable always wins over the config file.

VariableOverrides
BLUEFIN_UI_FLAVORui.flavor
BLUEFIN_UI_DARK_MODEui.dark_mode
BLUEFIN_THEMEtheme
BLUEFIN_BUNDLES_BASE_URLbundles.base_url
BLUEFIN_BUNDLES_DEFAULT_PATHbundles.default_path

This mechanism is generic — it is not a hardcoded list of os.Getenv calls; Viper reads any BLUEFIN_<KEY> variable that exists at process start.

Other environment variables​

These are read directly in Go code and are not part of the Viper config:

VariableEffect
HOMEBREW_PREFIXWhen set, bluefin-cli adds $HOMEBREW_PREFIX/etc/bluefin-cli as a config search path and prefers it as the config directory if ~/.config/bluefin-cli does not exist. Also consulted when locating brew itself.
BLUEFIN_DISABLE_COUNTMESet to any non-empty value to opt out of the anonymous countme usage ping (internal/countme/countme.go).
WSL_DISTRO_NAME, WSL_INTEROPUsed (alongside /proc markers) to detect WSL; affects Windows-specific install paths.
LOCALAPPDATAUsed on Windows to locate per-user app data for terminal/font registration.
SHELLYour login shell. Marks the default shell in bluefin-cli status and selects the shell for the shell-integration menu and profiles. status, doctor and doctor --fix act on the shell you are running (the parent process), falling back to SHELL when that cannot be determined.
XDG_CURRENT_DESKTOPConsulted by the installer to tailor desktop-specific install steps on Linux.

XDG Base Directory support​

bluefin-cli does not yet give full support for the XDG base-directory specification (XDG_CONFIG_HOME, XDG_DATA_HOME, etc.). The code hardcodes the config directory to ~/.config/bluefin-cli (or the Homebrew prefix path above), independent of XDG_CONFIG_HOME.

User-defined bundles​

Bundles are Homebrew Brewfiles. Curated bundles ship embedded in the binary, but you can add your own:

mkdir -p ~/.config/bluefin-cli/bundles
cat > ~/.config/bluefin-cli/bundles/my-tools.Brewfile <<'EOF'
brew "ripgrep"
brew "fd"
EOF

bluefin-cli install my-tools

bluefin-cli picks up any *.Brewfile in that directory automatically (internal/install/install.go) and lists it alongside the curated bundles (ai, cli, cncf, experimental-ide, fonts, full-desktop, ide, k8s, all) when you run bluefin-cli install list or the TUI's Install Apps menu. User-defined bundles extend the curated set — they do not shadow or replace any of it.

For Brewfile syntax, Windows entries, and examples, refer to the Brewfile guide.