Skip to main content

Installation

linux-cleanup ships three ways: npx with no install, a global npm install, or a git clone. All three run the same Bash script — the npm package is a thin Node launcher that locates cleanup.sh and points logs and reports at a persistent directory.

Check the installed version

Run linux-cleanup --version after installation or upgrade. The changelog records changes to the dry run and release notices.

Option 1 — npx, no install​

The fastest way to evaluate it. Nothing lands on your PATH and nothing is left behind if you decide against it.

npx linux-cleanup --version
npx linux-cleanup --scan # read-only audit
npx linux-cleanup # guided walkthrough

npx fetches the package into a temporary npm cache directory. Your logs and reports are written to ~/.linux-cleanup/ — not the temp directory — so they survive npm cache eviction and are still there next time.

Option 2 — global npm install​

npm install -g linux-cleanup
linux-cleanup --version

linux-cleanup is then on your PATH everywhere. Logs and reports still go to ~/.linux-cleanup/.

npm install -g linux-cleanup@latest # upgrade
npm uninstall -g linux-cleanup # remove

Uninstalling the package does not remove a shell alias or cron entry you installed — see Uninstall for the complete removal.

Option 3 — git clone​

For reading the source, auditing it, or modifying it. The repository contents are what npm publishes.

git clone https://github.com/aoneahsan/linux-cleanup ~/linux-cleanup
cd ~/linux-cleanup
chmod +x cleanup.sh
./cleanup.sh --self-test
./cleanup.sh

The one behavioural difference: a clone keeps its output alongside the source, in <clone>/logs/, <clone>/reports/ and <clone>/feedback/, rather than in ~/.linux-cleanup/. Both are overridable with LINUX_CLEANUP_DATA_HOME. See Output paths.

The project is MIT licensed, so forks and modifications are fine.

Verify before you run anything destructive​

linux-cleanup --version # confirms which build you actually have
linux-cleanup --self-test # dependency, syntax and safety-guard checks

A clean self-test ends with a pass message. It asserts that the protected-path guard really does refuse /, $HOME, ~/Documents, ~/.ssh and /etc, and that it does not refuse ~/.cache/yarn. Any failed assertion exits non-zero.

Run --self-test after every upgrade

It is the only check that runs against the code you actually have rather than against documentation. It takes a second.

Which install path to choose​

If you…Use
Want to try it oncenpx
Will run it regularly, or from cronGlobal npm install
Want to read or modify the sourcegit clone
Are on a machine without Node.jsgit clone
Need output kept next to the sourcegit clone

For cron specifically, prefer a global install and use an absolute path in the crontab — cron runs with a minimal PATH and will not find a ~/.local/bin install. This is the single most common cron problem; see Alias and cron.

What installing does not do​

  • No system service, no background daemon, no scheduled task (until you ask for one)
  • No telemetry agent. On start, the CLI fetches one public release record when online; it continues when offline
  • No shell configuration changes unless you run --install-alias or --doctor
  • No files outside the package and ~/.linux-cleanup/, and the latter only once you actually run it

Next​