wallgrab

An interactive Command-Line Interface (CLI) tool designed to query, search, and download high-resolution wallpapers from Wallhaven based on various search criteria.

This is a modern, TypeScript-based CLI tool, leveraging the speed of Bun and a rich terminal user experience.

Features

• Double-mode Execution:
  • Interactive Mode: Launch a beautiful step-by-step terminal wizard using @clack/prompts if run without parameters.
  • Direct Command Mode: Parse command-line flags using commander for quick execution or scripting.
• Smart Downloading:
  • Checks if a wallpaper is already downloaded to avoid wasting bandwidth.
  • Displays a clean, non-intrusive loading spinner (ora) with live progress.
• Premium Touches:
  • Automatically opens the download directory using process execution (execa) upon completion (on macOS).
  • Dynamic input validation for resolutions, colors, etc.
  • Supports persistent API keys and custom save folders.

Getting Started

1. Running instantly (without installing)

Users can execute the CLI on-demand without installing it permanently:

• npm: npx wallgrab
• bun: bunx wallgrab
• yarn: yarn dlx wallgrab
• pnpm: pnpm dlx wallgrab

2. Installing it globally (so the command wallgrab works directly)

If users want the command wallgrab to work anywhere in their terminal, they can install it globally:

• npm: npm install -g wallgrab
• bun: bun add -g wallgrab (or bun install -g wallgrab)
• yarn: yarn global add wallgrab
• pnpm: pnpm add -g wallgrab

Once installed globally, you can run it directly:

wallgrab [options]

3. Local Development (from Source)

Prerequisites

• Bun: Make sure you have Bun installed.

Installation

1. Clone or copy this repository to your system.
2. Navigate to the project directory:

   cd wallgrab

3. Install dependencies:

   bun install

4. Build the project:

   bun run build

Usage

1. Interactive Mode (Wizard)

Simply run the tool without any flags (or with the -i flag) to enter the step-by-step wizard:

# If installed globally:
wallgrab

# From source:
bun start
# OR
node dist/index.js

This guides you through query inputs, category selections (General, Anime, People), purity filters, sorting methods, resolution parameters, limit constraints, and more!

2. Direct CLI Command Mode

Pass options directly to the CLI to skip the interactive wizard.

Example: Download 5 space wallpapers to a custom folder

wallgrab --query "space" --limit 5 --dir "~/my-space-walls"

Example: Download 3 anime toplist SFW wallpapers from the last week

wallgrab -q "anime" -c "010" -p "100" -s "toplist" -t "1w" -n 3

CLI Options Reference

Run wallgrab --help to view all options:

Options:
  -q, --query <query>          Search query tags (e.g., "space", "-people", "+anime +scenic")
  -c, --categories <categories> Categories: 3-bit binary string (e.g., 100) or comma-separated names (general,anime,people)
  -p, --purity <purity>        Purity: 3-bit binary string (e.g., 110) or comma-separated names (sfw,sketchy,nsfw)
  -s, --sorting <sorting>      Sorting: date_added, relevance, random, views, favorites, toplist
  -o, --order <order>          Order: desc, asc
  -t, --top-range <range>      Top list range: 1d, 3d, 1w, 1M, 3M, 6M, 1y (only with sorting: toplist)
  -r, --resolution <resolution> Minimum resolution requirement (e.g., 1920x1080)
  -l, --resolutions <res...>   Exact resolutions list, comma-separated (e.g., 1920x1080,1920x1200)
  -a, --ratios <ratios>        Aspect ratios list, comma-separated (e.g., 16x9,16x10)
  --colors <colors>            Color hex code or list, comma-separated, without # (e.g., 660000)
  --page <number>              Page number to fetch (default: "1")
  --seed <seed>                Seed for random sorting
  -n, --limit <limit>          Number of wallpapers to download (0 for all) (default: "10")
  -d, --dir <directory>        Download directory (defaults to ~/wallpapers)
  -k, --api-key <key>          Wallhaven API Key
  -i, --interactive            Force interactive setup wizard
  -h, --help                   display help for command

Configuration File

Your configurations (saved API keys and custom default download directory) are stored persistently in: ~/.config/wallgrab/config.json