Utilities

Syntax

• The command is the first argument that is neither an option nor an option’s value, and options may come before it: census --json top is census top --json. With no command, census runs scan.
• A word that isn’t a command is a folder to scan only if it’s written as a path (it contains /, or starts with ~ or .) or names a file or folder that exists. Otherwise it’s an error, and nothing runs:

census tpo

unknown command: tpo (did you mean top?)

• --name=value works for every option that takes a value. An option without a value rejects one: --json=1 is an error.
• An option that takes a value is given once. --path A --path B is an error, never “the last one wins”.
• An unknown option names the help that lists the right ones: unknown option: --limit (see census help breakdown).
• Sizes such as --min-size 500K take bytes or a number followed by K, M or G, in powers of 1000.

census helpRead-only

Shows every command’s usage line, or one command’s options. --help and -h work too, after any command. Help is plain text, never JSON.

# Every command
census help

# One command's options
census help top
census top --help

census accessRead-only

Shows whether this process has Full Disk Access. macOS grants it to an app, and census inherits it from the app or terminal that started it, so the answer is about where you run census.

census access --json

results is {status, probes}. status is granted, not_granted or unknown (nothing to probe), and each probe is {path, readable, errno}. The exit code is 0 in every case. See Full Disk Access.

census versionRead-only

Prints the package and schema versions. --version and -V do the same, with --json too.

census version --json

{
  "schema_version": 5,
  "command": "version",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "scan": null,
  "results": { "version": "0.1.0", "schema_version": 5 }
}

census selftestRead-only

Compares incremental rescans with full scans in a temporary folder, to check that rescans on this Mac see every change.

census selftest --json

{
  "schema_version": 5,
  "command": "selftest",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "results": {
    "scenarios": [
      {
        "detail": "",
        "full_ms": 5,
        "incremental_ms": null,
        "name": "first scan",
        "number": 0,
        "reread": null,
        "status": "passed"
      },
      "…"
    ]
  }
}

If any scenario fails, status is failed, the exit code is 2, and errors has one selftest_failed entry. On a volume without file system event history, such as some external disks, every incremental scenario fails.

census servePer request

Answers requests on stdin, one JSON object per line, and writes responses to stdout the same way. The Disk Census app runs it, and any program can: scans it has read stay in memory, so queries answer in milliseconds. See census serve for the protocol.

printf '%s\n' '{"id":1,"args":["version"]}' | census serve