defaults-rs

Near drop-in replacement for the macOS defaults CLI with API bindings for Rust

Table of Contents

• Key Features
• Installation
• CLI Usage
• Rust API
• License

Key Features

• CLI (drs): Use it as a direct replacement for defaults without hassle.
• Async Rust API: Read, write, delete, rename, import/export, and inspect preferences from Rust code.
• Supports: User and global domains, all plist value types (int, float, bool, string, arrays, dictionaries).
• Familiar Style: Pretty-prints plist data close to the original defaults format.
• Binary & XML Plist: Handles both binary and XML plist files transparently.
• Extensible: Designed for easy addition of new commands and value types.

Installation

Using brew:

brew install hitblast/tap/drs

Using cargo:

cargo install defaults-rs

Manual Build & Install

cargo install --git https://github.com/hitblast/defaults-rs

CLI Usage

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

Examples

Read a key

drs read com.apple.dock tilesize

Write a key

drs write com.apple.dock tilesize -i 48
# or
drs write com.apple.dock tilesize --int 48

Delete a key

drs delete com.apple.dock tilesize

Read the whole domain

drs read com.apple.dock

List all entries in all domains containing word

drs find <word>

View all domains

drs domains

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

Import/Export a domain

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

Rust API

To access the developer-side API for defaults-rs, run the following command and add it to your Cargo project:

cargo add defaults-rs

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

Example

use defaults_rs::{Domain, PrefValue, Preferences};

#[tokio::main]
async fn main() {
    // Read a value
    let value = Preferences::read(Domain::User("com.apple.dock".into()), Some("tilesize"))
        .await
        .unwrap();

    // Write a value
    Preferences::write(
        Domain::User("com.apple.dock".into()),
        "tilesize",
        PrefValue::Integer(48),
    )
    .await
    .unwrap();

    // Delete a key
    Preferences::delete(Domain::User("com.apple.dock".into()), Some("tilesize"))
        .await
        .unwrap();
}

For writing domains in batches, you can use the batch-write function:

use defaults_rs::{Domain, PrefValue, Preferences};

#[tokio::main]
async fn main() {
    let batch = vec![
        (
            Domain::User("com.apple.dock".into()),
            vec![
                ("tilesize".into(), PrefValue::Integer(48)),
                ("autohide".into(), PrefValue::Boolean(true)),
            ],
        ),
        (
            Domain::User("com.apple.keyboard".into()),
            vec![
                ("InitialKeyRepeat".into(), PrefValue::Integer(25)),
            ],
        ),
    ];
    Preferences::write_batch(batch).await.unwrap();
}

License

This project has been licensed under the MIT License.