Skip to content
Command lineQuickstart

Quickstart

Scan your Mac, see what is using the space, clean what is safe and review the rest, in five steps.

View as Markdown
On this page

1. Turn on the command line

Open Disk Census, go to the CLI and Agents tab, and turn on the command line. Then open a new Terminal window and check that your shell finds census:

Terminal
census version

If your shell can’t find census, check that the command line is turned on in the CLI and Agents tab, then open a new Terminal window.

2. Scan your Mac

Run census with no command. It scans the whole startup drive, saves the result, and prints a summary:

Terminal
census
Example output
Macintosh HD   46.7 GB used · 16.1 GB free

  24.2 GB   ███████▎        macOS
   7.3 GB   ██▏             Developer
   5.6 GB   █▋              Applications
   3.2 GB   █               System Data
   2.6 GB   ▊               Hidden space
   2.0 GB   ▋               App data
   1.9 GB   ▌               Everything else

Biggest files
   7.1 GB   /System/Volumes/Preboot/F3022DFD-…/…/os.clone.dmg
   1.2 GB   /System/Library/AssetsV2/…/index.sql
   1.1 GB   /System/Volumes/VM/swapfile0

Safe to clean: 269 MB → census findings

The rows add up to the disk’s used space. Hidden space is used space that no file census could read accounts for: snapshots, the Recovery volume, files macOS protects, and folders census couldn’t open. Scans and scopes explains every row.

The first scan walks the whole drive. Later scans read again only the folders that changed since the last one.

3. See what’s using space

Queries read the saved scan instead of walking the disk again:

Terminal
# The largest folders, three levels deep
census top

# The ten largest files
census top --files --limit 10

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

# How the space splits into buckets: Applications, Developer, AI agents, …
census breakdown

4. Clean what’s safe

census clean rescans, lists the safe findings (caches, build output and logs that rebuild themselves), and asks before it deletes them:

Terminal
census clean
Example session
Safe to delete: 31 items · 2.0 GB
    1.2 GB  Developer caches
    0.6 GB  App caches
    0.2 GB  Logs
Delete them? [y/N] y
Freed 2.0 GB · used 46.7 GB → 44.7 GB · skipped 2
14 items need review → census review

Items in use, such as the caches of an app that is running, are skipped and saved for review. Deletion is permanent: nothing goes to the Trash.

5. Review the rest

Everything that isn’t safe waits in a review set until you choose. census review shows it as a numbered menu:

Terminal
census review
Example session
Needs review · 14 items · 6.3 GB
  1    3.1 GB  ~/proj/foo/target  Cargo build output
  2    1.4 GB  ~/Downloads/Xcode_15.xip  Installer in Downloads
Delete which? (1,3-5 · Enter for none): 2
Permanently delete 1 item (1.4 GB)? Type delete: delete
Freed 1.4 GB · used 44.7 GB → 43.3 GB

Press Return at Delete which? to keep everything. Nothing you leave out is touched.

Next steps

Updated · census JSON schema 5