Skip to content
Command lineMaintenance

Maintenance

List and run the maintenance tasks, such as rebuilding Quick Look's cache or deleting local snapshots, and optimize the Mac in one step.

View as Markdown

census maintainRuns tasks

Usage

census maintain [TASK ...] [--yes] [--progress] [--json]

Without tasks, lists the maintenance tasks this Mac can run and what each would fix. With tasks, runs them in the order given, after [y/N] in a terminal.

OptionDescription
--yesRun without asking. Required without a terminal.
--progressWrite task progress as NDJSON to stderr
--jsonWrite one JSON response
Terminal
# The tasks, and what this Mac shows now
census maintain

# Run two of them (asks first)
census maintain open-with quicklook

The tasks

Every command a task runs is listed here and in census maintain --json. None needs an administrator yet.

TaskWhat it runs
quicklookqlmanage -r cache, then qlmanage -r
open-withlsregister -dump; lsregister -u for each registered app that is gone or in a Trash (at most 500 a run); lsregister -gc; then a second dump to confirm
finderkillall Finder, and open -b com.apple.finder if Finder hasn’t come back within 5 seconds
mailWith Mail quit and at least 5% of its index free: copies the index with VACUUM INTO next to it, runs PRAGMA integrity_check, VACUUM, PRAGMA wal_checkpoint(TRUNCATE) and PRAGMA integrity_check again, then removes the copy when the check says ok
fontsatsutil databases -removeUser. A restart finishes it.
snapshotstmutil deletelocalsnapshots / when tmutil listlocalsnapshotdates / lists any
ds-storedefaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true, and the same for DSDontWriteUSBStores. Logging out finishes it.

An unknown or repeated task is invalid_request, and nothing runs. Tasks that need an administrator (DNS, Spotlight, the icon cache) aren’t available yet.

The JSON

Without tasks, results.tasks[] describes each task: id, title, fixes, commands, admin, interrupts, restart, duration (seconds or minutes), optimize, state and last_run. state is {index_bytes, free_bytes} for mail, {count} for snapshots, {on} for ds-store, and null otherwise.

After running tasks, each entry has id, result and detail. result is done, unchanged, skipped (with a reason: app_running, needs_full_disk_access or cancelled) or failed (with exit_code). results.restart lists the tasks a restart finishes. A failed task makes the exit code 4 (maintenance_failed); the others still run.

Terminal
census maintain open-with --yes --json
JSON
{
  "schema_version": 5,
  "command": "maintain",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "results": {
    "tasks": [
      {
        "id": "open-with",
        "result": "done",
        "detail": "29 stale apps removed",
        "removed": [{ "display": "/Volumes/ChatGPT Installer/ChatGPT.app", "lossy": false }, "…"]
      }
    ],
    "restart": [],
    "audit": {
      "display": "/Users/me/Library/Application Support/census/audit/maintain-1790950000000.ndjson",
      "lossy": false
    }
  }
}

census optimizeDeletes

Usage

census optimize [SCOPE] [--yes] [--progress] [--json]

Cleans the safe tier and runs the quick maintenance tasks (quicklook and open-with), after one confirmation. It rescans like clean, shows the safe items and the tasks, and asks once. The safe items are deleted first, then the tasks run, then the review set is saved.

OptionDescription
--scope KINDdrive (the default) or data
-p, --path PATHClean only within this folder
--yesRun without asking. Required without a terminal.
--progressWrite scan, deletion and task progress as NDJSON to stderr
--jsonWrite one JSON response
Terminal
census optimize

The result is clean‘s, plus tasks and restart as in maintain. One audit log covers both. A failed task makes the exit code 4 (maintenance_failed) when no item failed.

Updated · census JSON schema 5