Skip to main content

Report schema

The guided walkthrough writes a JSON record with "schema_version": 1, unless --no-report or --dry-run is set. The standalone --scan does not write this report. For a machine-readable scan, use --scan --json-events; that stream has a different structure.

Older documentation describes a different structure

Some material — including a reference page inside the source repository — describes a shape built around schema (a string like linux-cleanup/report/v1) with tool, session and categories objects.

The tool does not emit that. A parser written against it will fail on every real file. The structure below is what modules/walkthrough.sh writes. Confirm on your own machine:

jq 'keys' "$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"

Top level​

{
"schema_version": 1,
"credits": { },
"meta": { },
"disk": { "before": {}, "after": {} },
"memory": { "before": {}, "after": {} },
"steps": [ ],
"totals": { }
}
KeyTypeHolds
schema_versionnumberCurrently 1. Reject anything you do not recognise
creditsobjectTool identity, licence and author
metaobjectSession context — when, where, how, with what settings
diskobjectFilesystem usage before and after
memoryobjectMemory usage before and after
stepsarrayOne entry per step attempted
totalsobjectSession summary

credits​

{
"tool": "linux-cleanup",
"tool_version": "2.1.0",
"tool_homepage": "https://aoneahsan.com",
"tool_license": "MIT",
"author": {
"name": "Ahsan Mahmood",
"email": "aoneahsan@gmail.com",
"website": "https://aoneahsan.com",
"linkedin": "https://linkedin.com/in/aoneahsan"
}
}

Present so a record is self-attributing wherever it ends up. Nothing here reflects your machine.

meta​

KeyTypeHolds
toolstringAlways linux-cleanup
tool_versionstringThe version that wrote the record. Gate consumer logic on this
started_atstringSession start timestamp
finished_atstringSession end timestamp
duration_secondsnumberWall-clock duration
hoststringhostname output
userstring$USER
modestringThe mode that ran — walkthrough, scan, allsafe, system, and so on
stale_daysnumberThe --days threshold in force
log_filestringAbsolute path to this session's log
launcherstringHow it was invoked — bash for a direct run
via_npxnumber1 when run through the npm launcher, 0 otherwise

stale_days is worth capturing: it is the difference between a run that pruned at 100 days and one that ran with -d 30, and it explains why two sessions on the same machine reclaimed different amounts.

disk and memory​

Both hold a before and an after snapshot, taken at session start and end.

disk carries filesystem fields — filesystem, size, used, available and use percentage — derived from df. memory carries the equivalent from the system's memory report.

after minus before is not purely your cleanup

These are whole-machine measurements. A build, a package update or a browser running during the session moves them too, which is why a reported recovery can be lower than the sum of the steps — or negative. See Troubleshooting.

steps​

An array, one entry per step attempted, in order:

{ "n": 1, "title": "Package-manager caches", "status": "ran", "freed_bytes": 13315108864 }
KeyTypeHolds
nnumber1-based step number
titlestringHuman-readable step name
statusstringran, skipped, skipped (quit), or skipped (jq missing)
freed_bytesnumberBytes reclaimed by this step. 0 when skipped

skipped (quit) marks the steps after you pressed q — useful for telling a deliberate stop from a step you declined individually.

totals​

KeyTypeHolds
total_reclaimed_bytesnumberSum across steps
total_reclaimed_humanstringThe same, formatted
steps_runnumberSteps with status ran
steps_skippednumberSteps with a skipped status

Parsing​

LATEST="$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"

jq '.totals.total_reclaimed_human' "$LATEST"
jq '.meta | {mode, stale_days, duration_seconds}' "$LATEST"
jq '.steps[] | select(.status == "ran") | "\(.title): \(.freed_bytes)"' "$LATEST"

# Reclaim across every session on record
jq -s 'map(.totals.total_reclaimed_bytes) | add' ~/.linux-cleanup/reports/report-*.json

Validating​

No JSON Schema file ships with the tool. A structural check:

jq -e 'has("schema_version") and .schema_version == 1
and has("meta") and has("steps") and has("totals")' \
~/.linux-cleanup/reports/report-*.json

Prints true per valid file.

Compatibility guidance​

Writing a consumer:

  • Branch on schema_version. Treat an unfamiliar value as unparseable rather than guessing
  • Treat unknown keys as additive. Fields have been added within version 1 and may be again
  • Use meta.tool_version for behaviour that differs between releases
  • Do not assume every mode fills every section. Read-only modes produce fewer steps
  • Expect total_reclaimed_bytes to be negative occasionally. It is a df delta, not a sum of deletions

Next​