Add wallpaper and icon-layout commands#714
Open
aluedeke wants to merge 1 commit into
Open
Conversation
Adds four CLI commands for managing iOS home-screen state on supervised devices, reverse-engineered from cfgutil set-wallpaper and the springboardservices RPC. - ios set-wallpaper <image> [--screen=lock|home|both] --p12file=... Sends the MDM "Settings" command with item "Wallpaper" over the post- Escalate MCInstall channel, matching cfgutil's wire format. iOS 16+ unifies lock and home wallpapers as a paired set, so --screen is preserved for older-iOS / forward-compat (cfgutil behaves identically). - ios get-wallpaper [--output=wallpaper.png] Pulls the home-screen wallpaper PNG via springboardservices. Does not require supervision; lock screen is not exposed by iOS. May EOF on iOS 18 (matches pymobiledevice3 #1450). - ios get-icon-layout [--output=...] / ios set-icon-layout <file> Round-trippable JSON capture/restore of the home-screen layout via springboardservices getIconState/setIconState. Documented constraint: every installed app must occupy a slot (per cfgutil docs) and the iOS 14+ Edit-Pages hidden-page bit is not exposed by the RPC. The supervised handshake (Escalate / EscalateResponse / ProceedWithKeybagMigration) reuses the existing mcinstall.EscalateWithCertAndKey path, so no new crypto is added. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds four CLI commands for inspecting and modifying iOS home-screen state on supervised devices, reverse-engineered from Apple Configurator's
cfgutil set-wallpaperand thecom.apple.springboardservicesRPC.ios set-wallpaper <image> [--screen=lock|home|both] --p12file=... [--password=...]— sets the device wallpaper. Sends the MDMSettingscommand with itemWallpaperover the post-Escalatecom.apple.mobile.MCInstallchannel, exactly matching cfgutil's wire format (verified by DTrace).ios get-wallpaper [--output=wallpaper.png]— pulls the home-screen wallpaper PNG viaspringboardservices. No supervision required.ios get-icon-layout [--output=…]/ios set-icon-layout <file>— round-trippable JSON capture/restore of the home-screen layout (getIconState/setIconState).The supervised auth handshake (Escalate / EscalateResponse / ProceedWithKeybagMigration) reuses the existing
mcinstall.EscalateWithCertAndKeypath; no new crypto is added.Behavior caveats (documented in CLI help and Go doc-comments)
Wherefield. Apple's own cfgutil exhibits the same behavior. The--screenflag is preserved for older iOS / forward-compat.get-wallpapermay EOF on iOS 18: known iOS-side regression also seen in pymobiledevice3 (doronz88/pymobiledevice3#1450). Code is correct.set-icon-layoutconstraint: iOS requires every installed app to occupy a slot. Per cfgutil docs: "unexpected behavior may occur if the given layout does not contain every icon on the device". Missing apps are re-paginated, not hidden.Test plan
go build ./...clean (only my touched packages; existing untrackedios/resign/WIP excluded)go vet ./ios/mcinstall ./ios/springboard ./cleanset-wallpaperend-to-end on a real supervised iPhone SE (iOS 18.7.1) — wallpaper changes verified visually--screen=lock|home|bothall return"ok"; behavior matches cfgutil exactly (both screens get set on iOS 16+, unavoidable)get-icon-layout→set-icon-layoutround-trip on real device returns"ok", layout preserved--screen, missing--p12file,P12_PASSWORDenv-var fallback, all behave correctlyget-wallpaperon iOS < 18 (no test device available)🤖 Generated with Claude Code