cutler

Declarative macOS settings management at your fingertips, with speed.

# Install via Homebrew.
brew install hitblast/tap/cutler

Table of Contents

• Overview
• Other Installation Methods
• Usage
• Resources
• Notable Things
• Contributing
• License

Overview

Most of us, who use macOS, either configure it using the built-in System Settings app, or the defaults command-line tool. Both of these options are tedious and the latter requires manual tinkering with the settings inside a terminal. cutler is a project which solves just that!

cutler is a simple, command-line tool that lets you define your macOS system preferences in a TOML file. It wraps the defaults command, giving you an easy way to apply or reverse settings on the go.

Check out the Usage section for more details.

Other Installation Methods

In addition to using Homebrew (as shown above), there are a couple more methods to install cutler:

• Using cargo:

cargo install cutler

• Using mise:

mise use -g cargo:cutler

Usage

cutler reads your configuration from a config.toml file, which can live in one of these locations:

• $XDG_CONFIG_HOME/cutler/config.toml or,
• ~/.config/cutler/config.toml

It even respects $XDG_CONFIG_HOME so you don't have to worry about path issues. Just drop your config.toml file in one of these spots and you're ready to go.

Here’s what a basic TOML configuration looks like:

[dock]
tilesize = 46

[menuextra.clock]
FlashDateSeparators = true

For more details on the different defaults domains and values available for macOS, check out the Resources section. The TOML above effectively translates to these commands:

defaults write com.apple.dock "tilesize" -int "46"
defaults write com.apple.menuextra.clock "FlashDateSeparators"

You can also set options for NSGlobalDomain like this:

[NSGlobalDomain]
ApplePressAndHoldEnabled = true

[NSGlobalDomain.com.apple.mouse]
linear = true

cutler will translate the following TOML to:

defaults write NSGlobalDomain "ApplePressAndHoldEnabled" -bool true
defaults write NSGlobalDomain com.apple.mouse.linear -bool true

Note that if you run cutler apply for the first time without a configuration file, it will generate a sample config for you. You can also take a look at examples/cutler.toml for a full example.

Once you’ve set up your file, apply your settings with:

cutler apply

Now, sometimes you might want to check the integrity of the applied settings - whether they're applied correctly or have been reverted/modified. In order to check, run:

cutler status

To unapply all modifications, run:

cutler unapply

And if you want to completely remove your configuration file (note: this might make it harder to keep track of your settings), run:

cutler delete

You can use --verbose to see more details about the behind-the-scenes command execution. More information about all of the commands can be found by running cutler help.

Notable Things

When the cutler apply command is run, a snapshot file (.cutler_snapshot) will be created at your $HOME directory. It is used to keep track of the configuration state and can be used to revert to a previous state if needed. It is essential that this file is not manually overwritten or deleted, as it is crucial for maintaining the integrity of your configuration.

Resources

Finding the perfect set of defaults can be a bit of a hassle. Check out the "macOS defaults" website for a comprehensive list of settings.

Contributing

This is a passion project of mine to simplify the repetitive task of setting up my MacBook. Pull requests are always welcome! Feel free to contribute by creating a pull request or submitting an issue.

License

This project is licensed under the MIT License.