cutlerv0.4.7

Powerful, declarative settings management for your Mac, with speed.
GitHub Repo stars GitHub forks Crates.io Total Downloads

cutler simplifies macOS configuration by letting you manage system settings through a single TOML file instead of clicking through System Settings or typing complex defaults commands in the terminal.

Define your settings once, then easily apply, track, and revert changes across your system—think of it as infrastructure-as-code for your Mac.

⚠️ WARNING: Although cutler is solid enough for daily-driving, expect breaking changes before the v1 release.

Installation

Just a single brew command and you're ready to go!

brew install hitblast/tap/cutler

Or, use one of the following:

# Using cargo
cargo install cutler

# Using mise
mise use -g cargo:cutler

Architecture: The prebuilt binaries are compiled and shipped from macOS 14 on arm64. Intel Macs will require a manual compilation of the project.

Configuration

Create a config.toml file within one of the locations listed below and write your preferred settings following the defaults syntax. Check out the example configuration files to get started quickly! 

[dock]
tilesize = 46

[finder]
AppleShowAllFiles = true
CreateDesktop = false

[NSGlobalDomain]
ApplePressAndHoldEnabled = true

Or, to setup a comprehensive example on your Mac automatically, use this command: 

cutler init

Config file location: cutler looks for your configuration in these locations (in order):

Usage

cutler makes it super simple to apply, check, and revert your settings:

Apply your settings

cutler apply

This command applies all settings from your config file and restarts necessary system services.

Check current status

cutler status

Compares your configuration with current system settings.

Revert changes

cutler unapply

Removes all settings applied by cutler.

⚠️ Hard-reset settings

cutler reset --force

Resets every setting written in the config to factory defaults.
NOTE: This should ONLY be used as a fallback option to cutler unapply.

Manage configuration file

# Shows the contents of the configuration file
cutler config show

# Unapplies and deletes the configuration file
cutler config delete

Check for updates

cutler check-update

Snapshot file: When you run cutler apply, a snapshot file .cutler_snapshot is created in your home directory. This file records your configuration state and lets you revert to a previous setup if needed. Do not delete this file manually!

Add --verbose to any command for more detailed output about what's happening behind the scenes.

Advanced Features

When you apply your defaults using cutler, you can also define custom commands to be executed: 

[external]
  [[external.command]]
  cmd = "echo \"Hello World\""

This translates to running:

echo "Hello World"

For more complex scenarios, you can use a more advanced structure with separate arguments and variables: 

# Define reusable variables here:
[external.variables]
common_args = ["Hello", "World"]

[external]
  [[external.command]]
  cmd = "echo"
  # If you reference a variable (for example, $common_args) and it isn't defined
  # in the [external.variables] section, cutler will fall back and try to resolve it
  # from the environment (e.g. $PATH).
  args = ["$common_args", "$PATH"]
  sudo = false

This roughly translates to:

echo Hello World /usr/local/bin:/usr/bin:...

Some Personal Take

If you scroll around the GitHub Releases section, you will see more "personal takes" which are randomly written notes of mine to share some open thoughts.

Anyways, cutler is one of my favorite concurrent hobby projects right now. If you'd like to support me, consider starring this project!

⭐ View Source on GitHub 📚 macOS Defaults Reference
📖 API Reference