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):
~/.config/bluefin-cliif that directory already exists.$HOMEBREW_PREFIX/etc/bluefin-cliif theHOMEBREW_PREFIXenvironment variable is set.~/.config/bluefin-cliotherwise (created on first write).
For steps on each platform, see the setup guides for Linux, macOS, and Windows.
Keys
| Key | Default | Set by |
|---|---|---|
theme | catppuccin | Reserved default; the active flavor is tracked under ui.flavor below. |
ui.flavor | auto | bluefin-cli theme <flavor>, or the Settings screen in the TUI menu. auto follows your terminal's reported scheme. |
ui.dark_mode | true | The Settings screen in the TUI menu. |
bundles.base_url | https://raw.githubusercontent.com/projectbluefin/common/main/system_files | Not 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_path | shared/usr/share/ublue-os/homebrew | Same as above. |
game.high_score | 0 | The hidden dino game in the TUI header. |
update.last_check | unset | bluefin-cli menu, to throttle the update check to once per 24h. |
profile.gist_id | unset | bluefin-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.
| Variable | Overrides |
|---|---|
BLUEFIN_UI_FLAVOR | ui.flavor |
BLUEFIN_UI_DARK_MODE | ui.dark_mode |
BLUEFIN_THEME | theme |
BLUEFIN_BUNDLES_BASE_URL | bundles.base_url |
BLUEFIN_BUNDLES_DEFAULT_PATH | bundles.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:
| Variable | Effect |
|---|---|
HOMEBREW_PREFIX | When 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_COUNTME | Set to any non-empty value to opt out of the anonymous countme usage ping (internal/countme/countme.go). |
WSL_DISTRO_NAME, WSL_INTEROP | Used (alongside /proc markers) to detect WSL; affects Windows-specific install paths. |
LOCALAPPDATA | Used on Windows to locate per-user app data for terminal/font registration. |
SHELL | Your 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_DESKTOP | Consulted 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.