index

A powerful, modern CLI tool for managing shell configuration and development environment customization. Built with beautiful TUIs using Charm libraries.

✨ Features

• 🎨 Interactive Menu: Default TUI experience for easy navigation
• ✨ Bling: Toggle modern shell enhancements (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; package-manager installs are pointed at the right upgrade command
• 🏠 My Brewfile: one file describes your machine's packages — brew/cask lines plus winget/scoop/choco on Windows. bluefin-cli brewfile dump captures what's installed, add/remove edit it, install applies everything; the TUI's Install Apps → My Brewfile does all of it interactively with per-package management. 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: persistent shell with breadcrumbs, fuzzy filtering (/), a ctrl+p command palette, and a dot-matrix dino running the header — plus a hidden surprise for those who find it

🚀 Installation

One-liner (Linux / macOS)

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

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

Homebrew (Linux / macOS)

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

Winget (Windows)

winget install --id Hanthor.BluefinCLI --exact

Scoop (Windows)

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

deb / rpm (Debian, Ubuntu, Fedora, openSUSE…)

Every release ships native packages — 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

Go Install

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

Build from Source (Any OS)

Prerequisites:

• Go 1.25 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: package publishing (Homebrew tap, Winget, Scoop) is automated by GoReleaser on release; .github/workflows/winget.yml is a manual fallback for re-submitting a Winget version.

📖 Usage

Interactive Menu (Default)

Simply run the command to launch 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
# or

bluefin-cli shell zsh on
# or

bluefin-cli shell fish on

Or use the interactive menu: bluefin-cli menu -> "Shell Experience".

Features:

• eza: Modern replacement for ls
• bat: Syntax highlighting for cat
• ugrep: Faster grep
• zoxide: Smarter cd
• atuin: Shell history sync
• starship: Cross-shell prompt
• uutils: Rust rewrite of coreutilsl

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: Enable 6 AM/6 PM light/dark switching tasks (requires --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 your prompy lookks Browse and apply Starship preset themes:

bluefin-cli starship theme

Install Starship if not already present:

bluefin-cli starship install

🔧 What Gets Configured

Bling Tools

The bling command configures these modern CLI tools:

• eza: Modern replacement for ls with icons and colors
• bat: cat clone with syntax highlighting
• 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 bling 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

• Interactive Menu Structure: A visual guide to the application's menu hierarchy and options.
• Available Tools: A comprehensive list of all tools and bundles available.
• Winget Publishing Guide: Steps to publish and maintain the Windows package.

🏗️ Project Structure

bluefin-cli/
├── main.go              # Application entry point
├── cmd/                 # Cobra commands
│   ├── root.go         # Root command & menu default
│   ├── menu.go         # Interactive TUI menu
│   ├── bling.go        # Bling command
│   ├── motd.go         # MOTD command
│   ├── install.go      # Install bundles/wallpapers
│   ├── starship.go     # Starship theme management
│   └── status.go       # Status display
├── internal/            # Internal packages
│   ├── bling/          # Bling logic & embedded scripts
│   ├── motd/           # MOTD generation
│   ├── install/        # Bundle & wallpaper installation
│   ├── starship/       # Starship integration
│   └── status/         # Status checking
└── test/                # Integration tests

📚 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.21+
• Podman (for containerized testing)
• just (for running recipes)

Building

just build

Testing

# Run tests in container

just test

# Run tests locally

go test ./...

Interactive Development

Launch shells with bling pre-configured:

just bash   # Test in bash
just zsh    # Test in zsh
just fish   # Test in fish

Dependencies

This project uses:

• Cobra - CLI framework
• Huh - Forms and prompts
• Lipgloss - Style definitions

🤝 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

• ublue-os/packages - Original package implementations
• Starship - Cross-shell prompt
• Homebrew - Package manager for macOS and Linux

---

Part of the TunaOS ecosystem. Docs · Contributing