Environment variables
Every environment variable linux-cleanup reads. All are optional.
| Variable | Default | Effect |
|---|---|---|
NO_COLOR | unset | Any non-empty value disables ANSI colour. The cross-tool standard from no-color.org. Same as --no-color |
CLEANUP_NO_COLOR | 0 | linux-cleanup-specific colour switch. Set to 1 to disable colour here only |
LINUX_CLEANUP_LOG_DIR | ~/.linux-cleanup/logs/ (npx / npm) or <repo>/logs/ (clone) | Where session logs go. Created if missing |
LINUX_CLEANUP_REPORTS_DIR | ~/.linux-cleanup/reports/ or <repo>/reports/ | Where JSON session records go. Created if missing |
LINUX_CLEANUP_DATA_HOME | unset — falls back to the parent of the log dir | Parent for logs/, reports/ and feedback/ together |
LINUX_CLEANUP_NPX | unset | Internal. Set to 1 by the Node launcher. Do not set it yourself |
LINUX_CLEANUP_LAUNCHER | unset | Internal. The Node launcher sets node; the desktop app sets desktop, which skips the CLI's own update check because the app runs its own (since 2.1.0). Do not set it yourself |
XDG_CONFIG_HOME | ~/.config | Where personal-roots.txt and project-roots.txt are looked up |
Redirecting all output
LINUX_CLEANUP_DATA_HOME is the single lever that moves everything — logs, records and feedback bundles:
export LINUX_CLEANUP_DATA_HOME="/mnt/secure/linux-cleanup"
linux-cleanup --scan
The tool creates logs/, reports/ and feedback/ beneath the path you give it. It does not create or
verify the underlying mount point. Point this at an unmounted path and output lands on the underlying
filesystem instead — quietly.
Verify the target is mounted and writable before relying on it.
For finer control, LINUX_CLEANUP_LOG_DIR and LINUX_CLEANUP_REPORTS_DIR override individually and take
precedence over the data home.
Colour control
export NO_COLOR=1 # everything on this machine, all tools
export CLEANUP_NO_COLOR=1 # only linux-cleanup
linux-cleanup --no-color # only this invocation
CLEANUP_NO_COLOR exists for the case where you want colour from every other tool and plain output from
this one — typically when piping its output somewhere that mangles escape sequences.
Configuring the scanned roots
Two files under $XDG_CONFIG_HOME (default ~/.config) control which directories the personal and project
scanners walk:
| File | Used by | Default roots |
|---|---|---|
personal-roots.txt | --stale | ~/Downloads; protected roots such as ~/Desktop are ignored |
project-roots.txt | --node-modules | Your project directories |
One path per line. This follows the
XDG Base Directory specification, so setting
XDG_CONFIG_HOME relocates both.
personal-roots.txt widens what can be deletedThe personal scanner is interactive-only, so nothing is removed without your per-file confirmation — but a root you add is a directory whose contents will start appearing in candidate lists.
The path allowlist still applies and still wins: adding ~/Documents here does not
make it deletable.
For CI and scripts
NO_COLOR=1 linux-cleanup --scan > /tmp/scan.log
The standalone scan does not create the walkthrough's JSON session report. Check the
exit code when scripting it, or use --json-events for structured output.
What it does not read
PATH, except to detect which optional tools are installedUSERandLOGNAME, except to annotate the log header- Your shell history, aliases or configuration —
--doctoris the only mode that reads shell-init files, and only to check whether a runtime is wired in - Any remote or network-provided configuration. There is none
If $HOME is unset the script aborts immediately rather than guessing. See
Troubleshooting.
Next
- Output paths — where files actually land
- CLI flags