# Utilities

> Command syntax and help, Full Disk Access checks, versions, the self-test, and census serve.

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

```sh
census tpo
```

```text title="Output"
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 help

**Usage:** `census help [COMMAND]`

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.

```sh
# Every command
census help

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

## census access

**Usage:** `census access [--json]`

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

```sh
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](https://diskcensus.com/docs/cli/scans.md#full-disk-access).

## census version

**Usage:** `census version [--json]`

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

```sh
census version --json
```

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

## census selftest

**Usage:** `census selftest [--keep] [--json]`

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

| Option | Description |
| --- | --- |
| `--keep` | Keep the temporary folder for debugging |
| `--json` | Write one JSON response |

```sh
census selftest --json
```

```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 serve

**Usage:** `census serve`

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](https://diskcensus.com/docs/agents/serve.md) for the protocol.

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