# 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.

## census maintain

**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.

| Option | Description |
| --- | --- |
| `--yes` | Run without asking. Required without a terminal. |
| `--progress` | Write task progress as NDJSON to stderr |
| `--json` | Write one JSON response |

```sh
# 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.

| Task | What it runs |
| --- | --- |
| `quicklook` | `qlmanage -r cache`, then `qlmanage -r` |
| `open-with` | `lsregister -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 |
| `finder` | `killall Finder`, and `open -b com.apple.finder` if Finder hasn't come back within 5 seconds |
| `mail` | With 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` |
| `fonts` | `atsutil databases -removeUser`. A restart finishes it. |
| `snapshots` | `tmutil deletelocalsnapshots /` when `tmutil listlocalsnapshotdates /` lists any |
| `ds-store` | `defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true`, and the same for `DSDontWriteUSBStores`. Logging out finishes it. |

> [!NOTE]
> `snapshots` deletes your Mac's local Time Machine snapshots, and `finder` stops any copy Finder is doing. To undo `ds-store`, run `defaults delete com.apple.desktopservices DSDontWriteNetworkStores` and the same for `DSDontWriteUSBStores`.

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.

```sh
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 optimize

**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.

| Option | Description |
| --- | --- |
| `--scope KIND` | `drive` (the default) or `data` |
| `-p, --path PATH` | Clean only within this folder |
| `--yes` | Run without asking. Required without a terminal. |
| `--progress` | Write scan, deletion and task progress as NDJSON to stderr |
| `--json` | Write one JSON response |

```sh
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.