Skip to main content

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​

SectionHolds
schema_versionCurrently 1
creditsTool name, version, homepage, licence, author details
metaTimestamps, duration, host, user, mode, staleness threshold, log path, launcher
diskFilesystem usage before and after
memoryMemory usage before and after
stepsOne entry per step: number, title, status, bytes freed
totalsTotal 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
ArgumentAccepts
Formatmd, html, both
Identifiera 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​

JSON is always written; conversion is the optional part

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​

A session record is a step summary, not a backup

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​