Skip to content
/ wallfetch Public

CLI Wallpaper Fetcher - effortlessly discover, download, and manage stunning wallpapers from multiple sources

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

AccursedGalaxy/wallfetch

BranchesTags

Repository files navigation

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

🎭 Professional Wallpaper Management for Linux

Transform your desktop with curated wallpapers from across the web

Go Version License Release CI Status Release Status

Platform Downloads Stars

✨ What is WallFetch?

WallFetch is a powerful, modern CLI tool designed for Linux enthusiasts who want to effortlessly discover, download, and manage stunning wallpapers from multiple sources. Built with performance and simplicity in mind, it transforms your wallpaper collection workflow into a seamless experience.

🎯 Perfect for...

Desktop Customizers • Linux Power Users • Aesthetic Enthusiasts • Developers

🚀 Core Features

🌐 Multi-Source 🎨 Smart Filtering ⚡ Performance
Wallhaven + More Resolution + Aspect Concurrent Downloads
🔍 Advanced Search 🏷️ Category Sorting 🔧 Worker Pools
⭐ Quality Rating 🖼️ Orientation Control 💾 Efficient Storage
🧠 Intelligence 🖥️ Cross-Platform 🛠️ Developer
Duplicate Detection Linux + macOS + Windows Modern CLI
🔐 SHA256 Verification 🐧 Primary Linux Focus 🐚 Shell Completions
🗃️ SQLite Database 📱 Universal Experience 🔄 Easy Automation

🎪 Feature Highlights

Feature Description Status
🔄 Concurrent Downloads Multi-threaded downloading for maximum speed ✅ Active
🔍 Smart Deduplication Never download the same wallpaper twice ✅ Active
📱 Interactive Browser Preview wallpapers directly in terminal ✅ Active
🗂️ Collection Management Organize, prune, and maintain your library ✅ Active
⚙️ Flexible Configuration YAML config with environment variable support ✅ Active
🎯 Precision Filtering Fine-grained control over wallpaper selection ✅ Active
🤖 Weekly Automation Automated weekly wallpaper fetching with systemd ✅ Active

📦 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

Made with ❤️ for the Linux community

About

CLI Wallpaper Fetcher - effortlessly discover, download, and manage stunning wallpapers from multiple sources

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 8

v1.2.3 Latest
Nov 28, 2025
+ 7 releases

Packages

No packages published

Languages