Skip to main content

Environment variables

Every environment variable linux-cleanup reads. All are optional.

VariableDefaultEffect
NO_COLORunsetAny non-empty value disables ANSI colour. The cross-tool standard from no-color.org. Same as --no-color
CLEANUP_NO_COLOR0linux-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_HOMEunset — falls back to the parent of the log dirParent for logs/, reports/ and feedback/ together
LINUX_CLEANUP_NPXunsetInternal. Set to 1 by the Node launcher. Do not set it yourself
LINUX_CLEANUP_LAUNCHERunsetInternal. 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~/.configWhere 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 directory is created, the mount is not

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:

FileUsed byDefault roots
personal-roots.txt--stale~/Downloads; protected roots such as ~/Desktop are ignored
project-roots.txt--node-modulesYour project directories

One path per line. This follows the XDG Base Directory specification, so setting XDG_CONFIG_HOME relocates both.

Adding a root to personal-roots.txt widens what can be deleted

The 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 installed
  • USER and LOGNAME, except to annotate the log header
  • Your shell history, aliases or configuration — --doctor is 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​