bubblefetch

A fast, themeable system info tool built with Go and Bubbletea.
Single-run output (prints once, exits cleanly) — An alternative to neofetch/fastfetch.

Landing page · Docs · Quickstart · Themes

Buy me a coffee

🚀 One Command → Beautiful Output

# Default theme
bf

# Switch themes instantly
bf --theme dracula

# Export as image
bf -o bubblefetch.svg

# Fetch Solana token data
bf --sol DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Copy, paste, done. No configuration needed to get gorgeous themed output.

Why Bubblefetch?

Bubblefetch brings modern features to the fetch tool space:

Feature	Bubblefetch	fastfetch	neofetch
Speed	~1.3ms median	~10ms	~130ms
Plugin System	✅ Go plugins + external scripts	❌	❌
Image Exports	✅ PNG, SVG, HTML	❌	❌
Interactive Config	✅ TUI wizard	❌	❌
SSH Remote Mode	✅ Full support	⚠️ Limited	❌
Domain Scan	✅ WHOIS + DNS	❌	❌
Solana Token Info	✅ Real-time data	❌	❌
Per-Module Timing	✅ `costs` module	❌	❌
Export Formats	JSON, YAML, text, PNG, SVG, HTML	JSON, text	❌
Themes	8 built-in, easy custom	Custom	Custom

Performance methodology: ~1.3ms median collection time on local system (excluding network calls) measured via --benchmark flag over 100 iterations.

✨ What's New in v0.3.1

🪙 Solana Token Info (NEW!)

Fetch and display Solana token data with real-time pricing and 24h charts.

bf --sol DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

See example output →

Features from v0.3.0

🔌 Plugin System

Create custom modules with Go plugins or external scripts.

echo '{"label":"Weather","value":"72°F","icon":"󰖐"}' > plugin.sh

View plugin examples →

🖼️ Image Export

Export as PNG, SVG, or HTML with full theme support.

bf -o bubblefetch.svg

View SVG example → · View PNG →

🧙 Config Wizard

Interactive TUI setup with theme preview and module selection.

bf --config-wizard

See wizard screenshot → (Manual: Take screenshot)

🌐 Public IP Detection

Optional public IP display (privacy-first, disabled by default).

# Enable in config
enable_public_ip: true
modules:
  - publicip

See docs/CHANGELOG.md for complete details.

Features

Core Features

⚡ Blazing Fast: ~1.3ms median collection time - 100x faster than neofetch, 10x faster than fastfetch
Styled Output: Themed, framed terminal output with Nerd Font icons
OS Detection: Automatically detects your OS/distro and displays appropriate ASCII art
Comprehensive Info: CPU, GPU, memory, disk, network, battery, local IP, and more
Themeable: 8 built-in themes with easy custom theme creation

Advanced Features

🔌 Plugin System: Extend with custom modules using Go plugins (.so files)
🧩 External Modules: Drop executable scripts in plugins/external/
🧙 Interactive Config Wizard: Guided setup with theme preview and module selection
🖼️ Image Export: Export as PNG (raster), SVG (vector), or HTML (webpage)
🌐 Public IP Detection: Optional public IP display (privacy-first, disabled by default)
🌍 SSH Remote Support: Fetch system info from remote systems via SSH
🔎 Domain Scan: WHOIS + DNS lookup via --who
🪙 Solana Token Info: Fetch token data by contract address via --sol
📤 Export Modes: Export to JSON, YAML, or plain text
📊 Benchmark Mode: Measure collection performance (text or JSON output)
📈 Module Cost: Visualize per-module timing with the costs module
⚙️ Highly Customizable: YAML config, custom themes, modular system info display

Documentation

Start here: docs/README.md
Quick setup: docs/QUICKSTART.md
Examples: docs/EXAMPLES.md
Plugins: docs/PLUGINS.md
Exports schema: docs/EXPORTS.md
Remote mode: docs/REMOTE.md
Performance: docs/PERFORMANCE.md

Installation

Release Binaries

https://github.com/howieduhzit/bubblefetch/releases/latest

Arch Linux (AUR)

yay -S bubblefetch-git

AUR package: https://aur.archlinux.org/packages/bubblefetch-git Installs the bf alias alongside bubblefetch.

Quick Install (recommended)

git clone https://github.com/howieduhzit/bubblefetch.git
cd bubblefetch
./install.sh

This script:

Builds the optimized binary
Installs to /usr/local/bin
Creates ~/.config/bubblefetch
Copies themes + example config

Manual install

git clone https://github.com/howieduhzit/bubblefetch.git
cd bubblefetch
go build -ldflags="-s -w" -o bubblefetch ./cmd/bubblefetch
sudo mv bubblefetch /usr/local/bin/

Go install

go install github.com/howieduhzit/bubblefetch/cmd/bubblefetch@latest

Quick Start

New to bubblefetch? Get started in 60 seconds:

# 1. Install bubblefetch
git clone https://github.com/howieduhzit/bubblefetch.git
cd bubblefetch
./install.sh

# 2. Run the interactive setup wizard
bubblefetch --config-wizard

# 3. Run bubblefetch!
bf

# 4. Try different themes
bf --theme dracula
bf --theme nord

# 5. Export your setup
bf -o my-setup.png

That's it! See docs/QUICKSTART.md for more detailed guidance.

Common Setups

Ready-to-run recipes for popular use cases:

🪶 Minimal Laptop

Clean output, fast, low overhead.

# config.yaml
theme: minimal
modules:
  - os
  - kernel
  - uptime
  - cpu
  - memory
  - battery

bf

🎥 Streamer Flex

Full specs, colorful theme, export-ready.

# config.yaml
theme: dracula
modules:
  - os
  - kernel
  - host
  - cpu
  - gpu
  - memory
  - disk
  - network
  - localip

bf -o ~/stream-assets/sysinfo.png

🔒 Remote Server Audit (Safe Mode)

No shell pipelines, read-only commands.

bf --remote production-server --remote-safe --export json > audit.json

🎨 Theme Author Starter

Test themes quickly, enable timing.

# config.yaml
modules:
  - os
  - kernel
  - cpu
  - memory
  - costs  # Shows per-module timing

bf --theme my-custom-theme

Usage

Basic Usage

# Run with default settings
bubblefetch

# Short alias
bf

# Use a specific theme
bubblefetch --theme dracula

# Use custom config file
bubblefetch --config ~/.config/bubblefetch/custom.yaml

Tip: Use a Nerd Font in your terminal to see module icons. Note: bubblefetch prints once and exits (no interactive TUI).

Remote Systems (SSH)

# Fetch info from remote system via SSH
bubblefetch --remote user@hostname

# Uses your SSH config and keys automatically
bubblefetch --remote myserver

# Read-only safe mode (no shell pipelines)
bubblefetch --remote myserver --remote-safe

Domain Scan

bf --who google.com
bf --who google.com -R  # Include raw WHOIS

Solana Token Info

# Fetch token data by contract address
bf --sol EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# Short form
bf -s EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

# With theme
bf --sol EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --theme dracula

# Export as JSON
bf --sol EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v --export json

🚀 Enhanced Token Data with Bags.fm

For tokens launched via Bags.fm, get additional data including:

Creator Info: Who deployed the token (username + platform)
Launch Date: When the token was created
Total Fees: Lifetime fees collected by the token

Setup (Optional)

Get your free API key at dev.bags.fm
Add to your config:

# ~/.config/bubblefetch/config.yaml
bags_api_key: "your-api-key-here"

Note: Bags.fm data only appears for tokens launched through their platform. All other tokens still work with DexScreener data.

Export Modes

# Export as JSON
bubblefetch --export json > system.json

# Export as YAML
bubblefetch --export yaml > system.yaml

# Export as plain text
bubblefetch --export text > system.txt

# Compact JSON (no pretty print)
bubblefetch --export json --pretty=false

Benchmark Mode

# Run 10 iterations and show performance stats
bubblefetch --benchmark

# JSON benchmark output
bubblefetch --benchmark --format json

Interactive Config Wizard

First time setup? Run the interactive wizard:

bubblefetch --config-wizard

The wizard will guide you through:

Theme selection (preview all 8 built-in themes)
Module selection (choose which info to display)
Privacy settings (enable/disable public IP detection)
Plugin directory configuration

Configuration is saved to ~/.config/bubblefetch/config.yaml

Plugin System

Create custom modules with either external scripts or Go plugins.

External modules (recommended):

mkdir -p ~/.config/bubblefetch/plugins/external
cat > ~/.config/bubblefetch/plugins/external/weather.sh <<'EOF'
#!/usr/bin/env bash
echo '{"label":"Weather","value":"72°F","icon":"󰖐"}'
EOF
chmod +x ~/.config/bubblefetch/plugins/external/weather.sh

Add weather to your modules list.

Git context example (branch, dirty, ahead/behind, root):

mkdir -p ~/.config/bubblefetch/plugins/external
cp plugins/examples/external/git-context.sh ~/.config/bubblefetch/plugins/external/
chmod +x ~/.config/bubblefetch/plugins/external/git-context.sh

Go plugins (power users):

# Build example plugin
make plugin-hello

# Install to plugin directory
make install-plugins

# Add to config
modules:
  - hello  # Your custom plugin
  - os
  - cpu

Plugin Development:

See docs/PLUGINS.md for complete guide
Examples in plugins/examples/
Platform support: Linux, macOS, FreeBSD (not Windows)

Quick example:

package main

import (
    "github.com/howieduhzit/bubblefetch/internal/collectors"
    "github.com/howieduhzit/bubblefetch/internal/ui/theme"
)

var ModuleName = "hello"

func Render(info *collectors.SystemInfo, styles theme.Styles) string {
    return styles.Label.Render("Hello") +
           styles.Separator.Render(": ") +
           styles.Value.Render("World!")
}

Themes

Bubblefetch includes 8 beautiful built-in themes. Switch instantly with --theme:

Default (Catppuccin Mocha)

bf --theme default

Preview

(Manual: Add screenshot)

Colors: Primary #89b4fa, Secondary #cba6f7, Accent #f38ba8 Border: Rounded Download theme file →

Dracula

bf --theme dracula

Preview

(Manual: Add screenshot)

Colors: Primary #bd93f9, Secondary #ff79c6, Accent #50fa7b Border: Double Download theme file →

Nord

bf --theme nord

Preview

(Manual: Add screenshot)

Colors: Primary #88c0d0, Secondary #81a1c1, Accent #b48ead Border: Thick Download theme file →

Gruvbox

bf --theme gruvbox

Preview

(Manual: Add screenshot)

Colors: Primary #fabd2f, Secondary #fe8019, Accent #b8bb26 Border: Rounded Download theme file →

Tokyo Night

bf --theme tokyo-night

Preview

(Manual: Add screenshot)

Colors: Primary #7aa2f7, Secondary #bb9af7, Accent #9ece6a Border: Rounded Download theme file →

Solarized Dark

bf --theme solarized-dark

Preview

(Manual: Add screenshot)

Colors: Primary #268bd2, Secondary #6c71c4, Accent #859900 Border: Normal Download theme file →

Monokai

bf --theme monokai

Preview

(Manual: Add screenshot)

Colors: Primary #66d9ef, Secondary #f92672, Accent #a6e22e Border: Normal Download theme file →

Minimal

bf --theme minimal

Preview

(Manual: Add screenshot)

Colors: Monochrome white/gray Border: None Download theme file →

Creating Custom Themes

Copy a theme file to ~/.config/bubblefetch/themes/mytheme.json:

{
  "name": "mytheme",
  "colors": {
    "primary": "#89b4fa",
    "secondary": "#cba6f7",
    "accent": "#f38ba8",
    "label": "#f9e2af",
    "value": "#a6e3a1",
    "border": "#585b70",
    "background": "#1e1e2e"
  },
  "ascii": "auto",
  "layout": {
    "show_ascii": true,
    "ascii_width": 30,
    "separator": " ",
    "padding": 2,
    "border_style": "rounded"
  }
}

Then use it:

bf --theme mytheme

Share your themes! Submit a PR to themes/ directory.

Outputs

Bubblefetch can export your system info in multiple formats:

Image Exports

Perfect for sharing your setup on social media, creating wallpapers, or documentation.

PNG Export (Raster)

bf --image-export png --image-output sysinfo.png

Preview PNG example

View full size →

SVG Export (Vector)

bf --image-export svg --image-output sysinfo.svg

Preview SVG example

View full size →

HTML Export (Webpage)

bf --image-export html --image-output sysinfo.html

Preview HTML example

Standalone, responsive webpage with embedded CSS.

View HTML file →

Data Exports

Export system info as structured data for scripting or monitoring:

# JSON (pretty)
bf --export json

# JSON (compact)
bf --export json --pretty=false

# YAML
bf --export yaml

# Plain text
bf --export text

All exports respect your configured modules and collect the same data as visual output.

Privacy & Safety

What Bubblefetch Collects

Local only (default):

OS/distro, kernel version
Hostname
CPU, GPU, memory, disk usage
Active network interfaces
Battery status (if applicable)
Current shell, terminal emulator

Optional network features (disabled by default):

Public IP detection (enable_public_ip: true)
- Tries api.ipify.org, icanhazip.com, ifconfig.me
- 2-second timeout
- Completely optional
WHOIS/DNS lookup (--who domain.com)
Solana token data (--sol address)
SSH remote collection (--remote user@host)

Default Behavior

No network calls by default
No telemetry or analytics
No data sent to external servers
All data stays on your machine

Disabling Network Features

# config.yaml
enable_public_ip: false  # Default

# Don't add these modules
modules:
  # - publicip  # Leave this commented

Or use --remote-safe for SSH mode to disable shell pipelines.

SSH Remote Mode Safety

When using --remote:

Uses your existing SSH config
Respects SSH key auth
Safe mode (--remote-safe) disables shell pipelines
Only collects system info (no destructive operations)

Recommendation: Always use --remote-safe on production systems.

Troubleshooting

Nerd Font Icons Not Showing

Problem: Module icons appear as boxes or question marks.

Solution: Install a Nerd Font and configure your terminal to use it.

# 1. Install a Nerd Font (example: JetBrains Mono)
# Download from https://www.nerdfonts.com/

# 2. Configure terminal to use the font
# - Most terminals: Settings → Font → Select "JetBrains Mono Nerd Font"
# - Alacritty: Update ~/.config/alacritty/alacritty.yml
# - Kitty: Update ~/.config/kitty/kitty.conf

# 3. Test
bf

Recommended fonts: JetBrains Mono Nerd Font, FiraCode Nerd Font, Hack Nerd Font

macOS/Windows Support

Status:

Linux: ✅ Fully supported
macOS: ⚠️ Core features work, plugins limited (no .so support)
FreeBSD: ✅ Supported
Windows: ❌ Not supported (PRs welcome!)

macOS limitations:

Go plugins (.so files) don't work
External script plugins work fine
All other features supported

SSH Remote Prerequisites

Problem: --remote fails to connect.

Check:

Can you SSH manually?
```
ssh user@hostname
```
Is your SSH key added?
```
ssh-add -l
```
Is the remote host in ~/.ssh/known_hosts?
Use --remote-safe if you see permission errors.

Still stuck? Open an issue with your error message.

Plugin Not Loading

Problem: Custom plugin doesn't appear in output.

Checklist:

Is the plugin in the correct directory?

ls ~/.config/bubblefetch/plugins/external/

Is it executable?

chmod +x ~/.config/bubblefetch/plugins/external/myplugin.sh

Does it output valid JSON?

~/.config/bubblefetch/plugins/external/myplugin.sh
# Should output: {"label":"...","value":"..."}

Is it in your modules list?

# config.yaml
modules:
  - myplugin  # Must match filename (without extension)

See docs/PLUGINS.md for complete guide.

Performance Issues

Problem: Bubblefetch seems slow.

Debug:

# Check per-module timing
bf  # Add "costs" to your modules list

# Run benchmark
bf --benchmark

# Expected: ~1-2ms on modern hardware

Common causes:

Network-dependent modules (publicip, plugins that fetch data)
Slow SSH connection (use --remote-safe)
Many external plugins with timeouts

Solution: Disable slow modules or increase plugin timeout in config.

Modules

Available built-in modules:

os - Operating system name
kernel - Kernel version
host - Hostname
uptime - System uptime
cpu - CPU model
gpu - GPU model
memory - RAM usage
disk - Disk usage
shell - Current shell
terminal - Terminal emulator
network - Active network interfaces
localip - Local IP address
publicip - Public IP address (optional)
battery - Battery status (laptops)
costs - Per-module timing

Add custom modules via plugins!

Configuration

# ~/.config/bubblefetch/config.yaml
theme: default
modules:
  - os
  - kernel
  - cpu
  - memory
  - disk
  - uptime

Command-Line Reference

Usage: bubblefetch [OPTIONS]

Options:
  -c, --config string         Path to config file (default: ~/.config/bubblefetch/config.yaml)
  -t, --theme string          Theme name to use (overrides config)
  -r, --remote string         Remote system IP/hostname to fetch info from (via SSH)
  -e, --export string         Export format: json, yaml, or text
  -p, --pretty                Pretty print JSON output (default: true)
  -b, --benchmark             Run benchmark mode (10 iterations)
  -f, --format string         Benchmark output format: text or json
  -w, --config-wizard         Run interactive configuration wizard
  --image-export string       Export as image: png, svg, or html
  -o, --image-output string   Image output path (default: bubblefetch.{format})
  -W, --who string            Domain scan (WHOIS + DNS records)
  -R, --who-raw               Include raw WHOIS output
  -s, --sol string            Fetch Solana token data by contract address
  --remote-safe               Use read-only SSH commands (no shell pipelines)
  -v, --version               Print version information
  -h, --help                  Show help message

Notes:
  - If --image-export is omitted, the format is inferred from --image-output extension.
  - Add "costs" to your modules list to display per-module timing.

Examples:
  bubblefetch                                    # Run with default config
  bf                                             # Short alias
  bubblefetch --theme dracula                    # Use dracula theme
  bf -t dracula                                  # Short flags
  bubblefetch --config-wizard                    # Interactive setup
  bubblefetch --remote user@server               # SSH to remote system
  bf -r user@server                              # Short remote flag
  bubblefetch --export json --pretty=false       # Export compact JSON
  bf -e json -p=false                            # Short export flags
  bubblefetch --image-export png                 # Export as PNG
  bf -o ~/Pictures/fetch.svg                     # Auto-detect SVG from extension
  bubblefetch --who google.com                   # Domain WHOIS + DNS scan
  bubblefetch --sol <contract_address>           # Solana token info
  bf -s EPjFWdd...                               # Short Solana flag
  bubblefetch --benchmark                        # Performance test

Contributing

Contributions welcome! We're especially looking for:

Theme contributions: Share your custom themes
Plugin examples: Show off creative plugins
Documentation improvements: Help others get started
Bug reports: Open an issue
Feature requests: Tell us what you'd like to see

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

Built with Bubbletea and Lipgloss
Inspired by neofetch and fastfetch
ASCII art detection from DistroWatch

Made with ❤️ by the Bubblefetch community

⭐ Star us on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
.gocache		.gocache
cmd/bubblefetch		cmd/bubblefetch
dist/releases		dist/releases
docs		docs
examples/exports		examples/exports
internal		internal
packaging		packaging
plugins		plugins
scripts		scripts
site		site
themes		themes
.gitignore		.gitignore
BAGS_FM_INTEGRATION.md		BAGS_FM_INTEGRATION.md
DOCUMENTATION_UPDATE_SUMMARY.md		DOCUMENTATION_UPDATE_SUMMARY.md
LICENSE		LICENSE
MANUAL_TASKS.md		MANUAL_TASKS.md
Makefile		Makefile
QUICK_CHECKLIST.md		QUICK_CHECKLIST.md
README-OLD.md		README-OLD.md
README.md		README.md
config.example.yaml		config.example.yaml
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation

bubblefetch

🚀 One Command → Beautiful Output

📋 Table of Contents

Why Bubblefetch?

✨ What's New in v0.3.1

🪙 Solana Token Info (NEW!)

🔌 Plugin System

🖼️ Image Export

🧙 Config Wizard

🌐 Public IP Detection

Features

Core Features

Advanced Features

Documentation

Installation

Release Binaries

Arch Linux (AUR)

Quick Install (recommended)

Quick Start

Common Setups

🪶 Minimal Laptop

🎥 Streamer Flex

🔒 Remote Server Audit (Safe Mode)

🎨 Theme Author Starter

Usage

Basic Usage

Remote Systems (SSH)

Domain Scan

Solana Token Info

🚀 Enhanced Token Data with Bags.fm

Export Modes

Benchmark Mode

Interactive Config Wizard

Plugin System

Themes

Default (Catppuccin Mocha)

Dracula

Nord

Gruvbox

Tokyo Night

Solarized Dark

Monokai

Minimal

Creating Custom Themes

Outputs

Image Exports

PNG Export (Raster)

SVG Export (Vector)

HTML Export (Webpage)

Data Exports

Privacy & Safety

What Bubblefetch Collects

Default Behavior

Disabling Network Features

SSH Remote Mode Safety

Troubleshooting

Nerd Font Icons Not Showing

macOS/Windows Support

SSH Remote Prerequisites

Plugin Not Loading

Performance Issues

Modules

Configuration

Command-Line Reference

Contributing

License

Acknowledgments

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Packages