Skip to main content

index

License

A strong, modern CLI tool that manages your shell configuration and the look of your development environment. Its TUIs use the Charm libraries.

✨ 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 <flavor> 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. 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, a fuzzy filter (/), a ctrl+p command palette, and a dot-matrix dino in the header. It also hides a surprise.

🚀 Installation​

Status (2026-08-14): each release ships prebuilt binary assets. Since v0.10.6 that includes tarballs for Linux, macOS and Windows, plus native deb and rpm packages, so the one-liner scripts below work. A note marks each package-manager path that is not ready yet.

One-liner (Linux / macOS)​

curl -fsSL https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.sh | sh

Status (2026-08-14): the script downloads the binary from GitHub release assets, which are published since v0.10.6 (#141, closed).

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-08-14): same as the Linux/macOS one-liner — the script downloads from GitHub release assets, which are published since v0.10.6 (#141, closed).

Homebrew (Linux / macOS)​

The formula is published automatically by GoReleaser to the tuna-os/homebrew-tap tap on every release (#15):

brew tap tuna-os/tap
brew install bluefin-cli

Status (2026-08-14): the bluefin-cli formula has not been published by the release pipeline yet — only corral-vm.rb ships in the tuna-os tap (see #141). Until it appears, use ublue-os/homebrew-experimental-tap below.

It is also 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

Winget (Windows)​

winget install --id Hanthor.BluefinCLI --exact

Status (2026-08-14): Hanthor.BluefinCLI v0.8.1 is published in the winget repository (microsoft/winget-pkgs#407090, merged 08-14) but predates the current v0.10.6 release line — installable, though not yet current (#141, closed — release publishing works; a newer manifest submission is pending).

Chocolatey (Windows)​

choco install bluefin-cli

Status (2026-08-14): no bluefin-cli package has been published to the Chocolatey community repository yet — not available (#141, closed — release publishing now works, the Choco manifest is still pending).

Scoop (Windows)​

scoop bucket add tuna-os https://github.com/tuna-os/scoop-bucket
scoop install bluefin-cli

Status (2026-08-14): tuna-os/scoop-bucket has no manifests yet — the manifest is published by the release pipeline and is currently pending (#141, closed — release publishing now works, the Scoop manifest is still pending).

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_<version>_linux_amd64.deb
# Fedora & friends
sudo rpm -i bluefin-cli_<version>_linux_amd64.rpm

AUR (Arch)​

yay -S bluefin-cli-bin

Status (2026-08-14): no bluefin-cli-bin package exists in the AUR yet — not available (#141, closed).

Go Install​

go install github.com/tuna-os/bluefin-cli@latest

Build from Source (Any OS)​

Prerequisites:

  • Go 1.26.0 or later
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 (a fine-grained PAT with write access to tuna-os/scoop-bucket), without which the Scoop manifest upload step is safely skipped during release workflows. See docs/release-publishing.md for details.

A Homebrew tap release needs the HOMEBREW_TAP_TOKEN repository secret (a fine-grained PAT with write access to tuna-os/homebrew-tap), without which the formula upload step is safely skipped during release workflows. See docs/release-publishing.md for details.

Homebrew release process: when semantic-release determines that a merge to main warrants a release, it invokes GoReleaser, which publishes the binary formula to tuna-os/homebrew-tap (requires the HOMEBREW_TAP_TOKEN secret). External taps that build from source, such as ublue-os/homebrew-experimental-tap, must be synced manually — bump url and sha256 in contrib/homebrew/bluefin-cli.rb and open a PR in that tap.

📖 Usage​

Interactive Menu (Default)​

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 Tool Bundles​

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 <name>: 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>: 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

🔧 What Gets Configured​

Shell Experience Tools​

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​

Maintainers can find package-channel credentials and release verification in Release publishing. The Winget workflow is the manual fallback for re-submitting the Windows package; 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 containerized testing)
  • just (for running recipes)

Building​

just build

just build creates both variants:

  • bluefin-cli: the standard CLI
  • bluefin-cli-plus: the standard CLI plus features selected by the extra build tag, including 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:

🤝 Contributing​

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License​

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments​

  • Universal Blue - For the original bluefin-cli and ublue-bling
  • Charm - For the amazing TUI libraries
  • The Homebrew community

🔗 Related Projects​

Part of the TunaOS ecosystem. Docs · Contributing

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.