CLI Reference

Complete documentation for all macprefs commands and flags.

Commands

`preflight`

Checks write access to user Preferences, runs a safe defaults write/delete smoke test, and warns if MDM profiles are present. No permanent changes are made.

macprefs preflight [--config <config>]

Flag	Description
`-c, --config <config>`	Path to config JSON (optional, validates if provided)
`--version`	Show the version.
`-h, --help`	Show help information.

Exit codes:

0 — All checks passed
2 — One or more issues detected

`list`

Lists all preference domains, or keys within a specific domain.

macprefs list [--domain <domain>] [--format <format>]

Flag	Description
`--domain <domain>`	Show keys within this domain instead of listing domains
`--format <format>`	Output format (table
`--version`	Show the version.
`-h, --help`	Show help information.

`inspect`

Shows current values for preferences across all domains by default.

macprefs inspect [--domains <domains>] [--keys <keys>] [--format <format>]

Flag	Description
`--domains <domains>`	Comma-separated domains to inspect
`--keys <keys>`	Comma-separated keys to filter
`--format <format>`	Output format (table
`--version`	Show the version.
`-h, --help`	Show help information.

`export`

Exports macOS preferences to a JSON configuration file across all domains by default.

macprefs export <output-file> [--domains <domains>] [--baseline] [--no-progress]

Arguments:

<output-file> — Output JSON file path (required)

Flag	Description
`--domains <domains>`	Comma-separated domains to include (defaults to all domains)
`--baseline`	Compare against baseline (v1.1)
`--no-progress`	Suppress progress output (for CI/scripting)
`--version`	Show the version.
`-h, --help`	Show help information.

`validate`

Checks that a config file is valid JSON with correct structure.

macprefs validate [--config <config>] [--format <format>]

Flag	Description
`-c, --config <config>`	Path to config JSON
`--format <format>`	Output format (table
`--version`	Show the version.
`-h, --help`	Show help information.

`plan`

Shows what changes would be made without applying them. Read-only operation.

macprefs plan [--config <config>] [--format <format>] [--verbose] [--filter <filter>]

Flag	Description
`-c, --config <config>`	Path to config JSON
`--format <format>`	Output format (table
`-v, --verbose`	Show all changes in detail
`--filter <filter>`	Filter changes: conflicts, additions, all
`--version`	Show the version.
`-h, --help`	Show help information.

Exit codes:

0 — No changes needed (in sync)
2 — Changes detected (drift found)

`apply`

Applies config changes. Creates snapshot before any changes.

macprefs apply [--config <config>] [--yes] [--rollback-on-fail] [--no-rollback-on-fail] [--verbose]

Flag	Description
`-c, --config <config>`	Path to config JSON
`--yes`	Auto-confirm apply (for CI/CD)
`--rollback-on-fail`	Rollback on failure (default: enabled)
`--no-rollback-on-fail`	Disable rollback on failure
`--verbose`	Verbose output
`--version`	Show the version.
`-h, --help`	Show help information.

Exit codes:

0 — Changes applied successfully (or no changes needed)
1 — Apply failed

`rollback`

Restores preferences to their state before an apply operation.

macprefs rollback [--run-id <run-id>]

Flag	Description
`--run-id <run-id>`	Specific run ID to rollback (default: most recent)
`--version`	Show the version.
`-h, --help`	Show help information.

`about`

Show version and system information.

macprefs about

Flag	Description
`--version`	Show the version.
`-h, --help`	Show help information.

Documentation auto-synced from macprefs CLI help.