defaults-rs 1.2.1

Open-source interface to a user's defaults on macOS
Documentation

🍎 defaults-rs

Open-source interface to a user's defaults on macOS

Crates.io Total Downloads Refactor CI

Key Features

  • Read, write, delete, rename, import/export, and inspect preferences.
  • Supports user/global/path domains.
  • Supports all plist value types (API).
  • Pretty-printing and better logging than the original defaults tool.
  • Execution safety. Never accidentally write to a faulty domain again.
  • Dynamically chooses between XML and binary PLIST data formats.
  • Extremely small (<1.5k SLoC).

Table of Contents

Installation

Using brew:

$ brew install hitblast/tap/drs

Using cargo:

$ cargo install defaults-rs

Using mise:

# NOTE: This will compile the binary for your system.
$ mise use -g cargo:defaults-rs

Usage

The CLI command is drs. It closely mimics the original defaults tool.

Read a key (domain or path)

$ drs read com.apple.dock tilesize
$ drs read ~/Library/Preferences/com.apple.dock.plist tilesize
$ drs read com.apple.dock.plist tilesize   # this also works!

Write a key

$ drs write com.apple.dock tilesize -i 48
$ drs write com.apple.dock tilesize --int 48
$ drs write ~/Library/Preferences/com.apple.dock.plist tilesize --int 48

# create a new domain (disables checks)
$ drs write rubberduck --force duckcount --int 5

Delete a key

$ drs delete com.apple.dock tilesize
$ drs delete ~/Library/Preferences/com.apple.dock.plist tilesize

Read the whole domain

$ drs read com.apple.dock
$ drs read ~/Library/Preferences/com.apple.dock.plist

List all entries in all domains containing word

$ drs find <word>

View / fuzzy-read domains

$ drs domains

# disable fuzzy-searching with the -n/--no-fuzzy flag
$ drs domains -n

Use the global domain

$ drs read -g com.apple.keyboard.fnState
$ drs write -g InitialKeyRepeat --int 25

Read the type of a key

$ drs read-type com.apple.dock tilesize

Rename a key

$ drs rename com.apple.dock oldKey newKey
$ drs rename ~/Library/Preferences/com.apple.dock.plist oldKey newKey

Import/export a domain

$ drs import com.apple.dock ./mysettings.plist
$ drs export com.apple.dock ./backup.plist

Rust API Usage

In order to use the Rust API for defaults-rs, run this command in your project directory:

$ cargo add defaults-rs --no-default-features

Please refer to the API reference for more information about all the available functions.

For examples, check out: examples/

Why defaults-rs

defaults-rs was initially made with the necessity of a thin wrapper around the CoreFoundation APIs which are responsible for storing a user's defaults. Now, it also serves as a backend for directly interfering with system preferences in the cutler project.

Caveats

Some temporary limitations include:

  • .plist files for applications (Info.plist specifically) cannot be read by this tool as of now, although this is planned for the next release.

And since this is a completely open-source attempt to replicate the capabilities of defaults (which is a proprietary software), there will be certain limitations:

  • Domain-reading might result in showing slightly "less" output in very rare cases where parts of the domain is overridden by the system (e.g. com.apple.Safari). defaults-rs attempts to read in the Current User + Any Host space for the maximum achievable domain index. This is not a threat to I/O operations so it's not really much of a caveat.

Contributing

New pull requests and issues are always welcome. Please read the contribution guidelines for more information about certain parts of the codebase and/or how to form a structured pull request.

License

This project has been licensed under the MIT License.