*the cards in the logo are unofficial cards made for balafetch logo, not actual Balatro cards*
 |
 |
 |
| Example 1 | Example 2 | Example 3 |
balafetch is a lightweight wrapper for fastfetch that displays your system information with a random Balatro card as the logo. Each time you run it, balafetch fetches a random card from the Balatro fandom wiki (Jokers, Tarot Cards, Planet Cards, Spectral Cards, or Vouchers) and passes it to fastfetch for display. If anything goes wrong, it gracefully falls back to default fastfetch behavior.
- Why?
- Features
- Prerequisites
- Installation
- Usage
- How It Works
- Troubleshooting
- Contributing
- License
- Credits
- balatro.
- boredom.
Not long ago, i was looking at some rices on the hyprland discord server, and i came accross that beautiful balatro themed rice.
and i thought to myself,
"this rice would be perfect if it add a balatro card as the logo in fastfetch"
so i decided to make it myself, and here we are.
- 🎴 Randomly displays Balatro cards from 5 different categories (Jokers, Spectral Cards, Vouchers, Planet Cards, Tarot Cards)
- 🪶 Lightweight - doesn't ship with card images or fastfetch binary
- 🔄 Automatic image cleanup after display
- 🛡️ Graceful fallback to default fastfetch on errors
- 🌐 Fetches fresh card images from the Balatro fandom wiki API
- fastfetch must be installed and available in your PATH
- Install via your package manager or from fastfetch releases
- Must be compiled with ImageMagick support for image display
- Graphics-capable terminal emulator (for displaying card images)
- Supported terminals: Kitty, WezTerm, iTerm2, Konsole, Windows Terminal (with Sixel), or any terminal supporting Kitty/Sixel/iTerm graphics protocols
- Fallback: ASCII art via Chafa if graphics protocols aren't supported
- Internet connection (for fetching card images)
Download the latest version of balafetch for your OS and architecture:
curl -OL https://github.com/gitmobkab/balafetch/releases/latest/download/balafetch-{os}-{arch}Or download a specific version of balafetch:
curl -O -L https://github.com/gitmobkab/balafetch/releases/download/{version}/balafetch-{os}-{arch}Note
On Windows, you must add .exe to the filename
# For balfetch V0.4.0 on Windows amd64 (64-bit)
curl -O -L https://github.com/gitmobkab/balafetch/releases/download/V0.4.0/balafetch-windows-amd64.exe
# or for the latest
curl -OL https://github.com/gitmobkab/balafetch/releases/latest/download/balafetch-windows-amd64.exeReplace the following placeholders:
{version}- The version you want (e.g.,v0.4.0,V0.3.0, etc.){os}- Your operating system (linux,darwinfor macOS,windows,freebsd){arch}- Your CPU architecture (amd64,arm64,arm)
Important
For whatever reason, balafetch use capital V rather than v for versioning, so make sure to use {version} with a capital V when downloading. (e.g., V0.4.0 instead of v0.4.0)
Available OS/Architecture pairs:
windows/amd64windows/arm64linux/amd64linux/arm64linux/armdarwin/amd64(macOS Intel)darwin/arm64(macOS Apple Silicon)freebsd/amd64freebsd/arm64freebsd/arm
Versioning: You can find the latest version number on the balafetch GitHub Releases page.
you can see the latest release version in the badge at the top of this README as well. See the CHANGELOG for details on what's new in each version.
Release Page: You can also visit the balafetch releases page to manually download the binary for your platform.
To ensure the integrity of the downloaded binary, you can verify its SHA256 checksum against the value provided in the release notes.
Get the expected checksum from the release notes
see the release notes for the version you downloaded, and find the SHA256 checksum for your specific OS/architecture binary. ( available in the "Assets" section of the release and since v0.4.0)
# Example: expected checksum for Linux AMD64 binary in v0.4.0
bccd4f65...07b *dist/balafetch-linux-amd64
# Compute the checksum of the downloaded file
sha256sum balafetch-{os}-{arch}
# Compare the computed checksum with the expected value
# If they match, the file is valid. If not, do not use the file and try downloading again.Linux/macOS/FreeBSD:
# Make the binary executable
chmod +x balafetch-{os}-{arch}
# Move to a directory in your PATH for system-wide installation
sudo mv balafetch-{os}-{arch} /usr/local/bin/balafetchTip
If you prefer to install balafetch only for the current user:
mv balafetch-{os}-{arch} ~/.local/bin/balafetchWindows:
# Rename the binary (if needed)
ren balafetch-windows-{arch}.exe balafetch.exe
# Move to a directory in your PATH (e.g., C:\Windows\System32 or add a custom directory to PATH)
move balafetch.exe C:\Windows\System32\Start a new terminal and type:
balafetchIf there's no pre-built binary for your platform, you can build balafetch yourself.
Prerequisites:
Build instructions:
# Clone the repository
git clone https://github.com/gitmobkab/balafetch.git
cd balafetch
# Build the project
go build ./cmd/balafetch/ -o balafetch
# Install (system-wide)
sudo mv balafetch /usr/local/bin/
# Or install for current user only
mv balafetch ~/.local/bin/balafetch - The stupid balatro flavoured fastfetch wrapper
Usage: balafetch [OPTIONS] [CARD CATEGORY | ALIAS]
Options:
-h, --help Show help information
-t, --timeout int Set the timeout for API requests in seconds (default 20)
-v, --version Show version information
--version-full Show detailed version information
Available categories (aliases in parentheses):
- jokers (joker)
- tarot cards (tarot, tarots)
- planet cards (planet, planets)
- spectral cards (spectral, spectrals)
- vouchers (voucher)you can check the CLI documentation for more details on usage.
Note
To be very lightweight, balafetch doesn't ship with any Balatro card images nor the actual fastfetch binary. This means that in order to work, you at least need to have the fastfetch command available in your terminal.
When you run balafetch:
-
Logging relative setup - Initializes logging configuration
-
Pick a card category - Randomly selects between:
- jokers
- spectral cards
- vouchers
- planet cards
- "tarot cards
-
Request all images - Fetches all images for the selected category from the Balatro fandom API
-
Pick a random card - Selects one card at random from the fetched list
-
Download the image - Downloads the card image to your temporary folder as
balatro-{randomHash}.png -
Execute fastfetch - Runs
fastfetch -l path/to/card.pngwith the downloaded image -
Cleanup - Removes the temporary image file
Most operations are independent of balafetch itself and are bridged by your computer, internet availability/speed, hard drive speed, etc.
balafetch isn't working? See the balafetch troubleshooting documentation
balafetch has intelligent fallback behavior to ensure you always get some output:
Fatal Errors (red boxes) - Force balafetch to print an error and exit:
- Permission errors
- Command not found (fastfetch not installed)
- Logging setup failures
- Invalid usage (unsupported arguments) [since v0.3.0]
Fallible Errors (yellow boxes) - Recovered by falling back to default fastfetch:
- Failed to request images from API
- Failed to download selected card image
When a fallible error occurs, balafetch will automatically fall back to running fastfetch with default settings.
"command not found: fastfetch"
- Make sure fastfetch is installed and in your PATH
- Try running
fastfetchdirectly to verify installation
No image appears / Falls back to default fastfetch
- Check your internet connection
- The Balatro fandom API might be temporarily unavailable
- Check your temporary directory has write permissions
Note
balafetch has a log file located in your home directory at ~/balafetch/balafetch.log
You can check what went wrong there if the logo is not a Balatro card
Permission denied errors
- Ensure balafetch has execute permissions:
chmod +x balafetch - Check that your temporary directory is writable
If you're building scripts around balafetch, you may want to handle different error codes. See the Error Codes Documentation for details on all exit codes.
Contributions are welcome! Feel free to open issues or submit pull requests.
check the contributing guidelines for more details on contribution before submitting.
Under the MIT License
- fastfetch - The awesome system information tool this wraps
- Balatro - For being an incredible game
- Balatro Fandom Wiki - For providing the card images via their API
Made with ❤️ and a deck of cards 🃏