CLI flags
Every flag linux-cleanup accepts. Modes are mutually exclusive — pass one. Options combine with any mode.
linux-cleanup --help # the same list, with your machine's real paths inlined
An unrecognised flag prints the help text and exits with code 2.
Modes
Pass at most one. With none, you get the walkthrough.
| Flag | Aliases | Does | Full page |
|---|---|---|---|
| (none) | -w --walkthrough | Ten guided steps, prompting before each | Walkthrough |
-m | --menu -i --interactive | Numbered jump-to menu | Menu |
-t | --tui -g --gui | Visual whiptail / dialog menu | TUI |
-a | --all-safe | Batch clean every regenerable cache | All-safe |
-s | --scan | Read-only audit of every category | Scan |
-p | --stale | Large idle personal files (interactive) | Stale personal files |
--system | apt, journal, snap, /tmp, page cache (sudo) | System cleanup | |
--partials | Orphaned partial downloads (interactive) | Partial downloads | |
--audit | 20 largest entries in $HOME | Home audit | |
--node-modules | Stale node_modules (interactive) | node_modules finder | |
--globals | Read-only global-package audit | Globals audit | |
--doctor | Repair missing shell-init for runtimes | Doctor | |
--speed | Inspect pressure and startup work; ask before changes | Speed diagnosis | |
--editor-ext | Superseded VS Code / Cursor versions | Editor extensions | |
--reports | Interactive session-record manager | Reports | |
--export FMT ID | Non-interactive record conversion | Reports | |
--feedback | Bug-report instructions, optional mailto draft | Send a bug report | |
--debug-bundle | Package latest log + record into a tar.gz | Send a bug report | |
--list-targets | Print every targetable and protected path | Preview first | |
--self-test | Dependency, syntax and safety-guard checks | Preview first | |
-V | --version | Version and author | — |
--install-alias | Add a cleanup shell alias | Alias and cron | |
--install-cron | Weekly --all-safe -y, Sundays 03:00 | Alias and cron | |
--uninstall-alias | Remove the alias | Uninstall | |
--uninstall-cron | Remove the cron entry | Uninstall | |
--refresh-app | Refresh the persistent copy used by alias and cron | Installation |
Options
| Flag | Default | Effect |
|---|---|---|
-d N --days N | 100 | Staleness threshold. A file is eligible only when both atime and mtime exceed it. Lower is more aggressive |
--purge-all | off | Disables the staleness gate. Cache targets are wiped in full — pre-1.2.0 behaviour |
-y --yes | off | Auto-confirm regenerable caches. Valid only with --all-safe. Personal modes ignore it |
--no-report | off | Skip JSON generation. Logs are still written |
--cleanup-logs | off | Delete this run's log at the end. Records are always kept |
-n --dry-run | off | Walk the selected mode without deleting files or changing settings. A local log remains; no JSON session report is written |
--json-events | off | Version 1 NDJSON on stdout for --scan or --all-safe --yes; human text goes to stderr |
--no-color | off | Disable ANSI colour. NO_COLOR is honoured too |
-h --help | — | Print help and exit |
--purge-all removes a safety guardIt turns off the staleness gate, so caches are wiped whole regardless of when they were last used. Expensive assets — Gradle wrapper distributions, Playwright browsers, Cypress binaries — go with them. The pre-run banner states which strategy is active.
Scan and dry run answer different questions
--scan reads the current paths and sizes. --dry-run walks the selected cleanup and
shows proposed actions without deletion. See
Preview before deleting.
Recipes
| Goal | Command |
|---|---|
| Verify the install | linux-cleanup --self-test |
| See what is reclaimable | linux-cleanup --scan |
| Preview a selected cache cleanup | linux-cleanup --all-safe --dry-run |
| Stream a read-only scan as JSON events | linux-cleanup --scan --json-events |
| See every path it can touch | linux-cleanup --list-targets |
| Guided cleanup | linux-cleanup |
| One-shot batch, no prompts | linux-cleanup --all-safe -y |
| Aggressive sweep | linux-cleanup --all-safe -y -d 30 |
| Maximum reclaim before reimaging | linux-cleanup --all-safe -y --purge-all |
| Visual menu | linux-cleanup --tui |
| Old project dependency dirs | linux-cleanup --node-modules -d 90 |
| System maintenance | linux-cleanup --system |
| Weekly automation | linux-cleanup --install-cron |
| Convert the newest record to HTML | linux-cleanup --export html latest |
| File a bug | linux-cleanup --debug-bundle && linux-cleanup --feedback |
Environment variables
Most-used, with the full list separately:
| Variable | Effect |
|---|---|
NO_COLOR | Any non-empty value disables colour |
LINUX_CLEANUP_LOG_DIR | Override the log directory |
LINUX_CLEANUP_REPORTS_DIR | Override the session-record directory |
LINUX_CLEANUP_DATA_HOME | Parent for logs, records and feedback bundles |
Exit codes
| Code | Meaning |
|---|---|
0 | Clean run |
2 | Argument parse error or unsupported event-stream mode |
3 | An older version blocked by the release record |
130 | Aborted with Ctrl-C |
143 | Terminated by SIGTERM |
| other | Unexpected — writes a crash bundle |
Full table and the crash-trap logic: Exit codes.