{"id":13479463,"url":"https://github.com/scriptingosx/desktoppr","last_synced_at":"2025-04-06T01:11:29.612Z","repository":{"id":38714114,"uuid":"148489480","full_name":"scriptingosx/desktoppr","owner":"scriptingosx","description":"Simple command line tool to set the desktop picture on macOS","archived":false,"fork":false,"pushed_at":"2024-07-19T14:57:51.000Z","size":1867,"stargazers_count":307,"open_issues_count":5,"forks_count":27,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-03-30T00:09:53.883Z","etag":null,"topics":["command-line","command-line-tool","desktop-picture","macadmin","macos","swift","terminal"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scriptingosx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-09-12T14:00:29.000Z","updated_at":"2025-03-26T02:19:04.000Z","dependencies_parsed_at":"2024-10-30T13:42:58.056Z","dependency_job_id":null,"html_url":"https://github.com/scriptingosx/desktoppr","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scriptingosx%2Fdesktoppr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scriptingosx%2Fdesktoppr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scriptingosx%2Fdesktoppr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scriptingosx%2Fdesktoppr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scriptingosx","download_url":"https://codeload.github.com/scriptingosx/desktoppr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419872,"owners_count":20936013,"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":["command-line","command-line-tool","desktop-picture","macadmin","macos","swift","terminal"],"created_at":"2024-07-31T16:02:16.735Z","updated_at":"2025-04-06T01:11:29.590Z","avatar_url":"https://github.com/scriptingosx.png","language":"Swift","readme":"# Here comes the `desktoppr`!\n\n![](https://img.shields.io/github/v/release/scriptingosx/desktoppr)\u0026nbsp;![](https://img.shields.io/github/downloads/scriptingosx/desktoppr/latest/total)\u0026nbsp;![](https://img.shields.io/badge/macOS-10.13%2B-success)\u0026nbsp;![](https://img.shields.io/github/license/scriptingosx/desktoppr)\n\nA simple command line tool which can read and set the desktop picture/wallpaper. Credit for the name to [Neil Martin](https://macadmins.slack.com/archives/C19MR7EM9/p1536586211000100).\n\nNote: Apple used to call the macOS background image 'desktop picture' until macOS 13 Ventura, when they changed to be the same as in iOS: 'wallpaper'. This documentation might use either term.\n\nI have written a few blog posts that describe different use strategies for setting a desktop picture:\n\n- [Using desktoppr in a managed environment](https://scriptingosx.com/2024/01/using-desktoppr-in-a-managed-environment/)\n- [Building a LaunchD Installer pkg for desktoppr (and other tools)](https://scriptingosx.com/2024/07/building-a-launchd-installer-pkg-for-desktoppr-and-other-tools/)\n- [Strategies to using desktoppr](https://scriptingosx.com/2020/03/strategies-to-using-desktoppr/)\n- [Random Desktop Background with desktoppr](https://scriptingosx.com/2020/04/random-desktop-background-color-with-desktoppr/)\n\n## Getting and setting the current desktop picture/wallpaper\n\nYou can read the current desktop picture/wallpaper with:\n\n```\n$ desktoppr\n/Library/Desktop Pictures/Sierra.jpg\n```\n\nand set the desktop picture with\n\n```\n$ desktoppr \"/Library/Desktop Pictures/BoringBlueDesktop.png\"\n```\n\nWhen you have multiple displays, `desktoppr` will list all desktop pictures:\n\n```\n$ desktoppr\n/Library/Desktop Pictures/HotStepper.jpg\n/Library/Desktop Pictures/LyricalGangster.jpg\n/Library/Desktop Pictures/MrOfficer.jpg\n```\n\nWhen you pass a file `desktoppr` will set it as the desktop picture for _all_ screens:\n\n```\n$ desktoppr /Library/Desktop Pictures/NaahNananah.jpg\n$ desktoppr\n/Library/Desktop Pictures/NaahNananah.jpg\n/Library/Desktop Pictures/NaahNananah.jpg\n/Library/Desktop Pictures/NaahNananah.jpg\n```\n\nYou can also set the desktop for a specific screen: (index starts at zero)\n\n```\n$ desktoppr 0 /Library/Desktop Pictures/HotStepper.jpg\n$ desktoppr 1 /Library/Desktop Pictures/LyricalGangster.jpg\n$ desktoppr 2 /Library/Desktop Pictures/MrOfficer.jpg\n```\n\n`desktoppr` can also control the image scaling and background color for the desktop picture.\n\nThe scale and color settings will be set for all screens.\n\nUse the `scale` verb to control how the desktops are scaled. It can have the values `fill` (default), `stretch`, `center`, or `fit`.\n\n```\n$ desktoppr scale center\n```\n\nYou can pass a hex string for the background color:\n\n```\n$ desktoppr color 000000      # black background\n$ desktoppr color FFFFFF      # white background\n$ desktoppr color FF0000      # red background\n```\n\nSetting the wallpaper, scale and/or color are separate commands.\n\nNote: setting the background color does not work in macOS 14.x. See [issue #22](https://github.com/scriptingosx/desktoppr/issues/22).\n\n## Downloading the wallpaper image file\n\nWhen you give a URL to an image file as the argument, `desktoppr` will download the file from the URL and set it as the wallpaper.\n\n```\n$ desktoppr https://raw.githubusercontent.com/scriptingosx/desktoppr/profile/examples/BoringBlueDesktop.png\n```\n\nThe downloaded file will be stored in `~/Library/Application Support/desktoppr/`.\n\nWhen the download fails, the wallpaper will not be changed. If the downloaded file is not an image file, the wallpaper will revert to the system default.\n\n## desktoppr in scripts\n\nWhen you want to run it from a script it is safest to include the entire path to the binary:\n\n```\n/usr/local/bin/desktoppr \"/Library/Desktop Pictures/BoringBlueDesktop.png\"\n```\n\nSince the `desktoppr` tool sets user preferences, you still need to pay attention that it runs as the user. A LaunchAgent or a solution like [`outset`](https://github.com/macadmins/outset) is a good choice to manage this. Alternatively, you can [run the command as the current user from a root script](https://scriptingosx.com/2020/08/running-a-command-as-another-user/).\n\n## Managing the desktop picture/wallpaper with a profile\n\nWhen you run `desktoppr` with the `manage` verb, it will read the settings from the `com.scriptingosx.desktoppr` preference domain. You can set these settings with the `defaults` command or, preferably, by pushing a configuration profile from an MDM server. \n\nThe idea is to run `desktoppr manage` with a LaunchAgent plist at login and/or at regular intervals. You can find [a sample LaunchAgent plist here](examples/com.scriptingosx.desktopprmanage.plist). The sample LaunchAgent will run `desktoppr manage` at login and every three hours (10800 sec). You can build a pkg that installs the desktoppr binary, the LaunchAgent plist and an image file very early in the deployment workflow and then desktoppr sets the desktop background when the user reaches the desktop for the first time.\n\nFor Ventura and higher, binaries and applications run by LaunchAgents need to be approved with a `com.apple.servicemanagement` profile so they appear as managed in the login items section in Settings.app. The [sample configuration profile](examples/desktoppr-profile.mobileconfig) contains those settings, as well.\n\n\ndesktoppr uses the following keys:\n\n#### `picture` (type: `string`)\n\nThe path to the image file for the desktop picture/wallpaper. The same image will be set for all screens.\n\nWhen the value starts with `http://` or `https://` desktoppr will interpret this as a URL and attempt to download a file and set that file as the desktop picture/wallpaper. The downloaded file will be stored in `~/Library/Application Support/desktoppr/`. You can have desktoppr verify the downloaded image file by providing  a `sha256` checksum.\n\n#### `sha256` (type: `string`)\n\nThis sha256 checksum will be used to verify the downloaded image file. If the checksum from the downloaded file does not match the value of this key, the desktop picture/wallpaper will not be changed.\n\nYou can generate the sha256 checksum of the image file with `shasum -a 256 \u003cfilepath\u003e`\n\n#### `color` (type: `string`)\n\nThis string will be interpreted as a six-digit hex code and set as the background color. (Note: setting the color [is broken on macOS 14.x](https://github.com/scriptingosx/desktoppr/issues/22).)\n\n#### `scale` (type: `string`)\n\nOne of `fill` (default), `stretch`, `center`, or `fit`. This controls the scaling behavior of the image.\n\n#### `setOnlyOnce` (type: boolean, default: `false`)\n\nWhen set to `true`, `desktoppr manage` will not re-set the desktop picture/wallpaper if the last picture `desktoppr manage` set was the same. Use this to set the desktop image/wallpaper once from a configuration profile but allow the user to change it afterward. Even when `desktoppr manage` runs frequently, it should only re-set the desktop picture/wallpaper when the setting in the configuration profile changes.\n\nWhen set to `false`, `desktoppr manage` will re-apply the managed settings every time.\n\nThe examples have [a sample defaults plist with keys](examples/defaults.plist) and [a sample configuration profile](examples/desktoppr-profile.mobileconfig).\n\n## Download\n\nYou can get the code for `desktoppr` on my Github page and an installer in the [Releases](https://github.com/scriptingosx/desktoppr/releases). The installer pkg will install the binary in `/usr/local/bin`. Alternatively, a brew cask exists, so you could install it using `brew install --cask desktoppr` if you have [Homebrew](https://brew.sh) installed.\n\nThe tool requires the [Swift 5 Runtime support for command line tools](https://support.apple.com/kb/DL1998) when you install it on versions of macOS older than 10.14.4.\n\n","funding_links":[],"categories":["Swift"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscriptingosx%2Fdesktoppr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscriptingosx%2Fdesktoppr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscriptingosx%2Fdesktoppr/lists"}