# The census command line

> census is the Disk Census engine as a command. It runs the app's scan, findings and cleanup from your terminal, your scripts and your AI agents.

## What census does

`census` scans your Mac's disk, shows what is using the space, and deletes only what you choose. It is the engine inside the Disk Census app: the app starts `census serve` and talks to it in JSON. The app, your scripts and your AI agents all work from the same saved scan, under the same safety rules.

- **Reading is safe.** Scanning and every query only read. They never move or change your files.
- **Deleting is permanent.** Nothing goes to the Trash. Only a few commands delete anything, and they ask first. See [Safety and deletion](https://diskcensus.com/docs/cli/safety.md).
- **Scripts get JSON.** Add `--json` to any command and it prints exactly one JSON document. See [JSON output](https://diskcensus.com/docs/cli/json.md).

## Get census

`census` ships inside the app, at `Disk Census.app/Contents/Helpers/census`. You don't download it separately, and it updates with the app. Your Disk Census license covers the command line too.

To use it in Terminal, open Disk Census, go to the **CLI and Agents** tab, and turn on the command line. The app adds `census` to your shell. Then open a new Terminal window and check the version:

```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` runs on macOS 12 or later, on Apple silicon and Intel Macs.

## Your first commands

Scan the startup drive, then ask the saved scan questions. Queries read the saved scan instead of walking the disk again.

```sh
# Scan the whole startup drive and print a summary
census

# The largest folders, three levels deep
census top

# Files over 1 GB that you haven't opened in a year
census large --min-size 1G --not-opened 365

# What is safe to clean, and what needs your judgment
census findings
```

The [Quickstart](https://diskcensus.com/docs/cli/quickstart.md) walks through a first scan and cleanup from start to finish.

## Commands

| Command | What it does | Effect |
| --- | --- | --- |
| [`scan`](https://diskcensus.com/docs/cli/explore.md#scan) | Scans a scope and saves its tree for later queries. `census` alone runs it. | Read-only |
| [`report`](https://diskcensus.com/docs/cli/explore.md#report) | Shows the last saved scan report for a scope. | Read-only |
| [`scans`](https://diskcensus.com/docs/cli/explore.md#scans) | Lists every saved scan. | Read-only |
| [`breakdown`](https://diskcensus.com/docs/cli/explore.md#breakdown) | Groups the scanned space into storage buckets. | Read-only |
| [`top`](https://diskcensus.com/docs/cli/explore.md#top) | Shows the largest folders, or the largest files with `--files`. | Read-only |
| [`ls`](https://diskcensus.com/docs/cli/explore.md#ls) | Shows a saved folder's contents. | Read-only |
| [`types`](https://diskcensus.com/docs/cli/explore.md#types) | Shows file types and their share of the scan. | Read-only |
| [`history`](https://diskcensus.com/docs/cli/explore.md#history) | Shows how used space changed over the last hour, day, week and month. | Read-only |
| [`findings`](https://diskcensus.com/docs/cli/find.md#findings) | Lists cleanup findings, grouped as safe, review and keep. | Read-only |
| [`large`](https://diskcensus.com/docs/cli/find.md#large) | Lists the largest files or folders you can delete. | Read-only |
| [`duplicates`](https://diskcensus.com/docs/cli/find.md#duplicates) | Finds identical files and the space extra copies take. Alias: `dupes`. | Read-only |
| [`apps`](https://diskcensus.com/docs/cli/find.md#apps) | Lists installed apps and the Library items that belong to them. | Read-only |
| [`app`](https://diskcensus.com/docs/cli/find.md#app) | Shows one app and its Library items. | Read-only |
| [`leftovers`](https://diskcensus.com/docs/cli/find.md#leftovers) | Lists possible leftovers of apps you removed. | Read-only |
| [`clean`](https://diskcensus.com/docs/cli/clean.md#clean) | Deletes the safe tier and saves the rest for review. | Deletes |
| [`review`](https://diskcensus.com/docs/cli/clean.md#review) | Shows what needs a person and lets you choose what to delete. | Deletes |
| [`apply`](https://diskcensus.com/docs/cli/clean.md#apply) | Deletes the paths a selection file lists. | Deletes |
| [`empty-trash`](https://diskcensus.com/docs/cli/clean.md#empty-trash) | Empties every Trash you own. | Deletes |
| [`uninstall`](https://diskcensus.com/docs/cli/clean.md#uninstall) | Removes an app and the data named after it. | Deletes |
| [`maintain`](https://diskcensus.com/docs/cli/maintain.md#maintain) | Lists or runs maintenance tasks, such as rebuilding Quick Look's cache. | Runs tasks |
| [`optimize`](https://diskcensus.com/docs/cli/maintain.md#optimize) | Cleans the safe tier and runs the quick maintenance tasks, after one confirmation. | Deletes |
| [`export`](https://diskcensus.com/docs/cli/export.md#export) | Saves a scan report as JSON, Markdown, HTML or CSV. | Read-only |
| [`access`](https://diskcensus.com/docs/cli/utilities.md#access) | Shows whether this process has Full Disk Access. | Read-only |
| [`version`](https://diskcensus.com/docs/cli/utilities.md#version) | Prints the package and schema versions. | Read-only |
| [`selftest`](https://diskcensus.com/docs/cli/utilities.md#selftest) | Checks incremental rescans against full scans in a temporary folder. | Read-only |
| [`help`](https://diskcensus.com/docs/cli/utilities.md#help) | Shows every command, or one command's options. | Read-only |
| [`serve`](https://diskcensus.com/docs/agents/serve.md) | Answers JSON requests on stdin, for the app and other programs. | Per request |

## Scripts and AI agents

Every command takes `--json`, and the exit code tells you what happened. Read [JSON output](https://diskcensus.com/docs/cli/json.md) and [Exit codes and errors](https://diskcensus.com/docs/cli/errors.md) before you script against `census`.

AI coding agents use the same commands. The census skill teaches them to clean the safe tier when you ask, show you everything else, and delete only what you choose. See [Census for AI agents](https://diskcensus.com/docs/agents.md).