# Reports and exports

> Save a scan as JSON, Markdown, a self-contained HTML page or CSV, with home-folder names hidden when you share it.

## census export

**Usage:** `census export json|md|html|csv [SCOPE] [--output PATH] [--force] [--sections LIST] [--limit N] [--redact] [--refresh] [--progress] [--json]`

Saves one saved scan as a report. Without `--output`, the report goes to stdout.

| Option | Description |
| --- | --- |
| `--scope KIND` | `drive` (the default) or `data` |
| `-p, --path PATH` | A folder's own scan |
| `--output PATH` | Write to this file or folder (default: stdout) |
| `--force` | Replace an existing file |
| `--sections LIST` | Comma-separated sections. `duplicates` isn't included by default. |
| `--limit N` | Rows per list (default: 50; `0` means all) |
| `--redact` | Hide names beneath home folders |
| `--refresh` | Rescan first; otherwise the saved scan is read |
| `--progress` | Write progress as NDJSON to stderr |
| `--json` | With `--output`, print a JSON summary of the file written |

```sh
# A JSON report on the Desktop, named after the scan
census export json --output ~/Desktop/

# A Markdown report of four sections
census export md --sections summary,findings,folders,files --output report.md

# An HTML page you can share, with home-folder names hidden
census export html --redact --output ~/Desktop/shared-report.html

# Every row, as CSV
census export csv --limit 0 --output ~/Desktop/disk-usage.csv
```

### Sections

Sections come in this order: `summary`, `breakdown`, `findings`, `folders`, `files`, `types`, `apps`, `leftovers` and `duplicates`. By default a report has every section that applies, except `duplicates`, which has to read file contents; add it with `--sections`. `--limit` applies only to folders, files and duplicate groups. `apps` and `leftovers` need a drive or data scan; sections that don't apply are left out and named in `warnings`.

### Where the file goes

- **No `--output`:** the report is written to stdout. `--json` isn't allowed then, since stdout already holds the report.
- **An existing folder:** it receives `census-<scan_id>.<format>`.
- **A file that exists:** kept, unless you add `--force` (`output_exists` otherwise).

With `--output` and `--json`, census prints an envelope whose `results` has `format`, `path`, `bytes` and `sections`:

```sh
census export json --sections summary,duplicates --limit 5 --output report.json --json
```

### Formats

| Format | What you get |
| --- | --- |
| `json` | The v5 envelope, one `scan` object, and `results` with `generated_at_unix_ms`, `redacted` and `sections` |
| `md` | A Markdown report |
| `html` | One self-contained page, with no scripts and no external resources |
| `csv` | CRLF records, exact byte columns, and a guard against formula injection |

`--redact` replaces names in home-folder paths with salted tokens, and Markdown and HTML reports say that names are hidden. Export is available only on macOS.