zero-sh/apply-user-defaults

A small utility to set macOS user defaults declaratively from a YAML file.

apply-user-defaults

apply-user-defaults is a small utility to set macOS user defaults declaratively from a YAML file.

Usage

To use, simply structure a YAML file like the following:

com.apple.dock:
  # System Preferences > Dock > Automatically hide and show the Dock.
  autohide: true

  # System Preferences > Dock > Minimize windows using: Scale effect.
  mineffect: "scale"

  # System Preferences > Dock > Show indicators for open applications.
  show-process-indicators: false

  # System Preferences > Dock > Size.
  tilesize: 72

Then apply it using:

$ apply-user-defaults path-to-file.yaml

You can also see what commands are being run by enabling verbose output:

$ apply-user-defaults path-to-file.yaml --verbose
==> defaults write com.apple.dock autohide -bool true
==> defaults write com.apple.dock mineffect -string scale
==> defaults write com.apple.dock show-process-indicators -bool false
==> defaults write com.apple.dock tilesize -int 72
Success! Applied defaults.

Template Expansion

Environment variables can also be included using shell parameter expansion syntax. For example:

com.apple.finder:
  # Finder > Preferences > New Finder windows show > Home directory.
  NewWindowTargetPath: "file://${HOME}"

will evaluate to:

defaults write com.apple.finder NewWindowTargetPath -string "file://$HOME"

where $HOME is the value contained in the HOME environment variable.

This only applies when the string in the YAML file begins with a dollar sign and is wrapped in braces (just using $HOME won't work).

To disable, you may pass the flag --no-env or escape the dollar sign, e.g. '\\${VALUE}'.

Installation

Pre-compiled binaries are available on the releases page.

Homebrew

If you're using Homebrew, you can install with a custom tap:

$ brew install zero-sh/tap/apply-user-defaults

Cargo Install

To install via Cargo, run:

$ cargo install apply-user-defaults

Building from Source

To build from source:

$ git clone https://github.com/zero-sh/apply-user-defaults.git
$ cd apply-user-defaults
$ cargo run -- path-to-file.yml --verbose

License

This project is licensed under either the Apache-2.0 or MIT license, at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

apply-user-defaults's Issues

make a backup of current user defaults

Hello. I already changed a lot of user defaults. I would like to save these changes too. Since I don't remember all the settings, that I changed. It would be nice to generate yaml from current user defaults. is it possible to make this by read option?

Diff between current state and declared state

It would be cool if we were able to see a diff between the current configuration applied to the system, and the declared state within the config file, so we can see if it has been fully applied, and if not, what differs. I'd imagine this being done with something akin to defaults read

apply-user-defaults should handle array values

Cider storage of defaults and applying defaults doesn't appear to support arrays.

Example usage:
defaults write com.apple.dock persistent-apps -array-add '{"tile-type"="spacer-tile";}'

My intention is to be able to save new persistent applications into the Dock.
Since my common usage of Cider is when installing new macOS versions which keep changing the default value of com.apple.dock persistent-apps, I don't want cider apply-defaults to erase the entire persistent-apps value.

Issue reported by @RogerThiede, migrated from msanders/cider#51.