Skip to main content

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.

ModeFlagShows
Scan-s --scanEvery cache category with current sizes
Home audit--auditThe 20 largest entries in $HOME
Globals audit--globalsGlobal npm/pnpm/yarn/bun/deno packages
List targets--list-targetsEvery path the tool can touch, plus the protected list
Self-test--self-testDependency, syntax and safety-guard checks
Version-V --versionVersion 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.

ModeFlagBehaviour
Walkthrough(default) -wTen guided steps, prompt before each
Menu-m --menuNumbered menu — pick one category
TUI-t --tuiThe same, as a whiptail/dialog dialog
All-safe-a --all-safeEvery regenerable cache in one pass
Editor extensions--editor-extSuperseded VS Code / Cursor versions
System cleanup--systemapt, 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.

ModeFlagFinds
Stale personal files-p --staleLarge idle files in ~/Downloads and configured unprotected roots
Partial downloads--partials.fdmdownload, .crdownload, .part
node_modules finder--node-modulesProject dependency dirs idle N+ days

Output, repair and setup​

ModeFlagPurpose
Reports--reportsList, convert, view past session reports
Export--export FMT IDNon-interactive conversion
Doctor--doctorRepair broken shell-init for nvm, pnpm, bun, deno, cargo
Speed diagnosis--speedMeasure pressure and startup work; optional fixes ask separately
Feedback--feedbackBug-report instructions, optional mailto draft
Debug bundle--debug-bundlePackage latest log + report into a tar.gz
Install alias--install-aliasAdd a cleanup shell alias
Install cron--install-cronWeekly --all-safe -y, Sundays 03:00
Uninstall alias / cron--uninstall-alias --uninstall-cronRemove either

Choosing a mode​

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

OptionDefaultEffect
-d N --days N100Staleness threshold. Lower is more aggressive
--purge-alloffDisables the staleness gate — full wipe
-y --yesoffAuto-confirm regenerable caches. Only with --all-safe
--no-reportoffSkip the JSON report. Logs still written
--cleanup-logsoffDelete this run's log at the end. Reports always kept
--no-coloroffDisable ANSI colour. NO_COLOR also honoured
-n --dry-runoffWalk a selected cleanup without deleting; local log and update-check state may still be written
--json-eventsoffNDJSON for --scan or non-interactive --all-safe --yes

Full detail: CLI flags and the modes matrix.