This page explains macOS-specific command behavior. The CLI reference documents shared syntax and flags; Local sources and Sparse artifact lifecycle explain source selection and refresh behavior.
Profiles and source
Profile-aware commands use --profile to select a macOS profile; otherwise they use the configured selection. init prepares local state and validates the selected source. It refreshes a configured remote source by default and does not install or activate software.
apply
Applies the selected profile’s Brewfile by installing missing declared packages. It does not upgrade unrelated installed software or activate Nix. Use nix switch separately to activate the nix-darwin system.
diff
Read-only comparison of Homebrew and Nix system state with the selected profile’s declarations. Differences or an unavailable comparison produce a nonzero exit status. See diff for output options.
nix
On macOS, nix operates on the nix-darwin system. It does not upgrade flake inputs as a separate step. Remote source refresh is enabled by default; --no-refresh uses the current local source. Successful actions publish related Nix lock state unless --no-push is supplied.
build
Builds the configured nix-darwin system without activating it.
switch
Builds and activates the selected nix-darwin system.
test
Test-builds the nix-darwin system without activating it.
dry-run
Runs the nix-darwin dry-run build without activating the system.
update
Upgrades installed Homebrew packages and publishes the observed Homebrew inventory unless --no-push is supplied. It does not reconcile the Brewfile; use apply to install missing declarations.
snapshot brew
Captures and pushes the observed Homebrew inventory without reconciling it against package declarations. See snapshot for syntax.
recover nix
Resumes and publishes an interrupted nix-darwin update from its saved recovery state. See recover for syntax.
The shared config, source, validate, status, sync, fonts, provision, and self-update pages cover the other available commands and subcommands.