Modes overview
linux-cleanup has one entry point and picks its mode from a single flag. Running it with no flag gives you the guided walkthrough.
Modes are mutually exclusive — pass one. Options like --days and --yes combine with them.
Read-only — never deletes anything
These modes do not delete cleanup targets. They may still write a local log, and the release check may read a public record when online.
| Mode | Flag | Shows |
|---|---|---|
| Scan | -s --scan | Every cache category with current sizes |
| Home audit | --audit | The 20 largest entries in $HOME |
| Globals audit | --globals | Global npm/pnpm/yarn/bun/deno packages |
| List targets | --list-targets | Every path the tool can touch, plus the protected list |
| Self-test | --self-test | Dependency, syntax and safety-guard checks |
| Version | -V --version | Version and author |
Cleanup — regenerable data
These modes can delete cleanup targets. --yes skips the batch confirmation only for --all-safe; other modes keep their own prompts.
| Mode | Flag | Behaviour |
|---|---|---|
| Walkthrough | (default) -w | Ten guided steps, prompt before each |
| Menu | -m --menu | Numbered menu — pick one category |
| TUI | -t --tui | The same, as a whiptail/dialog dialog |
| All-safe | -a --all-safe | Every regenerable cache in one pass |
| Editor extensions | --editor-ext | Superseded VS Code / Cursor versions |
| System cleanup | --system | apt, journal, snap, /tmp, page cache — needs sudo |
Cleanup — interactive only
Personal or project data. These ignore --yes and require per-entry confirmation. See
Guard 3.
| Mode | Flag | Finds |
|---|---|---|
| Stale personal files | -p --stale | Large idle files in ~/Downloads and configured unprotected roots |
| Partial downloads | --partials | .fdmdownload, .crdownload, .part |
| node_modules finder | --node-modules | Project dependency dirs idle N+ days |
Output, repair and setup
| Mode | Flag | Purpose |
|---|---|---|
| Reports | --reports | List, convert, view past session reports |
| Export | --export FMT ID | Non-interactive conversion |
| Doctor | --doctor | Repair broken shell-init for nvm, pnpm, bun, deno, cargo |
| Speed diagnosis | --speed | Measure pressure and startup work; optional fixes ask separately |
| Feedback | --feedback | Bug-report instructions, optional mailto draft |
| Debug bundle | --debug-bundle | Package latest log + report into a tar.gz |
| Install alias | --install-alias | Add a cleanup shell alias |
| Install cron | --install-cron | Weekly --all-safe -y, Sundays 03:00 |
| Uninstall alias / cron | --uninstall-alias --uninstall-cron | Remove either |
Choosing a mode
| Goal | Mode |
|---|---|
| First time using the tool | --self-test, then --scan, then --all-safe --dry-run |
| Free space now, with control | (default walkthrough) |
| Free space now, no prompts | --all-safe -y |
| One specific category | --menu or --tui |
| Weekly unattended maintenance | --all-safe -y via --install-cron |
| Maximum reclaim before reimaging | --all-safe -y --purge-all |
| Find what is eating the disk | --audit then --scan |
| Old side projects piling up | --node-modules |
command not found after install | --doctor |
Options that combine with modes
| Option | Default | Effect |
|---|---|---|
-d N --days N | 100 | Staleness threshold. Lower is more aggressive |
--purge-all | off | Disables the staleness gate — full wipe |
-y --yes | off | Auto-confirm regenerable caches. Only with --all-safe |
--no-report | off | Skip the JSON report. Logs still written |
--cleanup-logs | off | Delete this run's log at the end. Reports always kept |
--no-color | off | Disable ANSI colour. NO_COLOR also honoured |
-n --dry-run | off | Walk a selected cleanup without deleting; local log and update-check state may still be written |
--json-events | off | NDJSON for --scan or non-interactive --all-safe --yes |
Full detail: CLI flags and the modes matrix.