wallfetch

██╗    ██╗ █████╗ ██╗     ██╗     ███████╗███████╗████████╗ ██████╗██╗  ██╗
██║    ██║██╔══██╗██║     ██║     ██╔════╝██╔════╝╚══██╔══╝██╔════╝██║  ██║
██║ █╗ ██║███████║██║     ██║     █████╗  █████╗     ██║   ██║     ███████║
██║███╗██║██╔══██║██║     ██║     ██╔══╝  ██╔══╝     ██║   ██║     ██╔══██║
╚███╔███╔╝██║  ██║███████╗███████╗██║     ███████╗   ██║   ╚██████╗██║  ██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝   ╚═╝    ╚═════╝╚═╝  ╚═╝

📦 Installation

🚀 Quick Install (Recommended)

One-liner installation for Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/AccursedGalaxy/wallfetch/main/scripts/install.sh | bash

Package Managers

Go Install

If you have Go installed:

go install github.com/AccursedGalaxy/wallfetch/cmd/wallfetch@latest

Arch Linux (AUR)

# Using yay
yay -S wallfetch

# Using paru
paru -S wallfetch

# Manual
git clone https://aur.archlinux.org/wallfetch.git
cd wallfetch
makepkg -si

Ubuntu/Debian

# Download latest .deb package
wget https://github.com/AccursedGalaxy/wallfetch/releases/latest/download/wallfetch_amd64.deb
sudo dpkg -i wallfetch_amd64.deb
sudo apt-get install -f  # Fix dependencies if needed

Manual Installation

Pre-built Binaries

1. Download the latest release for your platform from GitHub Releases
2. Extract and move to your PATH:

# Linux x64
wget https://github.com/AccursedGalaxy/wallfetch/releases/latest/download/wallfetch-linux-amd64
chmod +x wallfetch-linux-amd64
sudo mv wallfetch-linux-amd64 /usr/local/bin/wallfetch

Build from Source

git clone https://github.com/AccursedGalaxy/wallfetch.git
cd wallfetch
make build
sudo make install

# Optional: Set up weekly automation (Linux only)
./scripts/install-weekly-automation.sh

🛠️ Quick Start

1. Initialize Configuration

wallfetch config init

2. Set Your API Key

Get your free API key from Wallhaven and add it to ~/.config/wallfetch/config.yaml:

wallhaven:
  api_key: "your_api_key_here"

3. Fetch Wallpapers

# Fetch 10 wallpapers
wallfetch fetch wallhaven --limit 10

# Fetch with specific filters
wallfetch fetch wallhaven --limit 5 --resolution 1920x1080 --categories general

# Fetch ultrawide wallpapers
wallfetch fetch wallhaven --limit 5 --aspect-ratio 21x9 --only-landscape

4. Manage Your Collection

# List downloaded wallpapers
wallfetch list

# Browse wallpapers in your collection
wallfetch browse

# Browse with terminal preview (requires chafa or viu)
wallfetch browse --preview --interactive

# Browse random wallpapers with external viewer
wallfetch browse --random --viewer feh

# Clean up database (remove entries for deleted files)
wallfetch cleanup

# Remove duplicates (with confirmation)
wallfetch dedupe

# Prune old wallpapers, keep only 50 most recent
wallfetch prune --keep 50

⚙️ Configuration

Default Configuration Location

• Linux: ~/.config/wallfetch/config.yaml
• macOS: ~/.config/wallfetch/config.yaml
• Windows: %APPDATA%\wallfetch\config.yaml

Sample Configuration

default_source: "wallhaven"
download_dir: "~/Pictures/Wallpapers"
max_concurrent: 5

wallhaven:
  api_key: "your_api_key_here"

defaults:
  limit: 10
  resolution: "1920x1080"
  sort: "toplist"
  only_landscape: true

filters:
  min_width: 1920
  min_height: 1080
  aspect_ratios: ["16x9", "21x9"]

database:
  path: "~/.local/share/wallfetch/wallfetch.db"

Environment Variables

You can also set configuration via environment variables:

export WALLHAVEN_API_KEY="your_api_key_here"
export WALLFETCH_DOWNLOAD_DIR="~/Pictures/Wallpapers"

🎯 Usage Examples

Basic Usage

# Fetch 10 random wallpapers
wallfetch fetch wallhaven

# Fetch with specific category
wallfetch fetch wallhaven --categories anime --limit 5

# Fetch top wallpapers
wallfetch fetch wallhaven --sort toplist --limit 10

Advanced Filtering

# Ultrawide only
wallfetch fetch wallhaven --aspect-ratio 21x9 --only-landscape --limit 5

# High resolution wallpapers
wallfetch fetch wallhaven --min-resolution 2560x1440 --limit 10

# Multiple categories
wallfetch fetch wallhaven --categories general,anime --limit 15

Database Management

# Show configuration
wallfetch config show

# List all wallpapers with file status
wallfetch list

# Clean up orphaned database entries
wallfetch cleanup --dry-run  # Preview changes
wallfetch cleanup             # Apply cleanup

# Remove duplicates with confirmation
wallfetch dedupe --dry-run    # Preview what would be deleted
wallfetch dedupe              # Actually remove duplicates

# Prune old wallpapers intelligently
wallfetch prune --keep 100 --dry-run  # Preview pruning
wallfetch prune --keep 100            # Keep only 100 most recent

# Delete specific wallpaper
wallfetch delete 12345       # By database ID
wallfetch delete --source-id abc123  # By source ID

🤖 Weekly Automation

WallFetch includes a powerful automation system that can automatically fetch fresh wallpapers weekly using systemd timers. Perfect for keeping your wallpaper collection constantly updated with minimal effort.

✨ Automation Features

• 🕐 Scheduled Fetching: Automatically runs weekly with randomized delay
• ⚙️ Configurable Categories: Customize which wallpaper categories to fetch
• 📊 Smart Filtering: Ensures minimum resolution and quality standards
• 🔄 Auto-Cleanup: Maintains collection size by removing old wallpapers
• 📝 Detailed Logging: Track all fetch operations and results
• 💬 Desktop Notifications: Get notified when new wallpapers are added
• 🎯 No Duplicates: Leverages WallFetch's built-in deduplication

🚀 Quick Setup

Install the automation system with a single command:

# Using the installation script
./scripts/install-weekly-automation.sh

# Or using make targets (requires git clone)
make install-automation

# Check status
./scripts/install-weekly-automation.sh status
# or
make automation-status

# Remove automation if needed
./scripts/install-weekly-automation.sh uninstall
# or  
make uninstall-automation

⚙️ Configuration

The automation creates a configuration file at ~/.config/weekly-wallpaper-fetch.conf:

# Weekly Wallpaper Fetch Configuration
# Categories to fetch (comma-separated)
CATEGORIES="anime,city"

# Number of wallpapers to fetch per category
LIMIT=5

# Minimum resolution required
RESOLUTION="3440x1440"

# Sort method (toplist, date_added, relevance, random, views, favorites)
SORT="toplist"

# Content purity (sfw, sketchy, nsfw)
PURITY="sfw"

📋 Manual Script Usage

You can also run the automation script manually:

# Create default configuration
./scripts/weekly-wallpaper-fetch.sh --config

# Fetch wallpapers now
./scripts/weekly-wallpaper-fetch.sh --fetch

# Check current status
./scripts/weekly-wallpaper-fetch.sh --status

# View recent logs
./scripts/weekly-wallpaper-fetch.sh --logs

🔧 Automation Management

Monitor and control your automation:

# Check systemd timer status
systemctl --user status weekly-wallpaper-fetch.timer

# View next scheduled runs
systemctl --user list-timers weekly-wallpaper-fetch.timer

# Manually trigger a fetch
systemctl --user start weekly-wallpaper-fetch.service

# View service logs
journalctl --user -u weekly-wallpaper-fetch.service -f

📅 Schedule Details

• Frequency: Every 7 days
• Startup Delay: 5 minutes after boot
• Random Delay: Up to 1 hour (to distribute server load)
• Persistence: Runs missed schedules after system wake-up

🐚 Shell Completions

Enable shell completions for a better CLI experience:

Bash

# Linux
wallfetch completion bash | sudo tee /etc/bash_completion.d/wallfetch

# macOS
wallfetch completion bash > $(brew --prefix)/etc/bash_completion.d/wallfetch

Zsh

wallfetch completion zsh > "${fpath[1]}/_wallfetch"

Fish

wallfetch completion fish > ~/.config/fish/completions/wallfetch.fish

🔧 Development

Prerequisites

• Go 1.21 or higher
• Make (optional, for using Makefile)

Building

# Clone the repository
git clone https://github.com/AccursedGalaxy/wallfetch.git
cd wallfetch

# Build
make build

# Install locally
make install

# Run tests
make test

# Clean build artifacts
make clean

Contributing

1. Fork the repository
2. Create a 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 MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Wallhaven for providing the wallpaper API
• Cobra for the excellent CLI framework
• SQLite for the embedded database

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 📚 Documentation: Wiki