---
title: "Command guide"
description: "macOS-specific behavior for Homebrew reconciliation, Nix operations, inventory capture, and recovery."
---

> Documentation Index
> Fetch the complete documentation index at: https://outfitting.jfa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Command guide

This page explains macOS-specific command behavior. The [CLI reference](/docs/cli/) documents shared syntax and flags; [Local sources](/docs/source/local-sources/) and [Sparse artifact lifecycle](/docs/source/sparse-artifacts/) 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`](/docs/cli/nix/) 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`](/docs/cli/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`](/docs/cli/snapshot/) for syntax.

## `recover nix`

Resumes and publishes an interrupted nix-darwin update from its saved recovery state. See [`recover`](/docs/cli/recover/) for syntax.

The shared [`config`](/docs/cli/config/), [`source`](/docs/cli/source/), [`validate`](/docs/cli/validate/), [`status`](/docs/cli/status/), [`sync`](/docs/cli/sync/), [`fonts`](/docs/cli/fonts/), [`provision`](/docs/cli/provision/), and [`self-update`](/docs/cli/self-update/) pages cover the other available commands and subcommands.

Source: https://outfitting.jfa.dev/docs/platforms/macos/commands/index.mdx