cutlerv0.6.1 (Beta)

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

cutler aims to simplify your macOS setup experience into an "almost" one-command procedure. Define your settings once, then easily apply, track, and revert changes across your system—think of it as infrastructure-as-code for your Mac.

This website is just an overview of what cutler can do. In order to get a comprehensive guide on what cutler can do, please read the official README.

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

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

cutler init

Or, 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!

Shell Completions

Generate and install shell completion scripts for your shell:

# Bash
cutler completion bash > cutler.bash
mv cutler.bash ~/.bash-completion.d/

# Zsh
cutler completion zsh > _cutler
mv _cutler ~/.zfunc/

# Other shells like powershell, elvish and fish are also available.

Commands Reference

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.

Automate Homebrew

cutler eliminates manually installing packages by hand and using bundle files for storing their identifiers using just these two commands: 

# Backup installed casks and formulae
# This will update the config file you previously prepared
cutler brew backup

# Now, to install from it:
cutler brew install

External Commands

When you apply your defaults using cutler, you can also define custom external commands to be executed in a post-hook fashion: 

# A basic hello
[commands.greet]
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:
[vars]
common_args = ["Hello", "World"]
some_string = "Pancakes!"

[commands.greet]
run = "echo $common_args"
sudo = false

If you want to run them:

# combined execution
cutler exec

# or
cutler exec greet

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! :3

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