3. Usage Guide

WallRizz is a versatile wallpaper manager with a variety of options for customizing your desktop's appearance. Below is a detailed guide to its usage, along with examples to help you get started.

Command-Line Options

Option	Description
-d, --wall-dir FILE	Wallpaper directory path. (default: /home/ss/dev/erps) It can be passed as WALLPAPER_DIR environment variable.
-r, --(no-)random	Apply a random wallpaper from the directory.
-s, --img-size WIDTHxHEIGHT	Image cell size. (default: 30x10)
-l, --(no-)light-theme	Enable light theme.
-p, --padding VERTICLExHORIZONTAL	Container padding in cells. (default: 1x1)
-e, --(no-)enable-pagination	Display wallpapers in a fixed-size grid. Remaining wallpapers will be displayed in the next grid upon navigation.
-g, --grid-size WIDTHxHEIGHT	Wallpaper grid size. (default: 4x4)
-t, --(no-)theme-extensions	Download theme extension scripts.
-c, --color-backend VAL	Set color extraction command. (default: magick {} -format %c -define histogram:method=kmeans -colors 16 histogram:info:)
-z, --preview-mode VAL	Wallpaper preview mode. (default: grid) Can be one of [grid, list].
-w, --(no-)wallpaper-handler	Download wallpaper handler script.
-b, --(no-)browse	Browse wallpapers online.
-u, --repo-url URL(s)	Wallpaper repository GitHub URL(s). (default: https://github.com/5hubham5ingh/WallRizz/tree/wallpapers/) Can be passed as WALLPAPER_REPO_URLS environment variable.
-k, --api-key VAL	GitHub API key. Can be passed as GITHUB_API_KEY environment variable.
-m, --(no-)show-keymap	Display keymaps for the user interface.
-n, --(no-)disable-notification	Disable desktop notifications.
-a, --(no-)disable-autoscaling	Disable auto-scaling terminal size to fit all images.
-v, --set-interval NUM	Set the time interval to periodically set a random wallpaper.
-f, --set-interval-callback JavaScript IIFE	Set a callback function to conditionally modify the arguments at setInterval. Can be passed as WW_CB environment variable.
-o, --(no-)hold	Keep the app running even after the wallpaper has been applied.
-x, --plimit NUM	Number of execution threads used. (default: auto)
-i, --(no-)inspection	Enable verbose error log for inspection.
--(no-)test	Test extensions.
-h, --help	Print help.
--version	Print version.

--directory (-d)

Browse wallpapers in given directory.

Example

WallRizz -d ~/Pictures/wallpapers  

--random (-r)

Applies a random wallpaper from the specified directory.

Example:

WallRizz -r -d ~/Pictures/wallpapers  

--img-size (-s)

Defines the display size of images in cells. Format: WIDTHxHEIGHT.

Example:

WallRizz -s 150x40 -d ~/Pictures/wallpapers  

--light-theme (-l)

Enables light theme mode.

Example:

WallRizz -l -d ~/Pictures  

--padding (-p)

Sets the container padding in cells. Format: VERTICLExHORIZONTAL.

Example:

WallRizz -p 2x2 -d ~/Pictures  

--enable-pagination (-e)

Enables grid pagination for wallpaper display.

Example:

WallRizz -e -g 5x5 -d ~/Pictures  

--grid-size (-g)

Defines the size of the wallpaper grid. Format: WIDTHxHEIGHT.

Example:

WallRizz -g 3x3 -d ~/Pictures  

--theme-extensions (-t)

Downloads theme extension scripts.

Example:

WallRizz -t -d ~/Pictures  

--color-backend (-c)

Change the color extraction command.

Example:

WallRizz -c "sh -c 'matugen image {} -j hex | jq -r .colors.dark[],.colors.light[]'"

--wallpaper-handler (-w)

Downloads the wallpaper handler script.

Example:

WallRizz -w -d ~/Pictures  

--browse (-b)

Browse and download wallpapers online.

Example:

WallRizz -b -u https://github.com/5hubham5ingh/WallRizz/tree/wallpapers  

--repo-url (-u)

Specifies a wallpaper repository URL. Supports multiple URLs separated by semicolons (;).

Example:

WallRizz -u https://github.com/D3Ext/aesthetic-wallpapers/tree/main/images;https://github.com/5hubham5ingh/WallRizz/tree/wallpapers  

--api-key (-k)

Sets a GitHub API key to increase API rate limits. You can also use the GITHUB_API_KEY environment variable.

Example:

WallRizz -k YOUR_API_KEY -b -u https://github.com/5hubham5ingh/WallRizz/tree/wallpapers  

--show-keymap (-m)

Displays the user interface key mappings.

Example:

WallRizz -m  

--disable-notification (-n)

Disables desktop notifications.

Example:

WallRizz -n -d ~/Pictures  

--disable-autoscaling (-a)

Disables auto-scaling of the terminal size to fit all images.

Example:

WallRizz -a -d ~/Pictures  

--set-interval (-v)

Applies a random wallpaper periodically at the specified interval (in milliseconds).

Example:

WallRizz -v 3600000 -d ~/Pictures  

--set-interval-callback (-f)

Injects a JavaScript snippet to modify user arguments at setInterval.

Example:

WallRizz -v 3600000 -c "(globalThis.USER_ARGUMENTS ??= {})['enableLightTheme'] = ((h) => h >= 6 && h < 18)(new Date().getHours())"  

--hold (-o)

Keeps the application open even after the wallpaper has been applied.

Example:

WallRizz -o -d ~/Pictures  

--plimit (-x)

Sets the number of execution threads to use.

Example:

WallRizz -x 4 -d ~/Pictures  

--help (-h)

Displays the help menu.

Example:

WallRizz -h  

--version

Displays the program version.

Example:

WallRizz --version  

---

Combined Examples

1. Download Theme Extensions and Apply Light Theme:

   WallRizz -t -l -d ~/Pictures  

2. Enable Grid View with Pagination and Disable Autoscaling:

   WallRizz -e -a -g 4x4 -d ~/Pictures  

3. Set Wallpapers Based on the time:

   WallRizz -v 3600000 -c "(globalThis.USER_ARGUMENTS ??= {})['wallpapersDirectory'] = ((h) => h >= 6 && h < 18 ? `${HOME_DIR}/pics/nature/` : `${HOME_DIR}/pics/anime/`)(new Date().getHours())"  

4. Browse Wallpapers from Multiple Repositories:

   WallRizz -b -u https://github.com/D3Ext/aesthetic-wallpapers/tree/main/images;https://github.com/5hubham5ingh/WallRizz/tree/wallpapers  

---

For more information or query, check out the FAQ.