Skip to main content

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.

FlagAliasesDoesFull page
(none)-w --walkthroughTen guided steps, prompting before eachWalkthrough
-m--menu -i --interactiveNumbered jump-to menuMenu
-t--tui -g --guiVisual whiptail / dialog menuTUI
-a--all-safeBatch clean every regenerable cacheAll-safe
-s--scanRead-only audit of every categoryScan
-p--staleLarge idle personal files (interactive)Stale personal files
--systemapt, journal, snap, /tmp, page cache (sudo)System cleanup
--partialsOrphaned partial downloads (interactive)Partial downloads
--audit20 largest entries in $HOMEHome audit
--node-modulesStale node_modules (interactive)node_modules finder
--globalsRead-only global-package auditGlobals audit
--doctorRepair missing shell-init for runtimesDoctor
--speedInspect pressure and startup work; ask before changesSpeed diagnosis
--editor-extSuperseded VS Code / Cursor versionsEditor extensions
--reportsInteractive session-record managerReports
--export FMT IDNon-interactive record conversionReports
--feedbackBug-report instructions, optional mailto draftSend a bug report
--debug-bundlePackage latest log + record into a tar.gzSend a bug report
--list-targetsPrint every targetable and protected pathPreview first
--self-testDependency, syntax and safety-guard checksPreview first
-V--versionVersion and author—
--install-aliasAdd a cleanup shell aliasAlias and cron
--install-cronWeekly --all-safe -y, Sundays 03:00Alias and cron
--uninstall-aliasRemove the aliasUninstall
--uninstall-cronRemove the cron entryUninstall
--refresh-appRefresh the persistent copy used by alias and cronInstallation

Options​

FlagDefaultEffect
-d N --days N100Staleness threshold. A file is eligible only when both atime and mtime exceed it. Lower is more aggressive
--purge-alloffDisables the staleness gate. Cache targets are wiped in full — pre-1.2.0 behaviour
-y --yesoffAuto-confirm regenerable caches. Valid only with --all-safe. Personal modes ignore it
--no-reportoffSkip JSON generation. Logs are still written
--cleanup-logsoffDelete this run's log at the end. Records are always kept
-n --dry-runoffWalk the selected mode without deleting files or changing settings. A local log remains; no JSON session report is written
--json-eventsoffVersion 1 NDJSON on stdout for --scan or --all-safe --yes; human text goes to stderr
--no-coloroffDisable ANSI colour. NO_COLOR is honoured too
-h --help—Print help and exit
--purge-all removes a safety guard

It 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​

GoalCommand
Verify the installlinux-cleanup --self-test
See what is reclaimablelinux-cleanup --scan
Preview a selected cache cleanuplinux-cleanup --all-safe --dry-run
Stream a read-only scan as JSON eventslinux-cleanup --scan --json-events
See every path it can touchlinux-cleanup --list-targets
Guided cleanuplinux-cleanup
One-shot batch, no promptslinux-cleanup --all-safe -y
Aggressive sweeplinux-cleanup --all-safe -y -d 30
Maximum reclaim before reimaginglinux-cleanup --all-safe -y --purge-all
Visual menulinux-cleanup --tui
Old project dependency dirslinux-cleanup --node-modules -d 90
System maintenancelinux-cleanup --system
Weekly automationlinux-cleanup --install-cron
Convert the newest record to HTMLlinux-cleanup --export html latest
File a buglinux-cleanup --debug-bundle && linux-cleanup --feedback

Environment variables​

Most-used, with the full list separately:

VariableEffect
NO_COLORAny non-empty value disables colour
LINUX_CLEANUP_LOG_DIROverride the log directory
LINUX_CLEANUP_REPORTS_DIROverride the session-record directory
LINUX_CLEANUP_DATA_HOMEParent for logs, records and feedback bundles

Exit codes​

CodeMeaning
0Clean run
2Argument parse error or unsupported event-stream mode
3An older version blocked by the release record
130Aborted with Ctrl-C
143Terminated by SIGTERM
otherUnexpected — writes a crash bundle

Full table and the crash-trap logic: Exit codes.