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.

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 <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. 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-11-19): each release ships prebuilt binary assets: archives for Linux, macOS and Windows, plus native deb and rpm packages (see .goreleaser.yaml). The latest tag in the repository is v0.11.23; the releases page is authoritative for the current version. Package-manager channels depend on external registries that this repository cannot check. Their states come from docs/release-publishing.md, last recorded 2026-10-17, and a note marks each path that is not available.

One-liner (Linux / macOS)​

For more Linux and macOS steps, see the Linux Setup Guide and macOS Setup Guide.

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

Status (2026-11-19): the script downloads the binary from GitHub release assets. Releases have published these assets since v0.10.6.

One-liner (Windows PowerShell)​

For more Windows steps, see the Windows Setup Guide.

irm https://raw.githubusercontent.com/tuna-os/bluefin-cli/main/install.ps1 | iex

Then enable shell integration:

bluefin-cli shell powershell on

Status (2026-11-19): same as the Linux/macOS one-liner — the script downloads from GitHub release assets. Releases have published these assets since v0.10.6.

Homebrew (Linux / macOS)​

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

Status (2026-11-19): GoReleaser publishes the binary formula to tuna-os/homebrew-tap on each release, with the HOMEBREW_TAP_SSH_KEY deploy key. The tap has received each release since v0.11.17, and its Formula/bluefin-cli.rb is at v0.11.23. The release policy keeps this channel at preview until a maintainer records a brew install check.

A source-build preview formula is also available from ublue-os/homebrew-experimental-tap. A maintainer syncs it by hand from contrib/homebrew/bluefin-cli.rb, so it can lag behind the current release:

brew tap ublue-os/homebrew-experimental-tap
brew install bluefin-cli

Winget (Windows)​

winget install --id Hanthor.BluefinCLI --exact

Status (last recorded 2026-10-17; not re-verified): the winget repository had Hanthor.BluefinCLI v0.8.1 (microsoft/winget-pkgs#407090). That version predates the current v0.11.x release line — installable, though not current. Check the winget-pkgs listing for the live version. .github/workflows/winget.yml is the manual fallback to resubmit one.

Chocolatey (Windows)​

choco install bluefin-cli

Status (last recorded 2026-10-17; not re-verified): no bluefin-cli package was in the Chocolatey community repository — not available. The release invocation skips this publisher.

Scoop (Windows)​

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

Status (last recorded 2026-10-17; not re-verified): 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_<version>_linux_amd64.deb
# Fedora & friends
sudo rpm -i bluefin-cli_<version>_linux_amd64.rpm

AUR (Arch)​

yay -S bluefin-cli-bin

Status (last recorded 2026-10-17; not re-verified): no bluefin-cli-bin package existed in the AUR — not available.

Go Install​

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

Build from Source (Any OS)​

Prerequisites:

  • Go 1.26.7 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. 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_SSH_KEY repository secret. GoReleaser uses it to push 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_SSH_KEY 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​

New here? Follow the quick-start guide to set up your shell, install tools, and save a profile.

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

# Skip the post-install prompt

bluefin-cli install wallpapers bluefin-wallpapers --non-interactive

# Run sunset setup right after the install, without the prompt

bluefin-cli install wallpapers bluefin-wallpapers --yes

# 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 the post-install prompt.
  • --yes: Skip the prompt and run bluefin-cli sunset setup after the install.

Both flags apply on WSL and Windows only. There, an install that names casks offers to set up theme and wallpaper changes that follow the sun. bluefin-cli sunset setup runs the same setup at any time; see the sunset reference.

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 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.7 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 CLI
  • bluefin-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.

  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​

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.