Reports
The guided walkthrough writes a JSON session record to
~/.linux-cleanup/reports/report-<timestamp>.json, unless --no-report or --dry-run is set. Other modes do not create that record. Existing records are not auto-deleted.
Markdown and HTML are optional conversions produced on demand.
linux-cleanup --reports # interactive manager
linux-cleanup --export both latest # non-interactive conversion
What a session record contains
| Section | Holds |
|---|---|
schema_version | Currently 1 |
credits | Tool name, version, homepage, licence, author details |
meta | Timestamps, duration, host, user, mode, staleness threshold, log path, launcher |
disk | Filesystem usage before and after |
memory | Memory usage before and after |
steps | One entry per step: number, title, status, bytes freed |
totals | Total bytes reclaimed, human-readable total, steps run and skipped |
Full field-by-field reference: Report schema.
The interactive manager
linux-cleanup --reports
Lists past sessions and lets you view one, convert it to Markdown or HTML, open the HTML in a browser, or delete it.
Conversion options are hidden when jq is not installed — see below.
Exporting
Non-interactive, for scripts and habits:
linux-cleanup --export both latest # Markdown + HTML from the newest record
linux-cleanup --export html all # every record to HTML
linux-cleanup --export md 3 # record #3 to Markdown
| Argument | Accepts |
|---|---|
| Format | md, html, both |
| Identifier | a record number, latest, or all |
Output lands beside the JSON with the same timestamp in the filename. The HTML is self-contained — embedded CSS, dark-mode aware, no external assets — so it can be emailed or archived as a single file.
jq is required for conversion
Without jq, a walkthrough can still produce its JSON record. Only Markdown and HTML export are
unavailable, and step 10 of the walkthrough records itself as skipped (jq missing).
sudo apt install jq # Debian / Ubuntu
sudo dnf install jq # Fedora / RHEL
sudo pacman -S jq # Arch
The generated HTML escapes every JSON-derived value through jq's @html filter, so a malformed input
cannot inject markup into the rendered page.
Querying the JSON directly
The JSON is meant to be read by tools:
# Total reclaimed by the most recent session
jq '.totals.total_reclaimed_human' ~/.linux-cleanup/reports/report-*.json | tail -1
# Every step that actually ran, most recent session
jq '.steps[] | select(.status == "ran") | {title, freed_bytes}' \
"$(ls -t ~/.linux-cleanup/reports/report-*.json | head -1)"
# Reclaim across every recorded session
jq -s 'map(.totals.total_reclaimed_bytes) | add' ~/.linux-cleanup/reports/report-*.json
Retention
These records are never deleted automatically — not even by --cleanup-logs, which only removes the
current run's log file.
To thin them yourself:
find ~/.linux-cleanup/reports/ -name 'report-*' -mtime +90 -delete
Skip generation entirely for a single run with --no-report; the log is still written.
These are records, not backups
It records steps and disk observations, not a complete list of every removed file. It contains none of the removed content, and nothing in it can restore anything. Its value after an unwanted deletion is helping you identify what to restore from your own backup, or re-download. See Recovery.
Next
- Report schema — every field
- Output paths — where files land
- Recovery — using a session record after a surprise