What is macfig and what can it do?

macfig is a macOS defaults manager that can read, write, reset, search, backup, diff, export, import, and apply presets to macOS system preferences.

Should I back up before making changes?

Yes—Always run macfig backup before applying presets or bulk changes to enable safe restoration.

How do I revert changes if something goes wrong?

Use macfig restore to revert to a previous state, or use macfig reset to restore specific keys to defaults.

macfig

npx machina-cli add skill lu-zhengda/macos-toolkit/macfig --openclaw

Files (1)

SKILL.md

4.1 KB

macfig — macOS Defaults Manager

Browse macOS hidden defaults:

!macfig list $ARGUMENTS 2>&1 || echo "macfig not installed — brew install lu-zhengda/tap/macfig"

Analyze the output above. If showing categories, explain what each controls. If showing settings, explain each and its current value. Offer to change settings or apply presets. Always recommend macfig backup before changes.

Commands

Command	Purpose	Example
`macfig list`	List preset categories	`macfig list`
`macfig list <category>`	Show settings in category with current values	`macfig list dock`
`macfig get <domain> <key>`	Read a specific defaults value	`macfig get com.apple.dock autohide`
`macfig set <domain> <key> <value>`	Write a defaults value	`macfig set com.apple.dock autohide true`
`macfig preset <name>`	Apply a named preset bundle	`macfig preset dev-setup`
`macfig backup`	Backup all tracked settings to JSON	`macfig backup`
`macfig restore <file>`	Restore from backup file	`macfig restore ~/.config/macfig/backup.json`
`macfig reset <domain> <key>`	Delete a key (restore macOS default)	`macfig reset com.apple.dock autohide`
`macfig search <query>`	Search keys across all domains	`macfig search animation`
`macfig diff <backup>`	Compare current state against a backup	`macfig diff ~/.config/macfig/backup.json`
`macfig export [file]`	Export all tracked defaults to JSON	`macfig export defaults.json`
`macfig import <file>`	Import and apply defaults from JSON	`macfig import defaults.json`
`macfig watch <domain> <key>`	Monitor a defaults key for changes	`macfig watch com.apple.dock autohide`

Diff and Migration

Compare current settings against a backup to see what changed:

macfig backup
# ... make changes ...
macfig diff ~/.config/macfig/backup.json

Export and import defaults for machine migration:

# Export from old machine
macfig export my-defaults.json

# Import on new machine
macfig import my-defaults.json

Watch Mode

Monitor a specific defaults key for live changes:

macfig watch com.apple.dock autohide

Useful for debugging preference changes made by apps or System Settings.

JSON Output

Add --json to any read command for machine-readable output:

macfig list --json
macfig list dock --json
macfig get com.apple.dock autohide --json
macfig search animation --json
macfig diff backup.json --json
macfig export --json

Built-in Presets

Preset	Effect
`dock-speed`	Faster Dock animations and autohide delay
`finder-dev`	Show hidden files, extensions, path bar, status bar
`keyboard-fast`	Faster key repeat rate and shorter delay
`no-animations`	Disable most macOS animations
`privacy`	Disable analytics, Siri suggestions, ad tracking
`dev-setup`	Combined developer-friendly defaults

Safety Guidelines

Always backup first: Run macfig backup before applying presets or bulk changes
Use presets over raw set: Presets handle type inference and process restart automatically
Use search to discover: Run macfig search <term> instead of guessing domain/key pairs
Revert with restore: If something breaks, macfig restore <backup-file> reverts all changes
Diff before import: Run macfig diff to preview changes before applying an import

TUI Mode

Launch macfig without arguments for interactive mode — browse categories, toggle settings, and preview changes.

Source

git clone https://github.com/lu-zhengda/macos-toolkit/blob/main/skills/macfig/SKILL.mdView on GitHub

Overview

macfig is a macOS defaults manager to read, write, backup, and apply system preferences. It exposes commands to list, get, set, export, import, diff from backups, and apply built-in presets for common configurations.

How This Skill Works

macfig tracks a set of domains and keys and provides a CLI to read (get/list), write (set), and reset values. It supports backup and restore to JSON, diffing current state against backups, exporting/importing for migration, and applying presets that bundle multiple changes. It also offers watch mode to monitor specific preference keys in real time.

When to Use It

You want to adjust Dock behavior, such as speed or autohide, using presets or direct set commands.
You need to reveal Finder hidden files or tweak Finder-related preferences.
You are backing up macOS defaults, exporting/importing them for migration, or diffing changes against a backup.
You prefer using built-in presets (e.g., dock-speed, finder-dev, dev-setup) over manual key-by-key changes.
You want to monitor or audit preference changes in real time with watch.

Quick Start

Step 1: macfig backup
Step 2: macfig list dock to review current values
Step 3: macfig preset dock-speed

Best Practices

Always run macfig backup before applying changes.
Prefer presets over manual set when suitable to ensure proper typing and required restarts.
Use macfig get to verify the exact value after a change.
Use macfig diff to see what changed compared with a backup.
If something goes wrong, revert with macfig restore <backup-file> or reset keys as needed.

Example Use Cases

Backup current settings, then apply the 'dock-speed' preset to speed up Dock animations.
Enable Finder dev options with the 'finder-dev' preset to show hidden files and additional UI elements.
Export all tracked defaults to defaults.json for seamless migration to a new Mac.
Diff current settings against backup.json to audit unintended changes.
Watch the autohide key for com.apple.dock to debug app-initiated changes.

Frequently Asked Questions

Add this skill to your agents