Providers

With upgrade: true, the plan has one UPDATE per outdated declared package, such as upgrade with brew, 3.7c to 3.8. Without it, nothing is upgraded. A manager that cannot report newer versions gets one MANUAL step instead.

capture writes a Brewfile (tap, brew, cask and mas lines) or a package list from the "installed on purpose" reads. Dependencies are left out, since the manager pulls them in again.

Taps are installed before the formulae that need them.

Other Brewfile entries, such as vscode or go, are MANUAL: the plan names them, and you install them yourself.

mas entries are MANUAL until mas is installed.

If the manager itself is missing, the plan is one MANUAL step to install it.

An app installed outside the manager is not seen. Its cask is installed with --adopt, so Homebrew takes over the app already there; if the app differs from the cask, Homebrew refuses, and you delete the app or remove the entry.

The plan lists one CREATE per tool@version that is not installed, such as java@temurin-25.

Apply runs mise install in the config’s directory.

In the inventory, each runtime shows the version mise resolved next to the one requested, such as 24.21.0 for lts, and the newer version mise outdated reports. Versions installed but asked for by no config in this target, such as a global tool or an old node, show as not declared.

With upgrade: true, the plan has one UPDATE per outdated runtime. Apply runs mise upgrade for that tool@request in the config’s directory, so a pin such as 3.13 moves only within 3.13.

capture writes a [tools] table of every installed version, using the request when mise knows it.

mise refuses to read a config it does not trust. The plan then shows a MANUAL step: read the file, then run mise trust.

doctor checks that the shell runs each command from mise, not from another copy earlier on PATH, such as Homebrew’s node. The fix is to activate mise last in the shell profile.

Wallpaper. macOS keeps one picture for every Space on every display, in its wallpaper store, ~/Library/Application Support/com.apple.wallpaper/Store/Index.plist. System Events sees only the Spaces in view, so the plan reads the store itself, with a small JavaScript for Automation script run by osascript. If any Space shows another picture, the plan has one UPDATE. Apply sets the picture through System Events, rewrites every Space in the store, and restarts WallpaperAgent so the desktops redraw. The first run asks you to let your terminal control System Events. Another tool that also sets the wallpaper, such as a login agent, will undo this; turn it off.

Accent. accent is one of blue, purple, pink, red, orange, yellow, green or graphite. The plan reads AppleAccentColor with defaults; apply writes it and the matching AppleHighlightColor. Apps show the new colour once they restart; log out to see it everywhere.

Screen saver. The page, with the fonts and images its CSS loads from its folder inlined, becomes one data: URL. The plan compares it with the saver’s default page, WVSSDefaultAddressURL in the saver’s Info.plist, read with plutil. If they differ, apply writes it there with plutil and signs the saver again, ad hoc, with codesign. The saver shows its default page while its own list of pages, set in its Options, is empty.

If WebViewScreenSaver is not installed, in ~/Library/Screen Savers or /Library/Screen Savers, the plan is a MANUAL step: run assets/screensaver/build-saver.sh. It builds the saver from source with Xcode and installs it for you. The Homebrew cask is disabled, because the release build fails the Gatekeeper check; a local build is not quarantined.

Choosing WebViewScreenSaver as the screen saver is yours to do, once, in System Settings, Screen Saver. macOS keeps that choice where no tool should write it.

A file that does not exist, such as a wallpaper not rendered yet, is a MANUAL step.

The plan reads each key with defaults read. A key that is not set is a CREATE; one with another value is an UPDATE. Apply writes it with the type of the YAML value: -bool, -int, -float or -string.

The Dock, Finder and the screenshot settings are read only when their process starts, so a change to com.apple.dock, com.apple.finder or com.apple.screencapture adds an action that restarts it.

A key the config stops declaring keeps its value. Some keys need a logout to take effect.

The plan reads each key with gsettings get and compares values whatever the type gsettings prints, so uint32 250 matches 250.

Apply runs gsettings set with the value as GVariant text: a string is quoted, a list becomes an array of strings. GNOME applies a change at once; nothing restarts.

A schema or key GNOME does not know is a CREATE whose apply fails with gsettings' message.

Only keys under HKCU (or HKEY_CURRENT_USER): the user’s own settings, which need no administrator. Quote a key in single quotes, so YAML keeps its backslashes.

The plan reads each value with reg query. A bool or an integer is a REG_DWORD, so false matches 0x0; a string is a REG_SZ. A string starting with ~/ is a path in your home folder.

Apply runs reg add with the type. Windows applies most values at once; Explorer reads some only when it starts, so sign out to see them.

A service is in place when brew services list shows it started, or scheduled for one that runs on a timer. Otherwise apply runs brew services restart, which starts it at every login and recovers one that failed.

An agent is in place when launchctl print gui/<uid>/<label> finds it; the label is the file name without .plist. Otherwise apply loads it with launchctl bootstrap. The plist can come from a dotfiles target listed earlier in the config, which writes it first.

A changed plist is not reloaded. Reload it from a chezmoi run_onchange_ script that hashes the plist.

A unit is in place when systemctl --user show reports it enabled and active; a timer is active while it waits for its next run.

Otherwise apply runs systemctl --user daemon-reload, then systemctl --user enable --now with the file’s path, which links in a unit that lives outside systemd’s folders.

services works on Linux too: Homebrew on Linux runs brew services on systemd.

The task’s name is the file name without .xml. It is in place when Get-ScheduledTask finds it and it is not disabled; PowerShell reports the state in English whatever the system language.

A missing task is registered with Register-ScheduledTask from the file, in whatever encoding it has. A disabled one is enabled.

A changed file is not registered again. Re-register it by hand, or from a chezmoi run_onchange_ script that hashes the file.

keyd itself comes from your packages: keyd on Debian 13 and Ubuntu 25.04 or later, which name the program keyd.rvaiya, or the keyd COPR on Fedora. Until it is installed the plan shows a MANUAL step.

The plan compares the file byte for byte. Apply copies it with sudo install -m 644, then runs keyd reload when keyd is running.

keyd is in place when systemctl show keyd reports it enabled and active; otherwise apply runs sudo systemctl enable --now keyd.

A server is set by name in mcpServers; every other key in the file stays as it was. Each file is replaced in one rename, read again just before the write, so an agent writing it in between keeps its change.

Codex reads TOML. Its servers live in a marked block of config.toml. A server Codex already declares outside the block is a MANUAL step, since a table declared twice breaks the file. An env value written ${NAME} becomes an env_vars entry, which Codex passes through from your shell.

The rules file lands in a marked block, so what you wrote around it stays.

A skill is in place when every file in its folder matches.

A model is in place when ollama list shows it; otherwise apply runs ollama pull. ollama serve must be running. list shows each model.

Keep keys out of the file: write ${NAME} and keep the value in the keychain or a password manager. doctor warns about plain-text keys.