{"id":24653845,"url":"https://github.com/joshbeard/walsh","last_synced_at":"2025-10-26T13:16:34.449Z","repository":{"id":200866064,"uuid":"706301543","full_name":"joshbeard/walsh","owner":"joshbeard","description":"🖼️ Tool for managing wallpapers on Linux, BSD, and macOS","archived":false,"fork":false,"pushed_at":"2025-01-06T14:29:03.000Z","size":671,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-19T20:08:21.599Z","etag":null,"topics":["desktop-environment","hyprland","sway","wallpaper-changer","wallpaper-manager","wallpapers","wayland","xorg"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshbeard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-17T17:16:48.000Z","updated_at":"2024-11-25T23:11:40.000Z","dependencies_parsed_at":"2024-01-15T20:13:01.230Z","dependency_job_id":"ccd3ff8f-34a5-48d3-a156-f5943b594941","html_url":"https://github.com/joshbeard/walsh","commit_stats":null,"previous_names":["joshbeard/walls.sh","joshbeard/walsh"],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fwalsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fwalsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fwalsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeard%2Fwalsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshbeard","download_url":"https://codeload.github.com/joshbeard/walsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235633944,"owners_count":19021456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["desktop-environment","hyprland","sway","wallpaper-changer","wallpaper-manager","wallpapers","wayland","xorg"],"created_at":"2025-01-25T21:14:18.606Z","updated_at":"2025-10-07T13:32:15.763Z","avatar_url":"https://github.com/joshbeard.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# walsh\n\nWalsh is a niche CLI wallpaper manager for randomizing images on multiple\ndisplays from various configured sources. It supports saving images to lists,\nblacklisting unwanted images, downloading images, and more, by acting as a\nwrapper around other tools to query displays and set wallpapers.\n\n\u003cimg align=\"right\" width=\"256\" height=\"256\" src=\".doc/image.jpg\"\u003e\n\n## Features\n\n* Download wallpapers from Bing and Unsplash using [gosimac](https://github.com/1995parham/gosimac)\n* Set wallpapers randomly or specifically for each display\n* Change wallpapers on demand or at regular intervals\n* Manage wallpaper lists and set wallpapers from these lists\n* Track recent wallpapers to avoid repetition\n* Blacklist unwanted wallpapers\n* Source images from a remote server over SSH\n* Supports Xorg, Wayland, and macOS\n\n## Getting Started\n\n1. Ensure [dependencies](#dependencies) are installed.\n2. [Install](#installation) the latest version of walsh.\n3. [Run](#usage) walsh to set a random wallpaper on each display.\n    * You can run `walsh download bing` to get a few wallpapers to start.\n    * Then just run `walsh set` to set a random wallpaper.\n    * `~/Pictures/Wallpapers` is the default source directory.\n4. [Configure](#configuration) walsh to customize it, specifically the sources\n   you want to use.\n\n## Dependencies\n\n### Wayland\n\nOnly [swww](https://github.com/Horus645/swww) is supported for setting the\nwallpaper on Wayland. swww works across Wayland compositors.\n\nHyprland and Sway have been tested and are known to work, using `hyprctl` and\n`swaymsg` respectively.\n\n### Xorg\n\n* `xrandr`\n* One of the following tools, in order of preference:\n  * [nitrogen](https://wiki.archlinux.org/title/Nitrogen)\n  * [feh](https://wiki.archlinux.org/title/Feh)\n  * [xwallpaper](https://github.com/stoeckmann/xwallpaper)\n  * [xsetbg](https://linux.die.net/man/1/xsetbg)\n\n### macOS\n\nNo specific dependencies are required for macOS.\n\n### Download from Bing and Unsplash\n\nIf the `download` command is used, the [gosimac](https://github.com/1995parham/gosimac)\ntool should be installed and in the `PATH`.\n\n## Installation\n\nThe latest release can be found on the [releases](https://github.com/joshbeard/walsh/releases)\npage and can be downloaded and installed manually.\n\nTo download and install the latest version of walsh using `curl` and piping it\nto the shell, run the following command:\n\n```sh\ncurl -sfL https://raw.githubusercontent.com/joshbeard/walsh/master/install.sh | sh -\n```\n\nThe script will:\n- Detect your OS and architecture.\n- Download the latest release of walsh from GitHub.\n- Verify the checksum of the downloaded package.\n- Extract the binary and move it to the specified directory (default is `$HOME/bin`).\n\nMake sure the installation directory is in your `PATH` so you can easily run\n`walsh` from anywhere.\n\n### Custom Installation Directory\n\nIf you want to specify a custom installation directory, you can set the\n`INSTALL_DIR` environment variable or pass the `-d` (or `--dir`) argument. For\nexample:\n\n```sh\n# Using INSTALL_DIR environment variable\nINSTALL_DIR=/usr/local/bin curl -sfL https://raw.githubusercontent.com/joshbeard/walsh/master/install.sh | sh -\n\n# Using -d (or --dir) argument\ncurl -sfL https://raw.githubusercontent.com/joshbeard/walsh/master/install.sh | sh -s -- -d /usr/local/bin\n```\n\n## Usage\n\n```shell\nwalsh [command] [flags]\n```\n\nSee `walsh help` for more information.\n\nIf you run `walsh` without any arguments, it defaults to the `set` command and\nwill set a random wallpaper on each display.\n\nEnsure a configuration file exists at the default location and has at least one\nsource configured. See [Configuration](#configuration) for more information.\n\n### Set Wallpaper\n\n\n```shell\n# Set a random wallpaper on each display using the configured sources:\nwalsh set\n\n# Set a random wallpaper on a specific display:\nwalsh set -d 1\n\n# _`s` is an alias for `set`._\n# _You can also omit the `-d` flag and specify a number without it._\nwalsh s 1\n\n# Set a random wallpaper from a specific list:\nwalsh set -l my-list\n\n# Set a random wallpaper from a directory:\nwalsh set ~/Pictures/wallpapers\n\n# Set a specific wallpaper on each display:\nwalsh set ~/Pictures/wallpapers/wallpaper.jpg\n\n# Set a specific wallpaper on a specific display:\nwalsh set -d 1 ~/Pictures/wallpapers/wallpaper.jpg\n\n# Set a random wallpaper from an SSH source:\nwalsh set ssh://user@host/path/to/wallpapers\n```\n\n### View Wallpaper\n\n\n```shell\n# View the current wallpaper on each display:\nwalsh view\n\n# View the current wallpaper on a specific display:\nwalsh view -d 1\n```\n\n### Blacklist\n\n\n```shell\n# Blacklist the current wallpaper on a specific display:\nwalsh bl -d 1\n\nwalsh bl 1\n```\n\n### Download\n\nDownload wallpapers from Bing and Unsplash using\n[gosimac](https://github.com/1995parham/gosimac).\n\n\n\n```shell\nwalsh download bing\nwalsh download unsplash\n\n# Use short aliases:\nwalsh dl b\nwalsh dl u\n\n# Use a query with Unsplash:\nwalsh dl u -- --query \"nature\"\n```\n\n## Configuration\n\nStandard XDG configuration directories are used for configuration files.\n\nThe default configuration file is `${XDG_CONFIG_HOME}/walsh/config.yml`\n(e.g. `~/.config/walsh/config.yaml`) and will be created if it does not exist.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eDefault Configuration\u003c/summary\u003e\n\n```yaml\n# A list of directories or URIs to source images from.\nsources:\n  - ${XDG_HOME}/Pictures/Wallpapers\n\n# The file to track the currently set wallpaper.\ncurrent: ${XDG_DATA_HOME}/walsh/current.json\n\n# The file to track blacklisted wallpapers.\nblacklist: ${XDG_CONFIG_HOME}/walsh/blacklist.json\n\n# The file to track wallpaper history.\nhistory: ${XDG_DATA_HOME}/walsh/history.json\n\n# The directory where lists of wallpapers are stored.\nlists_dir: ${XDG_DATA_HOME}/walsh/lists\n\n# The directory to store temporary files, such as images downloaded from remote\n# sources.\ncache_dir: ${XDG_CACHE_HOME}/walsh\n\n# The number of images to keep in the history file.\nhistory_size: 50\n\n# The number of images to keep in the cache.\ncache_size: 50\n\n# The interval in seconds to set a new wallpaper. Set to 0 to disable.\ninterval: 0\n\n# A destination path or URI to download images to. This is used by the\n# 'download' # command.\n# Specify a path with optional environment variables or an SSH URI.\ndownload_dest: ${XDG_HOME}/Pictures/Wallpapers\n\n# set_command is the command used to set the specified wallpaper.\n# Use {{path}} to specify the path to the wallpaper and {{display}} to specify\n# the display number.\n# e.g. swww img '{{path}}' --outputs '{{display}}'\n# By default, this uses 'swww' on Wayland, 'nitrogen' on Xorg, and falls back\n# to looking for 'feh', 'xwallpaper', 'xsetbg'. Native system calls via\n# AppleScript are used on macOS.\nset_command: \"\"\n\n# view_command is the command used to view the specified wallpaper.\n# Use {{path}} to specify the path to the wallpaper.\n# e.g. feh --bg-fill '{{path}}'\n# By default, this uses 'xdg-open' on Linux/BSD and falls back to looking for\n# feh, eog, eom. Preview is used by default on macOS.\nview_command: \"\"\n```\n\n* On Linux and BSD, `${XDG_CONFIG_HOME}` defaults to `~/.config`,\n  `${XDG_DATA_HOME}` defaults to `~/.local/share`, and `${XDG_CACHE_HOME}`\n  defaults to `~/.cache`.\n* On macOS, `${XDG_CONFIG_HOME}` defaults to `~/Library/Application Support`,\n  `${XDG_DATA_HOME}` defaults to `~/Library/Application Support`, and\n  `${XDG_CACHE_HOME}` defaults to `~/Library/Caches`.\n\n\u003c/details\u003e\n\n### Sources\n\nSources is a list of directories or URIs to source images from. Directories\nare absolute or relative paths to directories on the local filesystem and can\nuse environment variables (e.g. `${HOME}/Pictures/Wallpapers`).\nAlternatively, an SSH URI can be used to source images from a remote directory.\n\n```yaml\nsources:\n  - /home/user/Pictures/wallpapers\n  - ssh://user@host:/path/to/wallpapers\n  - ssh://myhost:/path/to/wallpapers\n```\n\n### Desktop Environment Integration\n\nRun `walsh` however you like to set wallpapers. On Linux/BSD desktops, it's\npreferred to use the startup configuration of your desktop environment to run\n`walsh` at login. You can also use something like cron, systemd, or a launchd\nagent to run `walsh` at regular intervals. Or just run it on demand.\n\nIf using an SSH source, you will need to ensure your SSH agent is running and\nthe `SSH_AUTH_SOCK` environment variable is set. This is necessary for the\nremote source to work.\n\n#### Hyprland\n\n\u003cdetails\u003e\n\n\u003csummary\u003eUsing `hyprctl`\u003c/summary\u003e\n\nIn `~/.config/hypr/hyprland.conf`:\n\n```plain\nexec-once = $HOME/bin/walsh set --interval 600\n```\n\nWhen an SSH source is used, you may need to set the `SSH_AUTH_SOCK` environment\nvariable:\n\n```plain\nexec-once = SSH_AUTH_SOCK=/run/user/1000/gcr/ssh $HOME/bin/walsh set --interval 600\n```\n\n\u003c/details\u003e\n\n#### i3\n\n\u003cdetails\u003e\n\n\u003csummary\u003eUsing `i3`\u003c/summary\u003e\n\nIn `~/.config/i3/config`:\n\n```plain\nexec --no-startup-id $HOME/bin/walsh set --interval 600\n```\n\nWhen an SSH source is used, you may need to set the `SSH_AUTH_SOCK` environment\nvariable:\n\n```plain\nexec --no-startup-id export SSH_AUTH_SOCK=/run/user/1000/gcr/ssh \u0026\u0026 $HOME/bin/walsh set --interval 600\n```\n\n\u003c/details\u003e\n\n#### macOS\n\n\u003cdetails\u003e\n\n\u003csummary\u003eUsing `launchd`\u003c/summary\u003e\n\nCreate a `launchd` plist file at\n`~/Library/LaunchAgents/com.github.joshbeard.walsh.plist` with the following\ncontents:\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"\u003e\n\u003cplist version=\"1.0\"\u003e\n\u003cdict\u003e\n    \u003ckey\u003eLabel\u003c/key\u003e\n    \u003cstring\u003ecom.yourusername.walsh\u003c/string\u003e\n    \u003ckey\u003eProgramArguments\u003c/key\u003e\n    \u003carray\u003e\n        \u003cstring\u003e/Users/yourusername/bin/walsh\u003c/string\u003e\n        \u003cstring\u003eset\u003c/string\u003e\n        \u003cstring\u003e--interval\u003c/string\u003e\n        \u003cstring\u003e600\u003c/string\u003e\n    \u003c/array\u003e\n    \u003ckey\u003eRunAtLoad\u003c/key\u003e\n    \u003ctrue/\u003e\n    \u003ckey\u003eStandardOutPath\u003c/key\u003e\n    \u003cstring\u003e/tmp/walsh.stdout\u003c/string\u003e\n    \u003ckey\u003eStandardErrorPath\u003c/key\u003e\n    \u003cstring\u003e/tmp/walsh.stderr\u003c/string\u003e\n\u003c/dict\u003e\n\u003c/plist\u003e\n```\n\nThen load the plist:\n\n```shell\nlaunchctl load ~/Library/LaunchAgents/com.github.joshbeard.walsh.plist\n```\n\nTo unload the plist:\n\n```shell\nlaunchctl unload ~/Library/LaunchAgents/com.github.joshbeard.walsh.plist\n```\n\n\u003c/details\u003e\n\n## License\n\nwalsh is released under the [0BSD license](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeard%2Fwalsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshbeard%2Fwalsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeard%2Fwalsh/lists"}