Bluefin CLI
A strong, modern CLI tool that manages your shell configuration and the look of
your development environment. Its TUIs use the Charm libraries.
Contribute compute — no code needed
Donate time with your AI CLI.
Your machine runs one task at a time using your signed-in AI coding CLI.
The relay alternates between eligible School (OS) and Reef (apps)
hives after each task. If one hive has no work, the other can continue.
The guide covers prerequisites, verified just setup, credentials, provider
costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply.
Never post account credentials or API keys in issues or pull requests.
✨ Features
- 🎨 Interactive Menu: Default TUI experience for easy navigation
- ✨ Shell Experience: Turn on modern tools for your shell (eza, bat, ugrep, zoxide, atuin, starship)
- 📰 MOTD: Beautiful Message of the Day with system info and random tips
- 📦 Bundle Installer: Install curated tool bundles (ai, cli, fonts, k8s) from Universal Blue
- 🖼️ Wallpapers: Install desktop wallpaper collections from ublue-os/tap
- 🎨 Starship Themes: Browse and apply Starship prompt themes
- 📊 Status Command: View configuration and installed tools at a glance
- 🩺 Doctor:
bluefin-cli doctor diagnoses setup problems with fix hints
- 🎨 Theme Flavors:
bluefin-cli theme pins a Catppuccin flavor (latte, frappe, macchiato, mocha) or follows your terminal with auto
- ⬆ Self-Update:
bluefin-cli update for script installs — sha256-verified against the release checksums. For a package-manager install, it tells you the correct upgrade command
- 🏠 My Brewfile: one file describes your machine's packages —
brew/cask lines plus winget/scoop/choco on Windows. bluefin-cli brewfile dump records the installed packages. add/remove edit that file, and install applies all of it. The TUI does the same from Install Apps → My Brewfile, one package at a time. For syntax and examples, refer to the Brewfile guide. Extra recipes in ~/.config/bluefin-cli/bundles/*.Brewfile appear alongside the curated bundles
- 📦 Profiles:
bluefin-cli profile export > setup.json on one machine, profile import setup.json on another — shells, tools, and theme replayed exactly
- 🦕 A fully native TUI: a persistent shell with breadcrumbs and a fuzzy filter (
/). It also has a ctrl+p command palette and a dot-matrix dino in the header. It hides a surprise.
🚀 Installation
> Status (2026-10-07): each release ships prebuilt binary assets:
> tarballs for Linux, macOS and Windows, plus native deb and rpm packages.
> The one-liner scripts and direct downloads below work today. A note
> marks each package-manager path that does not work yet.
One-liner (Linux / macOS)
curl -fsSL https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.sh | sh
> Status (2026-10-07): the script downloads the binary from GitHub release
> assets, published on every release since v0.10.6.
One-liner (Windows PowerShell)
irm https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.ps1 | iex
Then enable shell integration:
bluefin-cli shell powershell on
> Status (2026-10-07): same as the Linux/macOS one-liner — the script
> downloads from GitHub release assets, published on every release since
> v0.10.6.
Homebrew (Linux / macOS)
The preview formula is available from ublue-os/homebrew-experimental-tap,
synced from the source-build formula in
contrib/homebrew/bluefin-cli.rb:
brew tap ublue-os/homebrew-experimental-tap
brew install bluefin-cli
> Status (2026-10-17): use ublue-os/homebrew-experimental-tap above.
> The primary tap tuna-os/homebrew-tap
> is not available yet. The GoReleaser configuration includes the Homebrew
> publisher, but GoReleaser skips it until an organization administrator sets
> the HOMEBREW_TAP_TOKEN repository secret (#295).
> For maintainer token and setup details, see
> docs/release-publishing.md. Once published,
> brew tap tuna-os/tap && brew install bluefin-cli will be the primary path.
Winget (Windows)
winget install --id Hanthor.BluefinCLI --exact
> Status (2026-10-07): the winget repository has Hanthor.BluefinCLI
> v0.8.1 (microsoft/winget-pkgs#407090). That version predates the
> current v0.11.x release line — installable, though not current. A
> newer manifest awaits review; .github/workflows/winget.yml is the manual
> fallback to resubmit one.
Chocolatey (Windows)
choco install bluefin-cli
> Status (2026-10-07): the Chocolatey community repository has no
> bluefin-cli package yet — not available.
Scoop (Windows)
scoop bucket add tuna-os https://github.com/tuna-os/scoop-bucket
scoop install bluefin-cli
> Status (2026-10-07): still not published — tuna-os/scoop-bucket
> ships no manifests at all. Like the Homebrew tap above, GoReleaser skips
> the Scoop publisher because no one has set the SCOOP_BUCKET_TOKEN
> repository secret; see
> docs/release-publishing.md.
deb / rpm (Debian, Ubuntu, Fedora, openSUSE…)
Releases ship native packages (nfpm) since v0.10.6 — grab the one for your
> distro from the latest release:
# Debian/Ubuntu
sudo dpkg -i bluefin-cli__linux_amd64.deb
# Fedora & friends
sudo rpm -i bluefin-cli__linux_amd64.rpm
AUR (Arch)
yay -S bluefin-cli-bin
> Status (2026-10-07): no bluefin-cli-bin package exists in the AUR yet
> — not available.
Go Install
go install github.com/tuna-os/bluefin-cli@latest
Build from Source (Any OS)
Prerequisites:
git clone https://github.com/tuna-os/bluefin-cli.git
cd bluefin-cli
go build -o bluefin-cli .
On Windows, use go build -o bluefin-cli.exe ..
Maintainers: semantic-release gives a version to each qualified merge to
main, then calls GoReleaser to send the release assets to the package
channels. .github/workflows/winget.yml is a manual fallback, to submit a
Winget version again.
A Scoop release needs the SCOOP_BUCKET_TOKEN repository secret. GoReleaser
uses it to upload the Scoop manifest to the bucket. Without it, GoReleaser
skips that upload. See release details.
A Homebrew tap release needs the HOMEBREW_TAP_TOKEN repository secret.
GoReleaser uses it to upload the formula to the tap. Without it, GoReleaser
skips that upload. See release details.
Homebrew release process: when semantic-release finds that a merge to
main warrants a release, it invokes GoReleaser. GoReleaser then sends the
binary formula to tuna-os/homebrew-tap when HOMEBREW_TAP_TOKEN is set.
For external taps that build from source, such as
ublue-os/homebrew-experimental-tap, sync the tap by hand. Bump url and
sha256 in contrib/homebrew/bluefin-cli.rb
and open a PR in that tap.
📖 Usage
Run the command to start the interactive menu:
bluefin-cli
Or explicitly:
bluefin-cli menu
Command Line Usage
Check Status
View your current configuration and installed tools:
bluefin-cli status
Diagnose Problems
bluefin-cli doctor
Update
bluefin-cli update # self-update (script installs)
bluefin-cli update --check # just check
✨ Shell Experience
Bluefin CLI includes a "Shell Experience" module (formerly "bling") that configures your shell with modern tools and aliases.
To enable the shell experience:
bluefin-cli shell bash on
bluefin-cli shell zsh on
bluefin-cli shell fish on
bluefin-cli shell ash on # busybox ash (Alpine, postmarketOS)
bluefin-cli shell nu on # Nushell
bluefin-cli shell powershell on
Or use the interactive menu: bluefin-cli menu -> "Shell Experience".
Two shells need a word of explanation:
- ash has no rc file by convention. An interactive ash reads the file that
$ENV names. Thus shell ash on writes ~/.ashrc, then exports ENV from
~/.profile so that ash reads it. atuin, starship and carapace have no ash
target, so bluefin-cli omits them there. The other tools work as usual.
- Nushell cannot evaluate a string. Thus
shell nu on writes the init
script to ~/.config/nushell/bluefin-cli.nu, and config.nu reads it from
there. Run bluefin-cli shell nu on again after you change your tool
configuration, to make a new copy of that script.
Features:
- eza: Modern replacement for
ls
- bat: Syntax color for
cat
- ugrep: Faster grep
- zoxide: Smarter
cd
- atuin: Shell history sync
- starship: Cross-shell prompt
- uutils: Rust rewrite of coreutils
MOTD - Message of the Day
Show the MOTD:
bluefin-cli motd show
Toggle MOTD for shells:
# Enable for all shells
bluefin-cli motd toggle all on
# Enable for specific shell
bluefin-cli motd toggle zsh on
# Disable MOTD
bluefin-cli motd toggle all off
Install curated Homebrew bundles:
# List available bundles
bluefin-cli install list
# Install specific bundle
bluefin-cli install ai # AI tools
bluefin-cli install cli # CLI essentials
bluefin-cli install fonts # Development fonts
bluefin-cli install k8s # Kubernetes tools
# Interactive mode
bluefin-cli install
Install Wallpapers
Install desktop wallpaper collections:
# Interactive selection
bluefin-cli install wallpapers
# Install specific wallpaper casks
bluefin-cli install wallpapers bluefin-wallpapers aurora-wallpapers bazzite-wallpapers
# Non-interactive test run: apply theme + enable all automation
bluefin-cli install wallpapers bluefin-wallpapers --yes
# Non-interactive with explicit controls
bluefin-cli install wallpapers bluefin-wallpapers --non-interactive --apply-theme --theme Bluefin --enable-mode-sync --enable-auto-dark-light --trigger-source polling
# Use startup-only mode sync (no minute polling task)
bluefin-cli install wallpapers bluefin-wallpapers --non-interactive --enable-mode-sync --trigger-source startup
# Auto Dark Mode integration mode (startup sync + external mode-change utility)
bluefin-cli install wallpapers bluefin-wallpapers --non-interactive --enable-mode-sync --trigger-source autodarkmode
# Cleanup Windows sync artifacts/state/tasks generated by wallpaper integration
bluefin-cli install wallpapers cleanup
# Full reset for testing: cleanup + uninstall known wallpaper casks + local wallpaper folders
bluefin-cli install wallpapers cleanup --all
Non-interactive wallpaper flags:
--non-interactive: Skip prompts and use provided flags.--yes: Shortcut for --non-interactive --apply-theme --enable-mode-sync --enable-auto-dark-light.--apply-theme: Apply a Windows theme after registration (WSL only).--theme : Theme to apply in non-interactive mode (Bluefin, Aurora, Bazzite).--enable-mode-sync: Enable day/night wallpaper sync task.--enable-auto-dark-light: Turn on the 6 AM and 6 PM light/dark tasks (needs --enable-mode-sync).--trigger-source <source></source>: Mode-sync trigger source (polling, startup, autodarkmode).
autodarkmode notes:
- Bluefin CLI ensures
%LOCALAPPDATA%\\BluefinCLI\\set-light-mode.ps1 and %LOCALAPPDATA%\\BluefinCLI\\set-dark-mode.ps1 exist.
- In Auto Dark Mode, point light/dark custom script hooks to those two scripts.
Starship Themes
You can change the appearance of your prompt.
Browse and apply Starship preset themes:
bluefin-cli starship theme
Install Starship if not already present:
bluefin-cli starship install
The shell command configures these modern CLI tools:
- eza: Modern replacement for
ls with icons and colors
- bat: A
cat clone with syntax color
- zoxide: Smarter
cd command that learns your habits
- atuin: Magical shell history with sync and search (optional)
- starship: Fast, customizable prompt for any shell
- ugrep: Ultra-fast grep alternative (optional)
Shell Aliases
When the shell experience is enabled in your shell:
ll # eza -l --icons=auto --group-directories-first
ls # eza
cat # bat --style=plain --pager=never
grep # ugrep (if installed)
📚 Documentation
- Command reference: Generated documentation for
every command and flag.
- Interactive menu structure: Menu hierarchy, navigation, and
available actions.
- Standard and plus builds: Feature differences
between the two published binaries.
- Available tools: Tools and bundles included with Bluefin CLI.
- GNOME integration: GNOME-specific setup and behavior.
- AI tools and CNCF tools: Details for the curated
bundle categories.
- Configuration: Config file location and schema,
environment variables, and user-defined bundles.
- Profile workflows: Export, import, diff, and gist sync
for portable shell, tool, and theme setups.
docs/troubleshooting.md: how to read doctor
output, and fixes for common setup problems.docs/testing.md: how to run the TUI tests, the test
layers, and how to add a test.
Maintainers can find package-channel credentials and release checks in
release details. The
Winget workflow lets maintainers submit the
Windows package again; GoReleaser handles the normal release path.
🏗️ Project Structure
bluefin-cli/
├── main.go # Application entry point
├── cmd/ # Cobra commands and TUI destinations
├── internal/
│ ├── install/ # Packages, bundles, and wallpaper installation
│ │ └── resources/ # Embedded Brewfiles and wallpaper metadata
│ ├── shell/ # Shell-experience configuration
│ ├── tui/app/ # Persistent Bubble Tea screen stack
│ └── update/ # Checksum-verified self-update
├── docs/commands/ # Generated command reference
├── scripts/ # Smoke and state validation scripts
├── test/ # Integration tests
└── justfile # Development task recipes
📚 Inspiration
This project consolidates and modernizes functionality from:
- ublue-bling: Shell aliases and tool initialization scripts
- bluefin-cli (cask): Homebrew package management and MOTD
- ujust recipes: Task runner and development environment helpers
🛠️ Development
Prerequisites
- Go 1.26.0 or later, matching the
go directive in go.mod (the CI jobs validate with Go 1.27)
- Podman (for container tests)
just (to run recipes)
Building
just build
just build creates both variants:
bluefin-cli: the standard CLIbluefin-cli-plus: the standard CLI plus the features that the build tag selects:
wallpapers, fonts, and sunset automation
Testing
# Run the integration suite in a container
just test
# Run the complete Go test suite locally
go test ./...
# Run the same race-enabled suite used by CI
go test -tags extra -race ./...
Interactive Development
Launch shells with the shell experience pre-configured:
just bash # Test in bash
just zsh # Test in zsh
just fish # Test in fish
Dependencies
This project uses:
- Cobra: framework for CLI commands
- Huh - Forms and prompts
- Lipgloss: styles for terminal output
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
📄 License
The Apache License 2.0 covers this project. See the LICENSE file for details.
🙏 Acknowledgments
- Universal Blue - For the original bluefin-cli and ublue-bling
- Charm - For the TUI libraries
- The Homebrew community
Part of the TunaOS ecosystem. Docs · Contributor guide
Contribute compute — no code needed
No time to write code? You can still push this project's backlog forward. TunaOS AI-agent hives work on this repository. Lend a hive your AI subscription or API tokens, and your machine runs contributor tasks from this project's backlog.