CLI reference

windowsweep [mode] [options]

The flags are identical through npx windowsweep, the global windowsweep command, windowsweep.cmd and powershell -File windowsweep.ps1. With no mode, the guided walkthrough starts. Modes marked with a fire mark delete files (subject to every guard in the safety model).

Modes

Mode	Flags	What it does
Walkthrough (default)	-w, --walkthrough	🔥 Guided run through every section, one confirmation per step
Menu	-m, --menu	🔥 Pick one section at a time; toggle dry-run and auto-yes
Safe batch	-a, --all	🔥 Sections 0,1,2,3,5,6,7,8,9,10,21 (+12,13 when elevated), no prompts with --yes
Only	--only L	🔥 Exactly these sections, e.g. --only 1,3,5-7
Profile	--profile NAME	🔥 A named bundle - see Profiles
Scan	-s, --scan	Read-only: health report, every target with its size, personal-file scanners
List	--list	The section catalogue
List targets	--list-targets	Every path the tool can touch, plus the protected list
Self-test	--self-test	Syntax, ASCII-only source, guards, junction and dry-run fixtures; exit 1 on failure
Reports	--reports	Reports manager: list, view, export, open, delete
Export	--export F [ID]	F = md, html, both; ID = N, latest (default), all
Stats	--stats	Run history and total reclaimed
Prune history	--prune-history [N]	Delete logs, reports and bundles older than N days (default 90)
Feedback	--feedback	How to report a bug; nothing is sent
Report issue	--report-issue	Opens a pre-filled GitHub issue in your browser after confirming
Debug bundle	--debug-bundle	Zips the latest log, report and a manifest under ~\.windowsweep\feedback
Scheduled task	--install-task, --uninstall-task	Weekly --all --yes --quiet --no-color --notify on Sundays at 03:00, as your user, start-when-available, with a three-hour limit (refused under npx; install globally first)
Profile alias	--install-alias, --uninstall-alias	A cleanup function in your PowerShell profile (refused under npx; install globally first)
Uninstall data	--uninstall-data	Removes ~\.windowsweep after a confirmation that --yes never answers
Version	-V, --version	Version and author
Help	-h, --help	The flag list

Options

Flag	Default	What it does
--dry-run, -n	off	Delete nothing; print what would go and estimate the total
-y, --yes	off	Auto-confirm regenerable-cache steps. Never applies to personal files
--i-understand-deep	off	Allow deep sections (11, 15, 16, 20) unattended, with --yes
--elevate	off	Relaunch elevated through a UAC prompt; the elevated run writes its own log
-d N, --days N	100	Idle window for caches: a file goes when its newest timestamp is N+ days old
--temp-days N	3	Idle window for temp folders (sections 10 and 12)
--purge-all	off	🔥 Clear cache targets completely instead of pruning idle files (a console run asks for a typed purge once; --yes confirms in batch)
--developer / --not-developer	saved answer	Override developer mode for this run only
--forget-developer	-	Ask the developer question again
--scan-roots "P1;P2"	auto-detected	Project roots for section 17 (semicolon-separated)
--exclude-path P	-	Never scan or touch this tree, in any section (repeatable). Since 1.2.0 the deletion chokepoint itself refuses an excluded path, so it holds everywhere rather than only in section 17
--exclude L	-	Drop sections from --all or a profile
--large-file-mb N	100	Minimum size for section 19
`--hiberfil off	reduced	keep`
--reset-base	off	Add /ResetBase to section 14
--permanent	off	Sections 18, 19 and 23 delete instead of using the Recycle Bin
--logs-dir P, --reports-dir P	~\.windowsweep\...	Where logs and reports are written
--no-report	off	Skip the JSON report (the log is still written)
--cleanup-logs	off	Delete this run's log at exit; reports are kept
--select L	off	Pre-answer the next interactive selection, e.g. --select 1,3-5. Repeatable; the lists are consumed in the order the prompts appear
--select-file P	off	UTF-8 file of one full path per line (# comments and blank lines skipped), matched case-insensitively against each prompt's candidates
--notify	off	Show a Windows notification when the run ends. Never changes the exit code and never writes to stdout
--json	off	One-line JSON summary on stdout; everything else goes to stderr
-q, --quiet	off	Fewer informational lines
--no-color	auto	Disable colour (also NO_COLOR or WINDOWSWEEP_NO_COLOR=1; off when output is redirected)
--ascii	auto	Plain ASCII glyphs (also WINDOWSWEEP_ASCII=1; automatic when output is redirected)
--pwsh	off	Launcher only: run the engine on PowerShell 7

Options may also be written --days=30.

Scripting the interactive sections

Sections 17, 18, 19 and 23 normally need a person choosing items, and they refuse to run unattended. Two flags let a script or a GUI supply that choice in advance:

# by index, one list per prompt, in the order the prompts appear
windowsweep --only 17 --select 1,3-5

# by path: list what you want removed, one full path per line
windowsweep --only 17,18 --select-file .\picks.txt

• Either flag lifts the interactive refusal, because a person did choose - and the selection also answers that section's final confirmation, so the run does not stall waiting for a keypress.
• --yes still selects nothing. It never has, and neither flag changes that.
• --select is consumed one list per prompt. A run with more prompts than lists falls back to the console for the rest, and selects nothing when there is no console.
• --select-file is offered to every prompt, so a line that matches nothing in a given section is normal; it is reported once and skipped.
• Nothing here reaches a path the deletion chokepoint would otherwise refuse.

The usual pairing is to list the candidates first and then act on the ones you want:

windowsweep --only 17 --dry-run --json        # read .candidates[] from the one stdout line
windowsweep --only 17 --select-file .\picks.txt

Machine-readable output

--json writes exactly one line to stdout; every human line goes to stderr. The document carries:

Key	Meaning
tool, version, mode, dry_run, elevated, developer	what ran
freed_bytes, estimated_bytes	reclaimed, and the dry-run estimate
sections[]	section, status (ran, dry-run, skipped, refused, failed), freed_bytes
candidates[]	what an interactive section offered: section, index, path, bytes, idle_days, project
targets[]	in scan mode: section, label, path, bytes
refusals[], log_file, report_file	what was refused, and where the run was recorded

candidates and targets are always present, as empty arrays when nothing was collected, so a caller can rely on the shape.

In --json mode each section also brackets itself on stderr so a caller can show progress:

##windowsweep section=7 event=start
##windowsweep section=7 event=end status=ran freed_bytes=4096

--list --json prints the section catalogue instead of the human table - sections[] (id, key, title, tier, admin, batch, dev), safe_batch, safe_batch_admin, profiles, walkthrough and walkthrough_admin - so a front end reads the catalogue rather than hard-coding it.

Exit codes

Code	Meaning
0	Success
1	A section failed, or the self-test found a failure
2	Usage error, or an interactive mode was started without a console
3	A section named in --only was refused (deep without --i-understand-deep, or interactive-only), or an installer was started from npx
130	Interrupted with Ctrl-C (the engine exits 130 from its exit handler; the Node launcher also returns 130 when it forwards the signal)

Environment variables

Variable	Default	Effect
WINDOWSWEEP_HOME	%USERPROFILE%\.windowsweep	Data directory
WINDOWSWEEP_LOG_DIR, WINDOWSWEEP_REPORTS_DIR	under the data directory	Same as --logs-dir / --reports-dir
WINDOWSWEEP_SHELL	powershell	pwsh runs the engine on PowerShell 7 (launcher only)
WINDOWSWEEP_NO_COLOR, NO_COLOR	unset	Disable colour
WINDOWSWEEP_ASCII	unset	Plain glyphs
WINDOWSWEEP_VERSION, WINDOWSWEEP_LAUNCHER, WINDOWSWEEP_NPX	set by the launcher	Version and launcher facts shown in logs and reports

Config file

%USERPROFILE%\.windowsweep\config.json stores defaults; flags always win. Nothing else is kept there: no history, no path list and no record of what a run removed. Those live in the logs and reports.

Key	Default	Meaning
developer	null	The saved developer answer (true / false)
days	100	Idle window
tempDays	3	Temp idle window
largeFileMb	100	Section 19 minimum size
scanRoots	[]	Section 17 roots
excludePaths	[]	Trees to leave alone, in every section - the same reach as --exclude-path

Last Updated: 2026-09-05