HeftCommand line
Windows · macOS · LinuxEverything you need to use Heft from scripts and scheduled tasks: exports, cleaning, treemap images, benchmarks and sensors.
On Windows, heft.exe is a windowed program, so a terminal may not show what it prints. Add --out report.txt to save the output to a file, or pipe it, for example heft.exe --bench C:\ | more. The examples below use heft; on Windows use the full path to heft.exe if it isn't on your PATH.
On a Mac, the program is inside the app: /Applications/Heft.app/Contents/MacOS/heft.
Reference
| Command | What it does |
|---|---|
heft [path] | Open Heft, and start scanning path if given. |
heft --export <path> <out.csv|out.json> [--folders] | Scan path and write every item as CSV (folders only with --folders), or a JSON summary if the file ends in .json. |
heft --clean [--dry-run] | Run the Cleaner with the selection saved in the app. --dry-run only reports what would go. |
heft --render <path> <out.png> [--size WxH] [--mode type|category|age] | Scan path and save a treemap image. The default size is 1600x1000. |
heft --bench <path> [--json] | Scan and print a summary with timings, the largest folders and the largest file types, or JSON. |
heft --sensors [--rounds N] [--report] | Read every hardware sensor N times (default 3) and print the values with their minimum and maximum. On a Mac, --report adds the model, chip and raw sensor data, for reporting a wrong reading. |
heft --tray | Start hidden in the notification area (Windows) or the menu bar (macOS). |
heft --compare <path> | Scan with both the MFT scanner and the folder scanner and compare the results. Windows, as administrator. |
heft --check-refresh <path> [--wait] | Test quick rescans against a full scan: scan path, change files in a scratch folder, rescan, and compare the result item by item with a fresh full scan. On Windows, give an NTFS drive and run as administrator. On macOS, any folder on a local disk; with --wait, Heft waits for you to change files yourself and press Enter instead. |
heft --icon <out.png> [--size N] | Write the app icon. Used by the packaging scripts. |
Two options work with most commands:
--out <file>saves the printed report to a file as well.--walkmakes--bench,--exportand--renderuse the folder scanner even when the fast MFT scan is available.
Set HEFT_DEMO=1 to open the app on a made-up demo disk without scanning anything.
Exporting a scan
Every file and folder under a path, for a spreadsheet:
heft --export C:\Users\alex everything.csvJust the folders, which is much shorter:
heft --export /home/alex folders.csv --foldersA JSON summary with totals, the drive's free space, the items directly inside, the largest files and space by type, handy for monitoring scripts:
heft --export / summary.jsonFor a quick machine-readable scan summary without writing a file, use heft --bench <path> --json.
Running the Cleaner
heft --clean runs the Cleaner with whatever you last ticked on the Cleaner page. Try it first with --dry-run to see what would be removed:
heft --clean --dry-runThe same safety rules apply as in the app: files in use are skipped, and so are rules whose program is running or that need administrator rights you don't have. On a Mac, rules that need your administrator password ask for it once, as in the app, when you run the command in a terminal; with nobody there to answer, they're skipped, and so is anything that would restart Finder. On Windows and macOS, the Cleaner page can schedule this every Sunday for you.
Scheduling it yourself
On Windows and macOS, the Cleaner page's weekly cleaning sets this up for you. On Linux, or for a different schedule, use your system's scheduler. For example, to clean every Sunday at noon with cron, run crontab -e and add:
0 12 * * 0 /path/to/heft --clean --out /tmp/heft-clean.txtRules that run system tools through pkexec (the Linux package and journal caches) ask for your password, so they can't run unattended. Leave them unticked if you schedule cleaning.
Treemap images
Save a picture of a folder's treemap, for a report or just to compare over time:
heft --render C:\ drive.png --size 2400x1500 --mode age--mode picks the colors: type (the default), category or age.
Benchmarks and sensors
--bench scans a path and prints how long each phase took, along with the totals and the biggest folders and types. It's useful for comparing the fast scan with a folder scan:
heft --bench C:\ --out fast.txt
heft --bench C:\ --walk --out walk.txt--sensors reads every hardware sensor a few times and prints them. On Windows, the driver status comes first:
heft --sensors --rounds 5On a Mac, --report adds the model, chip and macOS version and the raw sensor data behind the readings. If a reading is missing or wrong on your Mac, save a report and attach it to an issue, so the readings can be fixed for your chip. It has no serial numbers, names or addresses.
heft --sensors --report --out report.txt