brewfile guide
One Brewfile can list the packages for Linux, macOS, and Windows.
This guide shows the syntax, what bluefin-cli brewfile install does on each
platform, and some examples.
The default Brewfile is ~/Brewfile. If ~/Brewfile does not exist and
~/.Brewfile does, Bluefin CLI uses ~/.Brewfile. Use --file to select a
different file.
1. Syntax
Bluefin CLI reads five package kinds from a Brewfile:
# Homebrew (macOS, Linux)
brew "ripgrep"
cask "ghostty"
# Windows managers
winget "Microsoft.VisualStudioCode"
scoop "neovim"
choco "git"
| Kind | Target | Install command |
|---|---|---|
brew | macOS, Linux | brew bundle install |
cask | macOS, Linux | brew bundle install |
winget | Windows | winget install --exact --accept-package-agreements --accept-source-agreements --id <id> |
scoop | Windows | cmd /c scoop install <id> |
choco | Windows | choco install -y <id> |
The tool does not read tap lines, flatpak lines, comments (#), or
blank lines into the package list. brew bundle install still reads the tap lines.
2. One File for All Platforms
When you run bluefin-cli brewfile install:
-
If the file has
breworcasklines, Bluefin CLI runsbrew bundle install --file=<path>. Ifbrewis not on yourPATH, it shows this message and continues:skipping brew/cask entries: homebrew not found (https://brew.sh) -
For each
winget,scoop, orchocoline, Bluefin CLI runs the install command for that manager. If the manager is not on yourPATH, it shows this message and continues:skipping winget "Microsoft.VisualStudioCode": winget not installed
Thus you can keep Homebrew lines and Windows lines in the same file.
3. Errors
- If
brew bundle installfails, the command stops with that error. - Before each Windows package, Bluefin CLI shows a line like
winget: installing Microsoft.VisualStudioCode. - If the install of a Windows package fails, Bluefin CLI shows
winget <id> failed: <error>and continues with the next package.
4. Record Your Packages
bluefin-cli brewfile dump writes the installed packages to the Brewfile:
bluefin-cli brewfile dump --file ./Team.Brewfile
On macOS and Linux, this command runs brew bundle dump --force. On Windows,
it writes the winget, scoop, and choco packages that it finds.
Other subcommands: add, remove, list, and search. Refer to the
brewfile command reference.
5. Custom Bundles
Put extra bundle files in this directory:
~/.config/bluefin-cli/bundles/<name>.Brewfile
These bundles show in bluefin-cli install list and in the TUI menu
Install Apps. Refer to Configuration.
6. Use With Profiles
A profile keeps your shells, tools, and theme. A Brewfile keeps your packages. To copy a setup to a new machine, use the two together.
On the old machine:
bluefin-cli profile export > my-profile.json
bluefin-cli brewfile dump --file ~/MyBrewfile
On the new machine:
bluefin-cli profile import my-profile.json
bluefin-cli brewfile install --file ~/MyBrewfile
To compare the machine with the profile:
bluefin-cli profile diff my-profile.json
7. Example
# Command-line tools (macOS, Linux)
brew "bat"
brew "eza"
brew "fzf"
brew "ripgrep"
brew "starship"
brew "zoxide"
# Applications (macOS)
cask "ghostty"
cask "visual-studio-code"
# Windows
winget "Microsoft.VisualStudioCode"
winget "Git.Git"
winget "Starship.Starship"
scoop "7zip"
choco "curl"