cleanix-cli 1.2.0__tar.gz → 1.4.0b1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cleanix_cli-1.4.0b1/PKG-INFO +1013 -0
- cleanix_cli-1.4.0b1/README.md +971 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/RELEASING.md +12 -1
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/__init__.py +2 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/__init__.py +69 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ai_cli.py +5 -1
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ai_tools.py +9 -1
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/app_cruft.py +32 -3
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/base.py +12 -1
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/big_files.py +2 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/browser_profiles.py +18 -4
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/browsers.py +1 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/containers.py +2 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/dev_caches.py +14 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/downloads.py +2 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/duplicates.py +2 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/lang_caches.py +1 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/linux_extras.py +8 -3
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/logs.py +12 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/npm_cache.py +9 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_app_data.py +470 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_common.py +567 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_files.py +382 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_launch_jobs.py +191 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/pip_cache.py +9 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/project_cruft.py +8 -2
- cleanix_cli-1.4.0b1/cleanix/cleaners/stale_launchers.py +352 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/stale_receipts.py +261 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/stale_services.py +349 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/sys_extras.py +7 -3
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/temp_files.py +12 -5
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/thumbnails.py +1 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/user_cache.py +1 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/windows_apps.py +143 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/windows_core.py +105 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/windows_system.py +157 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/windows_wsl.py +58 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_app_paths.py +84 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_base.py +114 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_file_assoc.py +162 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_shared_dlls.py +106 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_startup.py +81 -0
- cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_uninstall.py +185 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cli.py +355 -49
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/completion.py +8 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/config.py +24 -4
- cleanix_cli-1.4.0b1/cleanix/core/catalog.py +184 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/context.py +6 -1
- cleanix_cli-1.4.0b1/cleanix/core/curation.py +303 -0
- cleanix_cli-1.4.0b1/cleanix/core/elevate.py +559 -0
- cleanix_cli-1.4.0b1/cleanix/core/elevate_launch.py +158 -0
- cleanix_cli-1.4.0b1/cleanix/core/engine.py +333 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/history.py +16 -5
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/models.py +79 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/platform.py +10 -1
- cleanix_cli-1.4.0b1/cleanix/core/quarantine.py +696 -0
- cleanix_cli-1.4.0b1/cleanix/core/regbackup.py +1012 -0
- cleanix_cli-1.4.0b1/cleanix/core/regclean.py +469 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/registry.py +5 -0
- cleanix_cli-1.4.0b1/cleanix/core/regpromises.py +54 -0
- cleanix_cli-1.4.0b1/cleanix/core/regsafety.py +296 -0
- cleanix_cli-1.4.0b1/cleanix/core/regsnap.py +190 -0
- cleanix_cli-1.4.0b1/cleanix/core/regtargets.py +543 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/report.py +72 -7
- cleanix_cli-1.4.0b1/cleanix/core/safety.py +486 -0
- cleanix_cli-1.4.0b1/cleanix/core/safety_windows.py +217 -0
- cleanix_cli-1.4.0b1/cleanix/core/scanmode.py +62 -0
- cleanix_cli-1.4.0b1/cleanix/core/service.py +205 -0
- cleanix_cli-1.4.0b1/cleanix/core/utils.py +452 -0
- cleanix_cli-1.4.0b1/cleanix/core/winenv.py +198 -0
- cleanix_cli-1.4.0b1/cleanix/core/winregistry.py +129 -0
- cleanix_cli-1.4.0b1/cleanix/core/winregistry_win.py +317 -0
- cleanix_cli-1.4.0b1/cleanix/elevated.py +1436 -0
- cleanix_cli-1.4.0b1/cleanix/gui/__init__.py +1 -0
- cleanix_cli-1.4.0b1/cleanix/gui/app.py +65 -0
- cleanix_cli-1.4.0b1/cleanix/gui/elevation.py +722 -0
- cleanix_cli-1.4.0b1/cleanix/gui/grouped_results.py +482 -0
- cleanix_cli-1.4.0b1/cleanix/gui/main_window.py +303 -0
- cleanix_cli-1.4.0b1/cleanix/gui/models.py +272 -0
- cleanix_cli-1.4.0b1/cleanix/gui/panels_config.py +434 -0
- cleanix_cli-1.4.0b1/cleanix/gui/panels_data.py +287 -0
- cleanix_cli-1.4.0b1/cleanix/gui/power_view.py +785 -0
- cleanix_cli-1.4.0b1/cleanix/gui/reveal.py +64 -0
- cleanix_cli-1.4.0b1/cleanix/gui/simple_view.py +760 -0
- cleanix_cli-1.4.0b1/cleanix/gui/theme.py +19 -0
- cleanix_cli-1.4.0b1/cleanix/gui/workers.py +302 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/__init__.py +5 -1
- cleanix_cli-1.4.0b1/cleanix/scheduler/schtasks.py +150 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix.1 +19 -3
- cleanix_cli-1.4.0b1/cleanix_cli.egg-info/PKG-INFO +1013 -0
- cleanix_cli-1.4.0b1/cleanix_cli.egg-info/SOURCES.txt +182 -0
- cleanix_cli-1.4.0b1/cleanix_cli.egg-info/entry_points.txt +5 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/requires.txt +7 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/pyproject.toml +10 -3
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/scripts/gen_manpage.py +11 -3
- cleanix_cli-1.4.0b1/tests/test_admin_eligibility.py +135 -0
- cleanix_cli-1.4.0b1/tests/test_catalog.py +160 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/tests/test_cleanix.py +29 -5
- cleanix_cli-1.4.0b1/tests/test_curation.py +247 -0
- cleanix_cli-1.4.0b1/tests/test_elevate.py +1630 -0
- cleanix_cli-1.4.0b1/tests/test_elevate_launch.py +277 -0
- cleanix_cli-1.4.0b1/tests/test_elevated_registry.py +1867 -0
- cleanix_cli-1.4.0b1/tests/test_gui_isolation.py +109 -0
- cleanix_cli-1.4.0b1/tests/test_orphan_app_data.py +504 -0
- cleanix_cli-1.4.0b1/tests/test_orphan_budget.py +128 -0
- cleanix_cli-1.4.0b1/tests/test_orphan_common.py +518 -0
- cleanix_cli-1.4.0b1/tests/test_orphan_files.py +600 -0
- cleanix_cli-1.4.0b1/tests/test_orphan_launch_jobs.py +267 -0
- cleanix_cli-1.4.0b1/tests/test_orphans_wiring.py +88 -0
- cleanix_cli-1.4.0b1/tests/test_owner_matches.py +426 -0
- cleanix_cli-1.4.0b1/tests/test_regbackup.py +1027 -0
- cleanix_cli-1.4.0b1/tests/test_regclean.py +1596 -0
- cleanix_cli-1.4.0b1/tests/test_registry_cli.py +805 -0
- cleanix_cli-1.4.0b1/tests/test_registry_foundation.py +681 -0
- cleanix_cli-1.4.0b1/tests/test_regtargets.py +378 -0
- cleanix_cli-1.4.0b1/tests/test_service.py +212 -0
- cleanix_cli-1.4.0b1/tests/test_stale_launchers.py +390 -0
- cleanix_cli-1.4.0b1/tests/test_stale_receipts.py +394 -0
- cleanix_cli-1.4.0b1/tests/test_stale_services.py +315 -0
- cleanix_cli-1.4.0b1/tests/test_verify_registry_script.py +307 -0
- cleanix_cli-1.4.0b1/tests/test_windows_cleaners_apps.py +142 -0
- cleanix_cli-1.4.0b1/tests/test_windows_cleaners_core.py +123 -0
- cleanix_cli-1.4.0b1/tests/test_windows_cleaners_system.py +160 -0
- cleanix_cli-1.4.0b1/tests/test_windows_cli.py +77 -0
- cleanix_cli-1.4.0b1/tests/test_windows_command_timeout.py +65 -0
- cleanix_cli-1.4.0b1/tests/test_windows_crossplatform.py +377 -0
- cleanix_cli-1.4.0b1/tests/test_windows_encoding.py +62 -0
- cleanix_cli-1.4.0b1/tests/test_windows_env.py +55 -0
- cleanix_cli-1.4.0b1/tests/test_windows_exec_resolution.py +204 -0
- cleanix_cli-1.4.0b1/tests/test_windows_minors.py +234 -0
- cleanix_cli-1.4.0b1/tests/test_windows_platform.py +31 -0
- cleanix_cli-1.4.0b1/tests/test_windows_profiles_cache.py +76 -0
- cleanix_cli-1.4.0b1/tests/test_windows_quarantine.py +217 -0
- cleanix_cli-1.4.0b1/tests/test_windows_rmtree_toctou.py +86 -0
- cleanix_cli-1.4.0b1/tests/test_windows_safety_integration.py +286 -0
- cleanix_cli-1.4.0b1/tests/test_windows_safety_model.py +149 -0
- cleanix_cli-1.4.0b1/tests/test_windows_safety_profiles.py +154 -0
- cleanix_cli-1.4.0b1/tests/test_windows_scheduler.py +145 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_app_paths.py +282 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_backend.py +944 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_file_assoc.py +461 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_shared_dlls.py +280 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_startup.py +253 -0
- cleanix_cli-1.4.0b1/tests/test_winreg_uninstall.py +390 -0
- cleanix_cli-1.2.0/PKG-INFO +0 -521
- cleanix_cli-1.2.0/README.md +0 -486
- cleanix_cli-1.2.0/cleanix/core/engine.py +0 -155
- cleanix_cli-1.2.0/cleanix/core/quarantine.py +0 -147
- cleanix_cli-1.2.0/cleanix/core/safety.py +0 -211
- cleanix_cli-1.2.0/cleanix/core/utils.py +0 -244
- cleanix_cli-1.2.0/cleanix_cli.egg-info/PKG-INFO +0 -521
- cleanix_cli-1.2.0/cleanix_cli.egg-info/SOURCES.txt +0 -86
- cleanix_cli-1.2.0/cleanix_cli.egg-info/entry_points.txt +0 -2
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/MANIFEST.in +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/__main__.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apple_litter.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apps.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apt.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/broken_symlinks.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/bsd.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/containerd.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/coredumps.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/desktop_extras.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/distro_pkg.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/dnf.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/editor_litter.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/font_cache.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ide.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/kernels.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/localizations.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/macos.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/macos_extra.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/memory.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/more_pkg.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/packaging_extras.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/pacman.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/snapshots.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/toolchains.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/trash.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/virtualization.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/__init__.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/reset.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/cron.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/launchd.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/systemd.py +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/dependency_links.txt +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/top_level.txt +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/README.md +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/aur/PKGBUILD +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/homebrew/cleanix.rb +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/rpm/cleanix-cli.spec +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/requirements.txt +0 -0
- {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/setup.cfg +0 -0
|
@@ -0,0 +1,1013 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cleanix-cli
|
|
3
|
+
Version: 1.4.0b1
|
|
4
|
+
Summary: A safe, thorough scheduled system cleaner for every *nix (Linux, macOS, BSD) and Windows.
|
|
5
|
+
Author: cleanix-cli contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/CloudOpsWorld/cleanix-cli
|
|
8
|
+
Project-URL: Repository, https://github.com/CloudOpsWorld/cleanix-cli
|
|
9
|
+
Project-URL: Issues, https://github.com/CloudOpsWorld/cleanix-cli/issues
|
|
10
|
+
Keywords: cleaner,cleanup,system,maintenance,linux,macos,bsd,windows,cache
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Environment :: X11 Applications :: Qt
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: Intended Audience :: System Administrators
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
18
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
19
|
+
Classifier: Operating System :: POSIX :: BSD
|
|
20
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
26
|
+
Classifier: Topic :: System :: Systems Administration
|
|
27
|
+
Classifier: Topic :: Utilities
|
|
28
|
+
Requires-Python: >=3.10
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
Requires-Dist: rich>=15.0.0
|
|
31
|
+
Requires-Dist: PyYAML>=6.0.3
|
|
32
|
+
Provides-Extra: gui
|
|
33
|
+
Requires-Dist: PySide6<7,>=6.6; extra == "gui"
|
|
34
|
+
Provides-Extra: gui-test
|
|
35
|
+
Requires-Dist: PySide6<7,>=6.6; extra == "gui-test"
|
|
36
|
+
Requires-Dist: pytest-qt>=4.4; extra == "gui-test"
|
|
37
|
+
Provides-Extra: dev
|
|
38
|
+
Requires-Dist: pytest>=9.1.1; extra == "dev"
|
|
39
|
+
Requires-Dist: ruff>=0.15.21; extra == "dev"
|
|
40
|
+
Requires-Dist: mypy>=2.3.0; extra == "dev"
|
|
41
|
+
Requires-Dist: build>=1.5.1; extra == "dev"
|
|
42
|
+
|
|
43
|
+
# Cleanix CLI
|
|
44
|
+
|
|
45
|
+
[](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml)
|
|
46
|
+
[](https://pypi.org/project/cleanix-cli/)
|
|
47
|
+
[](https://pypi.org/project/cleanix-cli/)
|
|
48
|
+
[](https://opensource.org/licenses/MIT)
|
|
49
|
+
|
|
50
|
+
A safe, thorough system cleaner for **every *nix flavour** — Linux (all
|
|
51
|
+
major distros), macOS, and the BSDs — and **Windows**. It **analyzes** your OS for junk — caches,
|
|
52
|
+
temp files, package-manager leftovers, orphaned packages, broken symlinks,
|
|
53
|
+
package-update config residue, rotated logs, trash, thumbnails, browser/dev
|
|
54
|
+
caches, container cruft — and only **removes** anything after you confirm.
|
|
55
|
+
|
|
56
|
+
It can run on a **schedule** (a systemd timer on Linux/BSD, a launchd agent on
|
|
57
|
+
macOS, a Task Scheduler task on Windows) to periodically analyze the
|
|
58
|
+
system and notify you (on Windows the report file is the output; no
|
|
59
|
+
notification is shown). Scheduled runs *never delete anything*; they only produce
|
|
60
|
+
a report so you can review and clean on your own terms.
|
|
61
|
+
|
|
62
|
+
## Platform support
|
|
63
|
+
|
|
64
|
+
Cleaners declare which platforms they apply to; `cleanix` auto-detects the OS
|
|
65
|
+
(and Linux distro via `/etc/os-release`) and only runs the relevant ones.
|
|
66
|
+
|
|
67
|
+
| Family | Detected as | Package/system cleaners |
|
|
68
|
+
|----------|------------------------------------|-------------------------|
|
|
69
|
+
| Linux | `linux` + distro id | apt, dnf/yum, pacman, zypper, apk, xbps, portage, flatpak, snap, nix, journald, coredumps, `/var/crash`, `.rpmnew`/`.pacnew`/`.dpkg-old` residue |
|
|
70
|
+
| macOS | `macos` | Homebrew, MacPorts, Xcode (DerivedData/DeviceSupport/simulators), ~/Library caches & logs, Trash |
|
|
71
|
+
| FreeBSD | `freebsd` | pkg cache + autoremove, ports distfiles & work dirs |
|
|
72
|
+
| NetBSD | `netbsd` | pkg, pkgin cache |
|
|
73
|
+
| OpenBSD | `openbsd` | pkg |
|
|
74
|
+
| Windows | `windows` | `%TEMP%`, thumbnail/icon caches, error reports & crash dumps, Recycle Bin, Windows Update/Delivery Optimization cache, system temp & dumps (admin), browser caches (Chrome/Edge/Brave/Firefox), DirectX/NVIDIA/AMD shader caches, WinGet/Chocolatey/Scoop/NuGet caches, Visual Studio cache; report-only: Prefetch, `Windows.old`, WSL disks; opt-in: DISM component store, dead registry entries (see [Windows registry cleaners](#windows-registry-cleaners-opt-in)); Task Scheduler |
|
|
75
|
+
| Cross-OS | all of the above | trash, thumbnails, ~/.cache, temp files, fonts, browser caches, broken symlinks, `.DS_Store`/AppleDouble, dev/language caches (cargo/go/gradle/ccache/composer/…), pip, npm/yarn, Docker, Podman |
|
|
76
|
+
|
|
77
|
+
Run `cleanix list` to see what applies to your machine, or `cleanix list --all`
|
|
78
|
+
to see every platform's cleaners.
|
|
79
|
+
|
|
80
|
+
## Windows notes
|
|
81
|
+
|
|
82
|
+
- Config is `%APPDATA%\cleanix\config.yaml`; state, history and quarantine live
|
|
83
|
+
under `%LOCALAPPDATA%\cleanix`. Cleanix deletes registry entries only
|
|
84
|
+
through the five opt-in registry cleaners (see
|
|
85
|
+
[Windows registry cleaners](#windows-registry-cleaners-opt-in)): they are
|
|
86
|
+
never part of a normal scan or clean and never run from the scheduled scan.
|
|
87
|
+
(It also stores its GUI settings under `HKCU\Software\Cleanix` and reads the
|
|
88
|
+
profile list; no other cleaner touches the registry.)
|
|
89
|
+
- Items that need admin rights (`win_system_temp`, `win_update_cache`,
|
|
90
|
+
`win_system_dumps`, DISM) require an **elevated terminal** (Run as
|
|
91
|
+
administrator); otherwise they are skipped with a note.
|
|
92
|
+
- **Report-only:** Prefetch, `Windows.old` and WSL virtual disks (`wsl_disk`)
|
|
93
|
+
are sized and explained, never deleted.
|
|
94
|
+
- **DISM component-store cleanup is opt-in:**
|
|
95
|
+
`cleanix clean --only win_component_store --execute` (elevated).
|
|
96
|
+
- **Quarantine moves path-based items only.** Command items such as emptying
|
|
97
|
+
the Recycle Bin and DISM cannot be undone with `cleanix restore`. Registry
|
|
98
|
+
entries are not moved: before one is deleted, a `.reg` and a `.json` backup
|
|
99
|
+
of it is written into a quarantine run (even when "keep a copy" is off).
|
|
100
|
+
Whether Cleanix promises that these can be restored is a separate, gated
|
|
101
|
+
statement; see [Windows registry cleaners](#windows-registry-cleaners-opt-in).
|
|
102
|
+
- `cleanix schedule install` creates a per-user, scan-only Task Scheduler task
|
|
103
|
+
named "Cleanix Scan" (it never cleans). It does not raise a notification:
|
|
104
|
+
the JSON report at `%LOCALAPPDATA%\cleanix\last-scan.json` is the output.
|
|
105
|
+
- External tools are never looked up in the current directory: PowerShell,
|
|
106
|
+
DISM and schtasks run from the System32 directory, everything else (e.g.
|
|
107
|
+
`docker`) only from absolute `PATH` entries.
|
|
108
|
+
- Quarantine across volumes refuses folders that contain a junction or
|
|
109
|
+
symlink (they are never copied); a locked file makes the item fail with
|
|
110
|
+
nothing copied, and any copy that has to be kept is listed by
|
|
111
|
+
`cleanix quarantine list`.
|
|
112
|
+
- **Residual limits (elevated runs).** `C:\Windows\Temp` is writable by
|
|
113
|
+
standard users. Before descending into each folder the remover re-checks
|
|
114
|
+
that it is still the same plain folder (not swapped for a junction), but a
|
|
115
|
+
swap in the short window between that check and the deletion is not
|
|
116
|
+
prevented (that needs handle-relative NT APIs), and entries in
|
|
117
|
+
`Windows\Temp` are not filtered by owner. If untrusted local users share the
|
|
118
|
+
machine, exclude that cleaner (`--exclude win_system_temp`).
|
|
119
|
+
- `cleanix factory-reset` is not supported on Windows.
|
|
120
|
+
- The AI-tool, dev-cache, pip/npm, Docker, Electron, JetBrains, big-file,
|
|
121
|
+
duplicate, downloads, stale-project and browser-profile cleaners also run on
|
|
122
|
+
Windows.
|
|
123
|
+
|
|
124
|
+
## AI / LLM leftovers (triaged, not nuked)
|
|
125
|
+
|
|
126
|
+
Local AI tooling scatters a lot of disposable junk *and* a lot of data you
|
|
127
|
+
deliberately downloaded. Cleanix **triages** — it removes the trash and leaves
|
|
128
|
+
your models and chat history alone:
|
|
129
|
+
|
|
130
|
+
| Tool | Removed (trash) | Kept (your data) |
|
|
131
|
+
|------|-----------------|------------------|
|
|
132
|
+
| **Ollama** | dangling blobs from interrupted pulls, server logs | installed models (referenced blobs/manifests) |
|
|
133
|
+
| **Hugging Face** | `*.incomplete` downloads, `.locks`, `.no_exist` | downloaded model/dataset weights |
|
|
134
|
+
| **PyTorch/Triton/vLLM/CUDA** | Triton, `torch.compile`/inductor, `torch_extensions`, vLLM, `~/.nv/ComputeCache`, FlashInfer JIT caches | — (all pure compile caches) |
|
|
135
|
+
| **LM Studio / Jan** | server logs | models, presets, conversations |
|
|
136
|
+
| **Continue.dev** | rebuildable embeddings index, logs, telemetry | sessions/config |
|
|
137
|
+
| **Claude Code** | throwaway shell snapshots, telemetry cache | projects, history |
|
|
138
|
+
| **Aider** | stray `.aider.tags.cache.*`, `.aider.chat.history.md`, `.aider.input.history` in project trees | — |
|
|
139
|
+
|
|
140
|
+
### AI coding-agent CLIs (retention-aware)
|
|
141
|
+
|
|
142
|
+
These accumulate rolling backups, per-session file-history/checkpoints, debug
|
|
143
|
+
logs, and transcripts that no built-in command reliably prunes. Cleanix applies
|
|
144
|
+
proper **retention** instead of all-or-nothing deletion:
|
|
145
|
+
|
|
146
|
+
| Tool | Removed | Kept |
|
|
147
|
+
|------|---------|------|
|
|
148
|
+
| **Claude Code** (`~/.claude`) | rolling `.claude.json` backups beyond the newest `keep_backups` (default 2); debug/telemetry/paste/download/changelog caches; stale (>`ai_history_max_age_days`) file-history & transcripts | `~/.claude.json`, `settings.json`, `plugins/`, credentials, **and any currently-running session** |
|
|
149
|
+
| **OpenAI Codex** (`~/.codex`) | session rollouts & TUI logs older than the retention age | recent sessions, config |
|
|
150
|
+
| **Gemini CLI** (`~/.gemini/tmp`) | stale per-project session/log data | config, recent sessions |
|
|
151
|
+
| **OpenCode** (`~/.local/share/opencode`) | logs, snapshots, tool-output | the SQLite DB, auth, storage |
|
|
152
|
+
|
|
153
|
+
Two knobs control retention (see `config/default.yaml`):
|
|
154
|
+
|
|
155
|
+
- `keep_backups: 2` — how many newest rolling backups to keep.
|
|
156
|
+
- `ai_history_max_age_days: 30` — transcripts/history/logs older than this are
|
|
157
|
+
offered (chat history is your data, so it's age-gated and conservative).
|
|
158
|
+
|
|
159
|
+
Per-session scratch (todos, shell snapshots, session env) touched within the
|
|
160
|
+
last day is always left alone, so cleaning never disturbs a live agent session.
|
|
161
|
+
|
|
162
|
+
## General app bloat
|
|
163
|
+
|
|
164
|
+
- **Electron/Chromium apps** (VS Code, Slack, Discord, Signal, Obsidian, …):
|
|
165
|
+
removes only rebuildable `Cache`/`Code Cache`/`GPUCache`/`Dawn*Cache`/
|
|
166
|
+
`CachedData`/`Crashpad` — **never** `Local Storage`, `IndexedDB`,
|
|
167
|
+
`Service Worker`, or cookies (so you stay logged in). Covers both
|
|
168
|
+
`~/.config/*` and Flatpak (`~/.var/app/*`) apps.
|
|
169
|
+
- **Flatpak app caches** — every app's `~/.var/app/*/cache`.
|
|
170
|
+
- **GPU shader caches** — Mesa (`mesa_shader_cache[_db]`), NVIDIA `GLCache`,
|
|
171
|
+
RADV/AMD Vulkan caches (rebuilt after driver updates).
|
|
172
|
+
- **Steam** — per-game shader caches, interrupted downloads, HTTP cache.
|
|
173
|
+
- **JetBrains IDEs** — caches, logs, and indexes (Linux `~/.cache/JetBrains`,
|
|
174
|
+
macOS `~/Library/Caches/JetBrains`).
|
|
175
|
+
|
|
176
|
+
Cleaners never offer the same path twice: dedicated cleaners own their
|
|
177
|
+
directories and the generic `~/.cache` catch-all defers to them.
|
|
178
|
+
|
|
179
|
+
## More reclamation & review
|
|
180
|
+
|
|
181
|
+
- **Old toolchain versions** (`toolchains`). Version managers hoard
|
|
182
|
+
multi-gigabyte installed runtimes — old `~/.nvm` node builds, `~/.pyenv` /
|
|
183
|
+
`~/.rbenv` versions, `rustup` toolchains, SDKMAN candidates, `asdf` installs.
|
|
184
|
+
Cleanix keeps the **active** version (always protected) plus the newest
|
|
185
|
+
`keep_toolchain_versions` (default 2) and offers the rest for removal. It
|
|
186
|
+
*skips a manager entirely if it can't prove which version is active* — pair
|
|
187
|
+
with `clean --quarantine` to make removals reversible. Disable with
|
|
188
|
+
`prune_old_toolchains: false`.
|
|
189
|
+
- **Stale project cruft** (`project_cruft`, report-only). Finds regenerable
|
|
190
|
+
`node_modules` / `.venv` / `target` / `.gradle` dirs in projects under
|
|
191
|
+
`project_scan_dirs` you haven't touched in `project_stale_days` (default 120).
|
|
192
|
+
- **Large files** (`big_files`, report-only). The biggest files in `$HOME`, so
|
|
193
|
+
you can see what filled the disk. Never deletes — just a sized list + `rm` hint.
|
|
194
|
+
- **Duplicate files** (`duplicates`, report-only). Identical large files (same
|
|
195
|
+
size + SHA-256) grouped with the space reclaimable by keeping one copy.
|
|
196
|
+
- **Stale downloads** (`downloads`, report-only). Old, large installers/ISOs in
|
|
197
|
+
`~/Downloads` (which stays hard-protected from deletion).
|
|
198
|
+
- **Orphaned browser profiles** (`browser_profiles`, report-only). Secondary
|
|
199
|
+
Chrome/Chromium/Firefox profiles idle for `browser_profile_stale_days`, with a
|
|
200
|
+
clear warning that a profile holds bookmarks/passwords/history.
|
|
201
|
+
|
|
202
|
+
## System-wide leftovers (report-only, Linux/macOS)
|
|
203
|
+
|
|
204
|
+
Seven detectors look for things that were left behind when a program was
|
|
205
|
+
removed. They only **report**: nothing is deleted, nothing is preselected, and
|
|
206
|
+
there is no way to clean them from Cleanix. Each finding names the exact path;
|
|
207
|
+
system-level findings also include a command that confirms ownership
|
|
208
|
+
(`dpkg -S`, `rpm -qf`, `pacman -Qo`) where a package backend
|
|
209
|
+
exists, while user-level ones may not, so you decide. They appear under "Needs your review"
|
|
210
|
+
and in `cleanix scan`. They work without root; anything they cannot read is
|
|
211
|
+
listed as a "Not checked" note instead of being guessed, and a command that
|
|
212
|
+
fails or prints something unexpected never counts as "orphaned".
|
|
213
|
+
|
|
214
|
+
| id | OS | Reports |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| `orphan_files` (opt-in) | Linux | Folders in `/opt`, `/usr/local`, `/var/lib` and `/var/cache` that no installed package owns |
|
|
217
|
+
| `stale_services` | Linux | systemd units, drop-ins and enable links in administrator-owned unit folders whose program or unit file is gone |
|
|
218
|
+
| `stale_launchers` | Linux | `.desktop` menu and autostart entries whose program is missing |
|
|
219
|
+
| `stale_alternatives` | Linux | Broken links in `/etc/alternatives` |
|
|
220
|
+
| `orphan_launch_jobs` | macOS | LaunchAgents/LaunchDaemons whose program no longer exists |
|
|
221
|
+
| `orphan_app_data` | macOS | Application Support, Containers and Preferences left by apps that are no longer installed |
|
|
222
|
+
| `stale_receipts` | macOS | Installer receipts whose installed files are all gone |
|
|
223
|
+
|
|
224
|
+
`orphan_files` is off by default because it walks several large trees. Run it
|
|
225
|
+
explicitly with `cleanix scan --only orphan_files` (it shows as `opt-in` in
|
|
226
|
+
the `default` column of `cleanix list`); Simple mode never runs it. The others run in a normal scan.
|
|
227
|
+
|
|
228
|
+
Known limits, read these before acting on a finding:
|
|
229
|
+
|
|
230
|
+
- Ownership lookups exist only for dpkg (Debian/Ubuntu), rpm (Fedora/openSUSE)
|
|
231
|
+
and pacman (Arch). On other distributions `orphan_files` reports nothing.
|
|
232
|
+
- On macOS the app-data check understands only reverse-DNS names
|
|
233
|
+
(`com.vendor.App`); folders named after the app ("Slack") are never reported.
|
|
234
|
+
- The macOS detectors have only been tested against fake data, not on a real
|
|
235
|
+
Mac. Treat their findings with extra care.
|
|
236
|
+
- `orphan_files` skips folders that look like live service data (k3s,
|
|
237
|
+
kubelet, container runtimes and similar) and anything changed within
|
|
238
|
+
`orphan_min_age_days`, but a program that creates its own folders at runtime
|
|
239
|
+
can still be reported; every finding says so. Check what uses a path first.
|
|
240
|
+
- The two macOS leftover reports that run `mdfind`/`pkgutil` (`orphan_app_data`
|
|
241
|
+
and `stale_receipts`) only run in a Deep scan in Simple mode.
|
|
242
|
+
- Notes ("Not checked", "Scan stopped early") are listed like findings: they
|
|
243
|
+
show up in the item counts and in `--json` output with size 0. A distinct
|
|
244
|
+
marker is a planned change.
|
|
245
|
+
- Any finding may be a false positive; confirm before removing anything
|
|
246
|
+
(with your package manager where one applies).
|
|
247
|
+
|
|
248
|
+
Already covered by other cleaners and therefore not repeated here: dpkg `rc`
|
|
249
|
+
packages (`apt`), `.dpkg-old`/`.rpmsave`/`.pacnew` files (`config_leftovers`),
|
|
250
|
+
AppImage menu entries (`appimage`), broken symlinks (`broken_symlinks`),
|
|
251
|
+
`~/Library/Caches` (`macos_caches`), saved application state (`macos_extra`)
|
|
252
|
+
and old Homebrew versions (`homebrew`).
|
|
253
|
+
|
|
254
|
+
Three config keys tune the scans: `orphan_max_items` (default 200 findings per
|
|
255
|
+
detector), `orphan_max_seconds` (default 60 s per detector; when it runs out
|
|
256
|
+
one note says the results are incomplete) and `orphan_min_age_days` (default
|
|
257
|
+
30; macOS app data and `orphan_files` entries touched more recently than this
|
|
258
|
+
are not reported; 0 turns the check off).
|
|
259
|
+
|
|
260
|
+
## Working with what a scan finds
|
|
261
|
+
|
|
262
|
+
- `cleanix explain <id>` — read-only, shows the **exact** paths/commands one
|
|
263
|
+
cleaner would consider (with size, root, delete-vs-report), for building trust.
|
|
264
|
+
- `cleanix clean --interactive` — pick individual items from a checklist before
|
|
265
|
+
removing (selection is per-item, not just per-cleaner).
|
|
266
|
+
- `cleanix clean --simulate` — write the exact target list to a file, delete
|
|
267
|
+
nothing (stronger than the dry-run summary).
|
|
268
|
+
- `cleanix clean --execute` — writes a **per-file audit manifest** to
|
|
269
|
+
`~/.local/state/cleanix/runs/` and prints the real `df` free-space change.
|
|
270
|
+
- `--profile safe|balanced|aggressive` — one flag to bundle the opt-in settings
|
|
271
|
+
(aggressive enables offline-repo/backup/locale/all-image pruning; it never
|
|
272
|
+
bundles volume removal).
|
|
273
|
+
- `--min-size 100M` — ignore items below a threshold to cut table noise.
|
|
274
|
+
- `cleanix scan --json` emits a **versioned** schema (`schema_version`, host,
|
|
275
|
+
os, `cleanable_bytes` vs `report_only_bytes`) for CI/tooling.
|
|
276
|
+
- `cleanix dashboard` — lifetime reclaim trend (sparkline) plus the last
|
|
277
|
+
scheduled scan's top sources, at a glance.
|
|
278
|
+
|
|
279
|
+
## Install & packaging
|
|
280
|
+
|
|
281
|
+
- **PyPI:** `pip install cleanix-cli` (or `pipx install cleanix-cli`); add the
|
|
282
|
+
`gui` extra for the desktop GUI (see [Graphical interface](#graphical-interface)).
|
|
283
|
+
Standalone GUI installers are planned (Plan 2B).
|
|
284
|
+
- **Standalone binaries** are attached to each [GitHub Release] alongside a
|
|
285
|
+
`SHA256SUMS` file and keyless **build-provenance attestations** — verify a
|
|
286
|
+
download with `gh attestation verify <file> --repo CloudOpsWorld/cleanix-cli`.
|
|
287
|
+
- **Homebrew / AUR / Fedora** packaging lives under [`packaging/`](packaging/),
|
|
288
|
+
along with a `cleanix.1` **man page** generated from the CLI
|
|
289
|
+
(`python scripts/gen_manpage.py`).
|
|
290
|
+
|
|
291
|
+
[GitHub Release]: https://github.com/CloudOpsWorld/cleanix-cli/releases
|
|
292
|
+
|
|
293
|
+
## Container leftovers (Docker / Podman / nerdctl / crictl)
|
|
294
|
+
|
|
295
|
+
A *leftover* is anything the engine keeps that **no existing container
|
|
296
|
+
references** and can be regenerated. Each category is surfaced as its own item
|
|
297
|
+
whose estimated size matches exactly what pruning it reclaims — so the number
|
|
298
|
+
you see is the number you get (no more counting unused-but-tagged images or
|
|
299
|
+
volumes you never asked to touch):
|
|
300
|
+
|
|
301
|
+
- **Dangling (untagged) images** — `docker image prune -f`
|
|
302
|
+
- **Stopped containers** (writable layers) — `docker container prune -f`
|
|
303
|
+
- **Build cache** — `docker builder prune -f`
|
|
304
|
+
- **Unused networks** — `docker network prune -f`
|
|
305
|
+
|
|
306
|
+
Two categories stay **opt-in** because they can destroy real work:
|
|
307
|
+
|
|
308
|
+
- `docker_prune_all_images` — also remove *tagged* images not used by any
|
|
309
|
+
container (`image prune -a`); frees more but forces a re-pull next time.
|
|
310
|
+
- `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
|
|
311
|
+
databases or other real data.
|
|
312
|
+
|
|
313
|
+
> On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
|
|
314
|
+
> space *inside* the VM; the host-side `Docker.raw` file may not shrink until
|
|
315
|
+
> Docker Desktop compacts it.
|
|
316
|
+
|
|
317
|
+
## Shell completion
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
cleanix completion bash | sudo tee /etc/bash_completion.d/cleanix
|
|
321
|
+
cleanix completion zsh > ~/.zfunc/_cleanix # a dir on your $fpath
|
|
322
|
+
cleanix completion fish > ~/.config/fish/completions/cleanix.fish
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Completes subcommands, options, cleaner ids (for `--only`/`--exclude`) and config
|
|
326
|
+
keys — baked in from the live build.
|
|
327
|
+
|
|
328
|
+
## Safe memory reclamation (RAM + swap)
|
|
329
|
+
|
|
330
|
+
Opt-in cleaners that free memory **without ever killing or trimming apps**:
|
|
331
|
+
|
|
332
|
+
```bash
|
|
333
|
+
sudo cleanix clean --only memory --execute # drop clean page/dentry/inode cache
|
|
334
|
+
sudo cleanix clean --only swap --execute # move swap back to RAM (OOM-guarded)
|
|
335
|
+
sudo cleanix clean --only memory_macos --execute # macOS `purge`
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
- `memory` runs `sync` then `drop_caches` — the kernel only releases *clean*
|
|
339
|
+
cached pages, re-reading from disk later; no process loses data.
|
|
340
|
+
- `swap` runs `swapoff -a && swapon -a` **only when free RAM comfortably exceeds
|
|
341
|
+
swap in use** (20% headroom), so it can never trigger an OOM kill.
|
|
342
|
+
- These are excluded from the default `scan`/`clean` (their effect is transient);
|
|
343
|
+
run them explicitly with `--only`.
|
|
344
|
+
|
|
345
|
+
## IDE & application coverage
|
|
346
|
+
|
|
347
|
+
- **IDEs** (`ide_caches`): VS Code and forks (VSCodium, Cursor, Windsurf, …)
|
|
348
|
+
logs / `CachedExtensionVSIXs` / stale workspace storage, Sublime, Atom, Emacs
|
|
349
|
+
native-comp cache, Zed logs, Qt Creator, Godot, Unity — plus JetBrains and
|
|
350
|
+
Xcode via their dedicated cleaners.
|
|
351
|
+
- **Apps** (`app_leftovers`, `snap_app_cache`): logs/crash-reports/temp for
|
|
352
|
+
Minecraft, Steam, Heroic, Lutris, Bottles, OBS, Zoom, Skype, Kodi, Nextcloud,
|
|
353
|
+
Dropbox, Ferdium/Rambox, browser crash reports, and every snap's per-app cache.
|
|
354
|
+
|
|
355
|
+
## Reversible cleaning, history & dashboard
|
|
356
|
+
|
|
357
|
+
- **Quarantine (undo):** `cleanix clean --quarantine` *moves* junk into a
|
|
358
|
+
per-run quarantine instead of deleting it. Undo with `cleanix restore`, reclaim
|
|
359
|
+
the space for good with `cleanix quarantine empty`, review with
|
|
360
|
+
`cleanix quarantine list`. A safety net most cleaners don't offer.
|
|
361
|
+
- **History & stats:** every real clean is logged; `cleanix stats` shows lifetime
|
|
362
|
+
space reclaimed and recent runs.
|
|
363
|
+
- **`cleanix info`:** one-glance dashboard — OS/distro, detected package
|
|
364
|
+
managers, applicable cleaner counts, config path, lifetime cleaned, quarantine
|
|
365
|
+
size.
|
|
366
|
+
- **Parallel scanning** across a thread pool (≈1.4×+ faster), with a live
|
|
367
|
+
progress bar.
|
|
368
|
+
- **`scan --sort size --top N`** to focus on the biggest wins.
|
|
369
|
+
- **User ignore-globs:** `protected_globs` in config adds your own never-delete
|
|
370
|
+
paths on top of the built-in guard.
|
|
371
|
+
|
|
372
|
+
## Highlights
|
|
373
|
+
|
|
374
|
+
- **Scan first, clean on confirmation.** Nothing is deleted without an explicit
|
|
375
|
+
`--yes` or an interactive confirmation.
|
|
376
|
+
- **Dry-run by default.** `cleanix clean` shows what *would* be removed unless you
|
|
377
|
+
pass `--execute`.
|
|
378
|
+
- **Safe deletes.** A hard-coded protected-path guard refuses to touch critical
|
|
379
|
+
system directories on every platform (`/`, `/etc`, `/usr`, `/System`,
|
|
380
|
+
`/Library`, `$HOME`, `~/Library`, `/usr/ports`, ...).
|
|
381
|
+
- **Orphan & leftover aware.** Finds orphaned packages, residual configs
|
|
382
|
+
(dpkg `rc` state), package-update residue (`.rpmnew`/`.pacnew`/`.dpkg-old`),
|
|
383
|
+
dangling symlinks, and orphaned launcher entries — the cruft "improperly
|
|
384
|
+
designed" packages leave behind.
|
|
385
|
+
- **Accurate sizing.** Uses actual allocated blocks, not apparent size, so
|
|
386
|
+
sparse files don't wildly overstate reclaimable space. Actively-written files
|
|
387
|
+
are left alone (in-use guard).
|
|
388
|
+
- **Modular & platform-gated.** Each junk source is an isolated, auditable module
|
|
389
|
+
that declares the platforms it applies to.
|
|
390
|
+
- **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
|
|
391
|
+
note) when you run unprivileged.
|
|
392
|
+
- **Scheduling.** Install a periodic read-only scan that reports (and notifies;
|
|
393
|
+
on Windows the report file is the output)
|
|
394
|
+
on a daily/weekly/monthly cadence — a **systemd user timer** on Linux, a
|
|
395
|
+
**launchd LaunchAgent** on macOS, a per-user **Task Scheduler** task on
|
|
396
|
+
Windows, and a **cron job** on the BSDs (or any
|
|
397
|
+
system with `crontab` but no systemd). Same `cleanix schedule` command on all.
|
|
398
|
+
|
|
399
|
+
## Install
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
pip install cleanix-cli # from PyPI
|
|
403
|
+
# or from source:
|
|
404
|
+
cd cleanix-cli && pip install -e .
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
This installs the `cleanix` command. Standalone Linux/macOS binaries are also
|
|
408
|
+
attached to each [GitHub Release](https://github.com/CloudOpsWorld/cleanix-cli/releases).
|
|
409
|
+
|
|
410
|
+
## Graphical interface
|
|
411
|
+
|
|
412
|
+
An optional desktop GUI (Qt / PySide6) runs the same engine as the CLI, in
|
|
413
|
+
the same process: the same scan, the same safety guard, the same quarantine
|
|
414
|
+
and history.
|
|
415
|
+
|
|
416
|
+
```bash
|
|
417
|
+
pip install "cleanix-cli[gui]" # adds PySide6; the CLI never needs it
|
|
418
|
+
cleanix gui # or: cleanix-gui
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Without the extra, `cleanix gui` prints the install hint and the CLI keeps
|
|
422
|
+
working. Standalone GUI installers (Windows installer, macOS `.dmg`, Linux
|
|
423
|
+
AppImage) are coming in a later release (Plan 2B); for now install with pip.
|
|
424
|
+
|
|
425
|
+
**Simple and Power.** A toolbar switch at the top picks the mode; the choice
|
|
426
|
+
is remembered. Both modes show scan results as a short list of plain-language
|
|
427
|
+
groups instead of raw paths. Each group has a title, a one-line explanation,
|
|
428
|
+
the item count, the total size and a **safety badge**. The badge always spells
|
|
429
|
+
the level out in words (colour is only a hint):
|
|
430
|
+
|
|
431
|
+
- **Safe**: rebuilt automatically; can be cleaned from Simple mode.
|
|
432
|
+
- **Review**: needs your judgment. Report-only findings are never deleted by
|
|
433
|
+
Cleanix (their row says why and, where there is one, how to remove them by
|
|
434
|
+
hand). Other Review items can be cleaned only from Power mode; in Simple
|
|
435
|
+
mode they are listed read-only.
|
|
436
|
+
- **Needs admin**: needs administrator permission and cannot be undone;
|
|
437
|
+
tickable only when administrator cleaning is available and the helper would
|
|
438
|
+
clean it, otherwise shown read-only with the reason.
|
|
439
|
+
- **Permanent**: cannot be undone (command items, for example emptying the
|
|
440
|
+
Windows Recycle Bin or pruning containers).
|
|
441
|
+
|
|
442
|
+
A group shows its biggest items (top 15) and folds the rest into one
|
|
443
|
+
"N smaller items" row; double-click it (or Enter, or right-click and Show all)
|
|
444
|
+
to list them. Items with nothing to reclaim are hidden. Command items, whose
|
|
445
|
+
size is only an estimate, are never hidden for being 0 B. Hover a row for the
|
|
446
|
+
full path and any manual-removal hint; right-click an item for Copy path and
|
|
447
|
+
Open location.
|
|
448
|
+
|
|
449
|
+
**Simple mode** (the default) is Scan, review, Clean, Undo. A **Deep scan**
|
|
450
|
+
checkbox (off by default) adds the slow cleaners (duplicates, big files,
|
|
451
|
+
downloads and the two macOS leftover reports, install records and data of
|
|
452
|
+
removed apps); a normal scan skips them. Results are split into three lists: the
|
|
453
|
+
main list holds groups with something pre-selected, "Also found (not
|
|
454
|
+
selected)" holds the Permanent and Needs admin groups, and "Needs your
|
|
455
|
+
review" holds the Review groups. Simple mode only lets you tick reviewed-safe
|
|
456
|
+
cleaners and the Trash and System groups; everything else (including cleaners
|
|
457
|
+
Cleanix does not know) is read-only there. Only files from reviewed-safe cleaners that
|
|
458
|
+
your normal user can delete are pre-selected; nothing that needs
|
|
459
|
+
administrator permission, nothing irreversible and no personal data is ever
|
|
460
|
+
pre-selected. Before cleaning, a confirmation shows the count and size and
|
|
461
|
+
offers **"Keep a copy so I can undo"**, ticked by default: files are moved
|
|
462
|
+
into quarantine instead of deleted (they use disk space until you empty it).
|
|
463
|
+
|
|
464
|
+
**Power mode** shows the same curated groups for every cleaner you choose to
|
|
465
|
+
scan ("Choose what to scan"), with a detail pane, JSON export and tabs for
|
|
466
|
+
Quarantine (restore, delete a run, empty all), History, Schedule, Settings
|
|
467
|
+
(every config key, including `protected_globs`) and Findings (report-only
|
|
468
|
+
items, with Reveal in the file manager; never deleted). Extra controls:
|
|
469
|
+
|
|
470
|
+
- **Raw list** toggles between the curated groups and the full sortable,
|
|
471
|
+
filterable table of every item.
|
|
472
|
+
- Quick selects: **Select all visible**, **Select none**, **Safe only** and
|
|
473
|
+
**Developer** act on the rows currently visible (filter and safety level).
|
|
474
|
+
- A safety-level filter, a text filter and **Show empty** (lists zero-size
|
|
475
|
+
items and lets you tick them).
|
|
476
|
+
|
|
477
|
+
Settings saved in the Settings tab apply to the running GUI from the next scan
|
|
478
|
+
or clean (no restart needed). **Dry run is ticked by default**; untick it to
|
|
479
|
+
clean for real. A dry run never asks for administrator permission: items that
|
|
480
|
+
need it are listed as a preview ("would be removed after one administrator
|
|
481
|
+
prompt"). "Keep a copy (undo)" is also ticked by default.
|
|
482
|
+
|
|
483
|
+
**What Undo covers.** Undo (Simple mode, or Restore in the Quarantine tab) only
|
|
484
|
+
brings back *files* that were cleaned as your normal user with a copy kept.
|
|
485
|
+
These are always permanent and cannot be undone:
|
|
486
|
+
|
|
487
|
+
- items that need administrator permission (the helper never quarantines);
|
|
488
|
+
- command items, such as emptying the Recycle Bin / Trash or pruning
|
|
489
|
+
containers;
|
|
490
|
+
- anything cleaned with "keep a copy" unticked.
|
|
491
|
+
|
|
492
|
+
Registry entries (Windows, Power mode only; Simple mode never cleans them) are
|
|
493
|
+
backed up in every case, but the Undo promise for them is **gated**: until the
|
|
494
|
+
checks in [docs/registry-cleanup-verification.md](docs/registry-cleanup-verification.md)
|
|
495
|
+
have been run on a real Windows machine, the GUI and the CLI say that restoring
|
|
496
|
+
registry entries is not supported yet (the backup files are kept), and Restore
|
|
497
|
+
does not touch the registry. Once the promise is switched on, per-user (`HKCU`) entries can be
|
|
498
|
+
restored from the Quarantine tab or with `cleanix restore <run>`, and
|
|
499
|
+
machine-wide (`HKLM`) entries only from an Administrator terminal (never from
|
|
500
|
+
the GUI).
|
|
501
|
+
|
|
502
|
+
**Administrator permission.** The GUI never runs as root: on Linux, macOS and
|
|
503
|
+
the BSDs it refuses to start when run as root (`sudo cleanix gui`) and asks
|
|
504
|
+
for administrator permission itself when needed. When you clean items
|
|
505
|
+
that need administrator rights, you are asked once per clean, through the
|
|
506
|
+
operating system's own prompt, and a separate helper (`python -m
|
|
507
|
+
cleanix.elevated`) removes them:
|
|
508
|
+
|
|
509
|
+
- **Windows:** the UAC prompt.
|
|
510
|
+
- **Linux:** `pkexec`, which needs polkit and a running polkit authentication
|
|
511
|
+
agent (normal in desktop sessions). Without `pkexec` such items are shown for
|
|
512
|
+
review only.
|
|
513
|
+
- **macOS:** the standard administrator password prompt.
|
|
514
|
+
|
|
515
|
+
The prompt itself does not list what will be removed; the GUI's confirmation is
|
|
516
|
+
the place to check. The helper trusts only cleaner ids and item keys from the
|
|
517
|
+
request, re-scans by itself and cleans only items it finds eligible. It runs
|
|
518
|
+
only a fixed list of system cleaners (see `admin_cleaner_ids` in
|
|
519
|
+
`cleanix/elevated.py`). In 1.4.0 that is 23 cleaners on Linux: the package
|
|
520
|
+
managers (`apt`, `dnf`, `pacman`, `zypper`, `apk`, `xbps`, `portage`,
|
|
521
|
+
`eopkg`, `swupd`), `old_kernels`, `snap`, system logs, journal, coredumps and
|
|
522
|
+
crash reports, `system_cache`, `var_backups`, `offline_updates`,
|
|
523
|
+
`config_leftovers`, `localepurge`, `crictl`, plus `temp` for other users'
|
|
524
|
+
entries. On macOS and the BSDs it is the same rule (default-enabled system
|
|
525
|
+
cleaners that need root and support the platform, plus `temp`). The opt-in
|
|
526
|
+
memory/swap actions are never included. On Windows it is 4 cleaners:
|
|
527
|
+
`win_system_temp`, `win_system_dumps`, `win_update_cache` and
|
|
528
|
+
`win_component_store` (not `temp`), plus the five registry detectors
|
|
529
|
+
(`win_reg_uninstall`, `win_reg_app_paths`, `win_reg_file_assoc`,
|
|
530
|
+
`win_reg_startup`, `win_reg_shared_dlls`), for which it deletes `HKLM` entries
|
|
531
|
+
only and never `HKCU`. The GUI offers only administrator items
|
|
532
|
+
the helper would clean; the rest are shown read-only with the reason. It uses
|
|
533
|
+
built-in default settings and ignores most of your config: only
|
|
534
|
+
`protected_globs` is honoured, since it can only add protection. It never
|
|
535
|
+
writes history or quarantine; the GUI records one history entry for its work.
|
|
536
|
+
|
|
537
|
+
Before offering administrator items the GUI checks once that the helper can
|
|
538
|
+
start (`python -I -c "import cleanix.elevated"`). A `pip install --user` or a
|
|
539
|
+
source-tree run fails that check: administrator items are then shown
|
|
540
|
+
read-only with "Administrator cleaning is not available: the helper cannot be
|
|
541
|
+
started from this installation"; install cleanix into the system or a venv.
|
|
542
|
+
|
|
543
|
+
**Headless / SSH.** The GUI needs a desktop session; over SSH or on a server
|
|
544
|
+
use the CLI. (The test suite runs the GUI headless with
|
|
545
|
+
`QT_QPA_PLATFORM=offscreen`.) Scheduled runs set up from the Schedule tab are
|
|
546
|
+
the same as `cleanix schedule`: they only scan and report, never delete.
|
|
547
|
+
|
|
548
|
+
### Security notes for the administrator helper
|
|
549
|
+
|
|
550
|
+
Known residuals, accepted for now (details in `cleanix/elevated.py`):
|
|
551
|
+
|
|
552
|
+
- **POSIX check-then-delete is path-based.** Every directory above an item is
|
|
553
|
+
re-checked right before deletion, but a service account or group that owns a
|
|
554
|
+
trusted parent could swap a path component between the check and the delete.
|
|
555
|
+
Descriptor-anchored deletion is future work.
|
|
556
|
+
- **Code-location trust.** The helper is started with `python -I`, which
|
|
557
|
+
ignores `PYTHONPATH`, the current directory and the user site directory.
|
|
558
|
+
Consequently a `pip install --user` install cannot run the helper (install
|
|
559
|
+
into a venv or system-wide). A user-writable interpreter or venv is still
|
|
560
|
+
user-writable code run as administrator; a root-owned install location is
|
|
561
|
+
planned with the installers (Plan 2B).
|
|
562
|
+
- **POSIX ACLs are not inspected**; only owner, group and mode bits are.
|
|
563
|
+
- **Windows: the result file is written by path**, as administrator, into the
|
|
564
|
+
requesting user's directory; a junction swap after validation could redirect
|
|
565
|
+
that write. Handle-based writing is future work.
|
|
566
|
+
- **Windows: `Windows\Temp` is cleaned only partly.** In elevated runs,
|
|
567
|
+
`win_system_temp` removes plain files there; directories (user-creatable,
|
|
568
|
+
swappable for junctions mid-delete) are refused. Items under `ProgramData`
|
|
569
|
+
are always refused in elevated runs.
|
|
570
|
+
- **macOS:** the administrator path has been reasoned about from the code and
|
|
571
|
+
unit-tested with mocks, but not yet run on a real Mac.
|
|
572
|
+
|
|
573
|
+
**Machine-wide registry entries (Windows).** The helper has a second, separate
|
|
574
|
+
action for registry entries under `HKLM`:
|
|
575
|
+
|
|
576
|
+
- Before the prompt, the GUI backs each entry up **as you** into a new
|
|
577
|
+
quarantine run (`.reg` + `.json`); an entry whose backup fails is not sent.
|
|
578
|
+
If you decline the prompt, that run is removed again.
|
|
579
|
+
- The request carries only the registry detector ids, the item keys you
|
|
580
|
+
ticked (each embeds the entry's content fingerprint), the backup **run id**
|
|
581
|
+
and your quarantine folder. The helper re-scans with exactly those
|
|
582
|
+
detectors and deletes only `HKLM` entries its own scan found, whose key and
|
|
583
|
+
fingerprint match, that pass the registry safety rules, and for which that
|
|
584
|
+
run holds a verified backup it could restore. Anything else is refused or
|
|
585
|
+
reported as "no longer found".
|
|
586
|
+
- The helper never reads or changes `HKCU`: running elevated, `HKCU` is the
|
|
587
|
+
administrator's hive, not yours. A request naming an `HKCU` entry is
|
|
588
|
+
refused as a whole, as is one with an unknown field, a run id containing a
|
|
589
|
+
path separator, a detector outside the five registry detectors, or a helper
|
|
590
|
+
that is not elevated.
|
|
591
|
+
- The run must be yours: the helper takes the owner of the request folder
|
|
592
|
+
(created by the unelevated GUI), looks up that account's profile in
|
|
593
|
+
`HKLM\...\ProfileList` (administrator-writable only), and accepts the
|
|
594
|
+
quarantine folder only inside that profile, without links or junctions, and
|
|
595
|
+
only when the folder, the run and its manifest are owned by that account.
|
|
596
|
+
It never uses the administrator's own `%LOCALAPPDATA%`.
|
|
597
|
+
- The quarantine folder must be on a local drive: a network (UNC, WebDAV) or
|
|
598
|
+
device path is refused from its text alone, before the helper touches the
|
|
599
|
+
filesystem. A request therefore cannot point the helper at a network share
|
|
600
|
+
directly. The run's manifest and backups are read once, during that
|
|
601
|
+
validation, each right after it is checked, and the helper deletes using
|
|
602
|
+
those in-memory copies; it never opens the run again by name.
|
|
603
|
+
- The helper writes nothing: no quarantine run, no history.
|
|
604
|
+
- Restoring these entries needs an Administrator terminal. The backup folder
|
|
605
|
+
can be changed by **any program running as you**, so inspect every `.reg`
|
|
606
|
+
file before importing it, then run `reg import "<absolute .reg path>" /reg:64`
|
|
607
|
+
for each one. `cleanix restore <run>` works only when the Administrator
|
|
608
|
+
terminal runs as the same account that made the backup (it lists exactly what
|
|
609
|
+
it will write first). With over-the-shoulder UAC (a separate administrator
|
|
610
|
+
account) it cannot find the run.
|
|
611
|
+
|
|
612
|
+
What this does **not** protect against:
|
|
613
|
+
|
|
614
|
+
- **Programs running as you.** A same-user (medium-integrity) program can edit
|
|
615
|
+
the request or the backup run between the GUI and the helper. It can only
|
|
616
|
+
choose among entries the helper's own allowlisted scan finds dead, and each
|
|
617
|
+
delete still needs a verified backup; but it can alter backup files after
|
|
618
|
+
the fact, which is why the GUI never offers an elevated restore and
|
|
619
|
+
`cleanix restore` shows exactly what it will write before writing it.
|
|
620
|
+
- **The registry delete race (R17).** There is no transactional registry API:
|
|
621
|
+
between the last check and `RegDeleteKeyEx` a key could be swapped for a
|
|
622
|
+
registry link, and the link's target could be deleted. This is reported as
|
|
623
|
+
"partially deleted … scan again", never as success.
|
|
624
|
+
- **Restore of tampered backups (T4).** Restore re-validates every path and
|
|
625
|
+
value, but a backup in your folder may have been written by any program
|
|
626
|
+
running as you; an elevated restore writes machine-wide. Review the listed
|
|
627
|
+
keys and values before confirming.
|
|
628
|
+
- **Partial deletes (T11).** A key tree that fails mid-delete is reported with
|
|
629
|
+
its backup run; restore recreates exactly the missing parts.
|
|
630
|
+
- **Link swaps during validation.** Each file of the run is checked with
|
|
631
|
+
`lstat` (links are not followed) and opened immediately afterwards; the
|
|
632
|
+
opened file must be the one just checked, or it is refused. A program
|
|
633
|
+
running as you that can create symbolic links (Developer Mode, or an
|
|
634
|
+
object-manager symlink) could still swap a folder in the instant between
|
|
635
|
+
that check and the open. The administrator's open would then follow the
|
|
636
|
+
swapped link, possibly to a network path, before the check refuses the
|
|
637
|
+
file. Opening relative to an already-verified folder handle is future work.
|
|
638
|
+
- **"Missing" evidence in folders standard users can write.** A machine-wide
|
|
639
|
+
entry is listed as dead when the program it points at is missing. Some
|
|
640
|
+
locations outside `C:\Users` are writable by standard users (folders created
|
|
641
|
+
directly under `C:\` inherit "Authenticated Users: Modify"; some vendor
|
|
642
|
+
folders under `ProgramData`). A standard user can rename a file there so that
|
|
643
|
+
a live `HKLM` entry looks dead, and it is then deleted once an administrator
|
|
644
|
+
approves the prompt. This is a denial of service only (the entry is backed up
|
|
645
|
+
first), not a privilege gain.
|
|
646
|
+
|
|
647
|
+
## Usage
|
|
648
|
+
|
|
649
|
+
```bash
|
|
650
|
+
# List available cleaners
|
|
651
|
+
cleanix list
|
|
652
|
+
|
|
653
|
+
# Analyze the system (read-only) and print a report
|
|
654
|
+
cleanix scan
|
|
655
|
+
|
|
656
|
+
# Analyze only specific cleaners
|
|
657
|
+
cleanix scan --only trash,thumbnails,apt
|
|
658
|
+
|
|
659
|
+
# Preview what a clean would remove (dry-run, the default)
|
|
660
|
+
cleanix clean
|
|
661
|
+
|
|
662
|
+
# Actually delete, asking for confirmation
|
|
663
|
+
cleanix clean --execute
|
|
664
|
+
|
|
665
|
+
# Delete without prompting (for scripts)
|
|
666
|
+
cleanix clean --execute --yes --only trash,pip_cache
|
|
667
|
+
|
|
668
|
+
# Emit the scan report as JSON (for tooling / notifications)
|
|
669
|
+
cleanix scan --json
|
|
670
|
+
|
|
671
|
+
# Install a weekly read-only scan that notifies you
|
|
672
|
+
# (systemd timer on Linux/BSD, launchd agent on macOS; on Windows a Task
|
|
673
|
+
# Scheduler task whose output is the report file, no notification)
|
|
674
|
+
cleanix schedule install --frequency weekly
|
|
675
|
+
|
|
676
|
+
# Check / remove the schedule
|
|
677
|
+
cleanix schedule status
|
|
678
|
+
cleanix schedule uninstall
|
|
679
|
+
|
|
680
|
+
# View and change settings (no YAML editing needed)
|
|
681
|
+
cleanix config list
|
|
682
|
+
cleanix config set remove_old_kernels false
|
|
683
|
+
cleanix config set keep_kernels 3
|
|
684
|
+
cleanix config unset keep_kernels # revert to default
|
|
685
|
+
|
|
686
|
+
# See a factory-reset plan for this OS (advisory — runs nothing)
|
|
687
|
+
cleanix factory-reset
|
|
688
|
+
cleanix factory-reset --scope user
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
### Windows registry cleaners (opt-in)
|
|
692
|
+
|
|
693
|
+
Five detectors look for dead registry entries: `win_reg_uninstall`,
|
|
694
|
+
`win_reg_app_paths`, `win_reg_file_assoc`, `win_reg_startup` and
|
|
695
|
+
`win_reg_shared_dlls`. They are Windows only and **never** part of a plain
|
|
696
|
+
`cleanix scan` / `cleanix clean`, a `--profile`, or the scheduled scan; name
|
|
697
|
+
them explicitly (`cleanix list` shows them as `opt-in`) with `--only` or the
|
|
698
|
+
`--registry` flag. `--registry` (Windows only; elsewhere it exits 2 with
|
|
699
|
+
"Registry cleanup is only available on Windows.") selects exactly the five
|
|
700
|
+
registry cleaners, or adds them to an explicit `--only`; it counts as the
|
|
701
|
+
explicit selection `clean` requires and is never implied by a profile, the
|
|
702
|
+
configuration or the scheduled scan:
|
|
703
|
+
|
|
704
|
+
```bash
|
|
705
|
+
cleanix scan --registry # same five ids
|
|
706
|
+
cleanix clean --registry --execute # lists every key/value, asks first
|
|
707
|
+
cleanix scan --only win_reg_uninstall,win_reg_startup # read-only
|
|
708
|
+
cleanix scan --only win_reg_uninstall --json # targets in JSON
|
|
709
|
+
cleanix clean --only win_reg_uninstall --execute # lists every key/value, asks first
|
|
710
|
+
cleanix clean --only win_reg_uninstall --execute --yes # no prompt
|
|
711
|
+
cleanix restore <run-id> # undo, once shipped
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
Scan output and JSON show each target as `HKCU\path\to\key [value]` (control
|
|
715
|
+
characters are shown escaped); JSON items add `kind`, `target` and
|
|
716
|
+
`registry` (`{"hive","key","value"}` or `null`), and each cleaner adds a
|
|
717
|
+
boolean `registry` (true for the five registry ids). `history.jsonl` entries
|
|
718
|
+
of runs that removed registry entries carry a `registry` count (no values).
|
|
719
|
+
Machine-wide (`HKLM`) entries are only removed from an elevated
|
|
720
|
+
(Administrator) terminal; without one they are skipped with a message.
|
|
721
|
+
Restoring a run that contains `HKLM` entries also needs an Administrator
|
|
722
|
+
terminal: `cleanix restore` prints exactly what will be written and asks you
|
|
723
|
+
to type `yes` (`--yes` is accepted only together with an explicit run id).
|
|
724
|
+
|
|
725
|
+
What the CLI promises about backups follows what this version ships (see
|
|
726
|
+
"Undo status" below). While registry undo is not shipped, the CLI says registry
|
|
727
|
+
entries have a backup written but that restoring them is not supported yet. Once
|
|
728
|
+
shipped, `HKCU` entries are backed up before removal and can be restored with
|
|
729
|
+
`cleanix restore <run>`; `HKLM` entries are backed up too, but restoring them
|
|
730
|
+
needs an Administrator terminal.
|
|
731
|
+
|
|
732
|
+
#### What the registry cleaners do, and do not do
|
|
733
|
+
|
|
734
|
+
They list an entry only when every piece of evidence the detector needs is
|
|
735
|
+
**provably missing**. "Unknown is not dead": an unreadable key, a network or
|
|
736
|
+
removable drive, a variable that cannot be expanded, a host program such as
|
|
737
|
+
`msiexec` or `rundll32`, anything under the Windows directory, Microsoft- or
|
|
738
|
+
Store-owned locations, an MSI- or Burn-managed uninstall entry, or an entry
|
|
739
|
+
whose structure the detector does not recognise is never listed. For
|
|
740
|
+
machine-wide entries, targets under `C:\Users` are also unknown (they belong to
|
|
741
|
+
another user's per-user install).
|
|
742
|
+
|
|
743
|
+
- `win_reg_uninstall`: `Uninstall` keys (including the 32-bit `WOW6432Node`
|
|
744
|
+
view) whose install folder **and** uninstaller are gone.
|
|
745
|
+
- `win_reg_app_paths`: `App Paths\<name>.exe` entries whose program is gone.
|
|
746
|
+
- `win_reg_file_assoc`: "open with" handlers (a class with a
|
|
747
|
+
`shell\...\command` and an optional `DefaultIcon`) whose programs and icons
|
|
748
|
+
are all gone.
|
|
749
|
+
- `win_reg_startup`: `Run` and `RunOnce` values for programs that no longer
|
|
750
|
+
exist. Nothing is "disabled": live startup entries are never touched.
|
|
751
|
+
- `win_reg_shared_dlls`: `SharedDLLs` counters for files that no longer exist.
|
|
752
|
+
|
|
753
|
+
They never claim to speed up Windows or free space (registry items have size 0
|
|
754
|
+
and are never counted in "freed"), never delete a live entry, never open
|
|
755
|
+
the merged `HKEY_CLASSES_ROOT` view (file-type handlers are read and removed
|
|
756
|
+
under the two real `Software\Classes` keys), `HKEY_USERS`,
|
|
757
|
+
`HKEY_CURRENT_CONFIG`, Windows Installer, policy or Explorer keys, and open only
|
|
758
|
+
the 64-bit registry view (`KEY_WOW64_64KEY`; the 32-bit view is reached only
|
|
759
|
+
through explicit `WOW6432Node` paths, also from a 32-bit Python). The findings are always
|
|
760
|
+
labelled **Review** in the GUI. `--all-users` does not load other users'
|
|
761
|
+
hives: `HKCU` is the registry of the account running Cleanix (in an elevated
|
|
762
|
+
terminal that is the administrator's, which is why elevated scans do not judge
|
|
763
|
+
`HKCU` handlers).
|
|
764
|
+
|
|
765
|
+
**Backups.** A registry entry is deleted only after a backup of exactly what
|
|
766
|
+
was scanned has been written and read back (a failed backup means nothing is
|
|
767
|
+
deleted), and only if the entry is still what the scan saw (its fingerprint is
|
|
768
|
+
part of the item key); otherwise it is reported as "changed since the scan;
|
|
769
|
+
scan again". Each removed entry gets two files in a quarantine run,
|
|
770
|
+
`N__registry.reg` (UTF-16 with BOM, `Windows Registry Editor Version 5.00`;
|
|
771
|
+
readable in Notepad, usable with `reg import`) and `N__registry.json` (typed
|
|
772
|
+
values, the source Cleanix's own restore uses). Restore re-creates missing keys
|
|
773
|
+
and values additively, refuses any entry whose values differ, validates every
|
|
774
|
+
path again and checks that the result equals the backup. Security descriptors
|
|
775
|
+
are not backed up: a restored key inherits its parent's permissions.
|
|
776
|
+
|
|
777
|
+
**Undo status (gated).** The backup code is shipped and unit-tested against an
|
|
778
|
+
in-memory registry, but several Windows behaviours it relies on can only be
|
|
779
|
+
confirmed on a real machine (registry link handling, `REG_MULTI_SZ` with empty
|
|
780
|
+
strings, `reg export`/`reg import` agreement). The 64-bit-view behaviour for
|
|
781
|
+
`HKLM\SOFTWARE` cannot be exercised safely and is covered only by unit tests
|
|
782
|
+
that pin the `KEY_WOW64_64KEY` flag. Until the manual
|
|
783
|
+
verification in
|
|
784
|
+
[docs/registry-cleanup-verification.md](docs/registry-cleanup-verification.md)
|
|
785
|
+
has passed, the switch `UNDO_SHIPPED` in `cleanix/core/regpromises.py` stays
|
|
786
|
+
`False`. Every user-visible message then says: "A backup of each removed
|
|
787
|
+
registry entry is written to the quarantine folder, but restoring registry
|
|
788
|
+
entries is not supported in this version yet; to restore one manually, inspect
|
|
789
|
+
the .reg file and import it with reg import ... /reg:64." `cleanix restore` and
|
|
790
|
+
the GUI Quarantine tab restore file entries as usual but do **not** run the
|
|
791
|
+
registry restore: they report "not restored: registry restore is not enabled in
|
|
792
|
+
this version (backup files are in ...)" and keep the run.
|
|
793
|
+
|
|
794
|
+
**Restoring.** `HKCU` entries: `cleanix restore <run>`, or Restore in the GUI's
|
|
795
|
+
Quarantine tab. `HKLM` entries only from an **Administrator terminal**, never
|
|
796
|
+
from the GUI. Inspect every `.reg` file first (the backup folder can be changed
|
|
797
|
+
by any program running as you), then run
|
|
798
|
+
`reg import "<absolute .reg path>" /reg:64` for each one. `cleanix restore
|
|
799
|
+
<run>` from the Administrator terminal also works when it runs as the same
|
|
800
|
+
account that made the backup: it lists exactly which keys and values it will
|
|
801
|
+
write and waits for `yes`. With over-the-shoulder UAC (a separate administrator
|
|
802
|
+
account) only `reg import` with the absolute path works, because the run lives
|
|
803
|
+
in the standard user's profile.
|
|
804
|
+
|
|
805
|
+
**Limits and residual risks** (details in
|
|
806
|
+
[Security notes for the administrator helper](#security-notes-for-the-administrator-helper)):
|
|
807
|
+
|
|
808
|
+
- **No transaction (R17).** Between the last check and the delete a key could be
|
|
809
|
+
swapped for a registry link and the link's target deleted. Cleanix reports a
|
|
810
|
+
partly deleted entry as such ("scan again"), never as success. What a delete
|
|
811
|
+
does to a link as the final path component is one of the points the Windows
|
|
812
|
+
verification measures.
|
|
813
|
+
- **Programs running as you** can edit a backup between the clean and a restore.
|
|
814
|
+
Restore re-validates and an elevated restore lists what it will write, but
|
|
815
|
+
that is why the GUI never offers an elevated restore.
|
|
816
|
+
- **A standard user can make a live `HKLM` entry look dead** by renaming a file
|
|
817
|
+
in a folder they can write; it is then removed only after an administrator
|
|
818
|
+
approves the prompt, and it is backed up first.
|
|
819
|
+
- **Partial deletes**: a key tree that fails halfway is reported with its
|
|
820
|
+
backup run; restore recreates exactly the missing parts.
|
|
821
|
+
- An entry that cannot be backed up exactly (a `Policies` subkey, names with
|
|
822
|
+
line breaks, a registry link, more than 256 keys, 4096 values or 1 MiB of data) is not
|
|
823
|
+
offered at all.
|
|
824
|
+
|
|
825
|
+
The elevated helper path (`HKLM`) is covered by unit tests only; it has not
|
|
826
|
+
been run against a real machine-wide registry and must not be tried on one.
|
|
827
|
+
|
|
828
|
+
## Configuration via CLI
|
|
829
|
+
|
|
830
|
+
`cleanix config` reads/writes `~/.config/cleanix/config.yaml` (`%APPDATA%\cleanix\config.yaml` on Windows) with type-checked
|
|
831
|
+
values, so you never have to hand-edit YAML:
|
|
832
|
+
|
|
833
|
+
```bash
|
|
834
|
+
cleanix config list # every setting, value, source, description
|
|
835
|
+
cleanix config get <key>
|
|
836
|
+
cleanix config set <key> <value> # bool/int/float/list are validated
|
|
837
|
+
cleanix config unset <key> # revert to the built-in default
|
|
838
|
+
cleanix config path
|
|
839
|
+
```
|
|
840
|
+
|
|
841
|
+
## Factory-reset advisor
|
|
842
|
+
|
|
843
|
+
`cleanix factory-reset` detects how your OS can be reset and prints a **tiered,
|
|
844
|
+
copy-pasteable plan** — it never executes anything destructive:
|
|
845
|
+
|
|
846
|
+
- **NixOS / Guix** → declarative rollback to a prior generation (✅ reversible)
|
|
847
|
+
- **rpm-ostree** (Silverblue/Kinoite) → `rpm-ostree reset` to the base image (✅)
|
|
848
|
+
- **openSUSE MicroOS** → `snapper rollback` (✅)
|
|
849
|
+
- **macOS** → the built-in "Erase All Content and Settings" (recommended)
|
|
850
|
+
- **Traditional distros** (Fedora/Ubuntu/Arch) → honestly reports there is *no*
|
|
851
|
+
true factory reset; suggests snapshot-restore/reinstall and gives best-effort
|
|
852
|
+
package/config/user reset steps.
|
|
853
|
+
|
|
854
|
+
`--scope user|packages|system|full` controls how much the plan covers.
|
|
855
|
+
|
|
856
|
+
### Executing a reversible reset
|
|
857
|
+
|
|
858
|
+
On reversible systems only, cleanix can run the rollback for you:
|
|
859
|
+
|
|
860
|
+
```bash
|
|
861
|
+
sudo cleanix factory-reset --execute
|
|
862
|
+
```
|
|
863
|
+
|
|
864
|
+
This is heavily gated:
|
|
865
|
+
|
|
866
|
+
- **Only reversible strategies** run — NixOS (`nixos-rebuild switch --rollback`),
|
|
867
|
+
rpm-ostree (`rpm-ostree reset`), MicroOS (`snapper rollback`), Guix
|
|
868
|
+
(`guix system roll-back`). Traditional distros and macOS **refuse to execute**.
|
|
869
|
+
- **Only the reversible rollback command** runs — never the irreversible
|
|
870
|
+
dotfile/`rm -rf` steps (those stay advisory).
|
|
871
|
+
- Requires **root**, an **interactive terminal**, and a **typed confirmation
|
|
872
|
+
phrase** (`reset <hostname>`). Each action prints its **undo** command.
|
|
873
|
+
- Stops on the first failure.
|
|
874
|
+
|
|
875
|
+
Without `--execute`, `factory-reset` only prints the plan.
|
|
876
|
+
|
|
877
|
+
## System-wide mode (root)
|
|
878
|
+
|
|
879
|
+
Run unprivileged, cleanix scans **your** home. Run as **root/sudo**, it
|
|
880
|
+
automatically sweeps **every real user's home** plus system-wide locations:
|
|
881
|
+
|
|
882
|
+
```bash
|
|
883
|
+
sudo cleanix scan # all users + system (auto when root)
|
|
884
|
+
sudo cleanix scan --current-user # restrict to the invoking user
|
|
885
|
+
cleanix scan --all-users # force multi-user even unprivileged
|
|
886
|
+
sudo cleanix scan --min-uid 500 # change the "real user" uid threshold
|
|
887
|
+
```
|
|
888
|
+
|
|
889
|
+
How it works:
|
|
890
|
+
|
|
891
|
+
- Cleaners declare a **scope**: *user* (trash, caches, browsers, AI tools, …)
|
|
892
|
+
or *system* (package managers, `/var/log`, journal, coredumps, …).
|
|
893
|
+
- User-scoped cleaners run **once per target user**, resolving `~`, `~/.cache`,
|
|
894
|
+
`~/.config`, uid, etc. against *that* user — never leaking root's environment.
|
|
895
|
+
- Target users come from `/etc/passwd`: root plus accounts with uid ≥ `min_uid`
|
|
896
|
+
(1000 on Linux/BSD, 500 on macOS) that have a real home directory.
|
|
897
|
+
- Shared/system paths yielded for multiple users are **de-duplicated**, so
|
|
898
|
+
nothing is offered — or deleted — twice.
|
|
899
|
+
- The protected-path guard is extended to cover **every** scanned user's home
|
|
900
|
+
(and their `~/.config`, `~/.local`, `~/Library`, …), so a bug can never wipe
|
|
901
|
+
another user's home.
|
|
902
|
+
|
|
903
|
+
## Report-only tier (backups & snapshots)
|
|
904
|
+
|
|
905
|
+
Some things are *leftovers* but also *recovery data* — filesystem snapshots,
|
|
906
|
+
mobile-device backups, suspended-VM memory images. Cleanix surfaces these with
|
|
907
|
+
their size and the **correct removal command**, but they are **never** eligible
|
|
908
|
+
for deletion (`clean` skips them; even a forced attempt is refused):
|
|
909
|
+
|
|
910
|
+
```
|
|
911
|
+
Report-only — review and remove manually (never auto-deleted)
|
|
912
|
+
7.5 GiB Timeshift snapshot: 2026-01-01 timeshift --delete --snapshot '2026-01-01'
|
|
913
|
+
```
|
|
914
|
+
|
|
915
|
+
Covered report-only: Timeshift/Snapper snapshots, libvirt saved VM states,
|
|
916
|
+
macOS Time Machine local snapshots, iOS device backups, macOS sleep image,
|
|
917
|
+
and the system-wide orphan reports (see above).
|
|
918
|
+
|
|
919
|
+
## Extended coverage
|
|
920
|
+
|
|
921
|
+
Beyond the core cleaners, cleanix also handles:
|
|
922
|
+
|
|
923
|
+
- **Old kernels** — package-manager-driven; always keeps the running kernel and
|
|
924
|
+
the newest `keep_kernels` (default 2). Set `remove_old_kernels: false` to skip.
|
|
925
|
+
- **System caches & spools** — `/var/cache` (PackageKit/man/fontconfig/cups),
|
|
926
|
+
Debian `/var/backups`, ABRT/apport crash spool, staged offline-update payloads.
|
|
927
|
+
- **Language package caches** — Go modcache, rustup/deno/bun/nvm/pnpm, Android
|
|
928
|
+
SDK. Offline repos (Maven/Ivy/sbt/Coursier/NuGet/RubyGems) gated behind
|
|
929
|
+
`include_offline_repos`.
|
|
930
|
+
- **Desktop search indexes** — Baloo, Tracker, Zeitgeist, GVFS metadata.
|
|
931
|
+
- **VM/cloud tooling** — VirtualBox logs, Vagrant boxes, kube/minikube/helm,
|
|
932
|
+
AWS/Azure/gcloud/Terraform/Pulumi caches.
|
|
933
|
+
- **Editor & build litter** — Vim/Neovim swap/undo, `__pycache__`,
|
|
934
|
+
`.pytest_cache`/`.mypy_cache`/`.ruff_cache`/`.tox`, loose core dumps.
|
|
935
|
+
- **macOS extras** — Saved Application State, CocoaPods/Carthage, QuickLook.
|
|
936
|
+
- **Opt-in** (off by default): editor backup files (`*~`/`*.bak`/`*.orig`) via
|
|
937
|
+
`remove_backup_files`, and localepurge-style unused locales/man-pages via
|
|
938
|
+
`purge_unused_locales`.
|
|
939
|
+
|
|
940
|
+
## Safety model
|
|
941
|
+
|
|
942
|
+
1. **Two-phase**: `scan` is always read-only. `clean` defaults to dry-run.
|
|
943
|
+
2. **Protected paths**: deletion of (or inside) critical paths is refused at the
|
|
944
|
+
lowest level — see `cleanix/core/safety.py`.
|
|
945
|
+
3. **Age thresholds**: temp/log cleaners only consider files older than a
|
|
946
|
+
configurable age, so in-use files are left alone.
|
|
947
|
+
4. **Scheduled = analyze only**: the timer runs `scan` and writes a report; it
|
|
948
|
+
does not clean.
|
|
949
|
+
|
|
950
|
+
## Configuration
|
|
951
|
+
|
|
952
|
+
Defaults live in `cleanix/config.py`. Override them with a YAML file at
|
|
953
|
+
`~/.config/cleanix/config.yaml` (see `config/default.yaml` for the shape).
|
|
954
|
+
|
|
955
|
+
## Project layout
|
|
956
|
+
|
|
957
|
+
```
|
|
958
|
+
cleanix/
|
|
959
|
+
cli.py # argparse entry point (scan / clean / list / schedule)
|
|
960
|
+
config.py # defaults + YAML overrides
|
|
961
|
+
core/
|
|
962
|
+
models.py # CleanableItem, CleanerReport, dataclasses
|
|
963
|
+
platform.py # OS + distro detection, platform tokens
|
|
964
|
+
context.py # multi-user scanning (target users, current-user binding)
|
|
965
|
+
safety.py # protected-path guard + safe delete
|
|
966
|
+
engine.py # runs cleaners, aggregates reports, executes cleans
|
|
967
|
+
registry.py # discovers, platform-filters & instantiates cleaners
|
|
968
|
+
utils.py # sizes (allocated blocks), walking, age/in-use guards
|
|
969
|
+
report.py # rich tables + JSON rendering
|
|
970
|
+
cleaners/
|
|
971
|
+
base.py # Cleaner ABC (declares .platforms)
|
|
972
|
+
# cross-platform
|
|
973
|
+
trash, thumbnails, user_cache, temp_files, font_cache, browsers,
|
|
974
|
+
broken_symlinks, apple_litter, dev_caches, pip_cache, npm_cache, containers
|
|
975
|
+
# logs & crashes
|
|
976
|
+
logs, coredumps, linux_extras (config residue + /var/crash)
|
|
977
|
+
# linux package managers
|
|
978
|
+
apt, dnf/yum, pacman, distro_pkg (zypper/apk/xbps/portage),
|
|
979
|
+
more_pkg (conda/mamba, guix, eopkg, swupd, opam, sdkman, gem, cpanm),
|
|
980
|
+
packaging_extras (flatpak/snap/nix/appimage)
|
|
981
|
+
# AI / LLM engines & clients
|
|
982
|
+
ai_tools (ollama, huggingface, compile caches, ai clients, aider)
|
|
983
|
+
ai_cli (claude code, codex, gemini cli, opencode — retention-aware)
|
|
984
|
+
# desktop-app bloat
|
|
985
|
+
app_cruft (electron caches, flatpak caches, gpu shaders, steam, jetbrains)
|
|
986
|
+
# extended system leftovers
|
|
987
|
+
sys_extras (/var/cache, /var/backups, crash spool, offline updates)
|
|
988
|
+
kernels (old-kernel purge), localizations (localepurge, opt-in)
|
|
989
|
+
# extended user leftovers
|
|
990
|
+
lang_caches (go/rust/js/.net/jvm), desktop_extras (search indexes)
|
|
991
|
+
virtualization (vbox/vagrant/k8s/cloud), editor_litter (swap/pycache/cores)
|
|
992
|
+
# backups & snapshots (report-only tier)
|
|
993
|
+
snapshots (timeshift/snapper/timemachine/device backups)
|
|
994
|
+
# macOS
|
|
995
|
+
macos (caches, trash, diagnostics, homebrew, macports, xcode)
|
|
996
|
+
macos_extra (saved state, cocoapods, sleep image)
|
|
997
|
+
# BSD
|
|
998
|
+
bsd (freebsd pkg, distfiles/work dirs, pkgin)
|
|
999
|
+
scheduler/
|
|
1000
|
+
__init__.py # backend() — picks systemd or launchd for the OS
|
|
1001
|
+
systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
|
|
1002
|
+
launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
|
|
1003
|
+
schtasks.py # per-user Task Scheduler scan task (Windows)
|
|
1004
|
+
```
|
|
1005
|
+
|
|
1006
|
+
To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
|
|
1007
|
+
implement `find_items()` (read-only, yields `CleanableItem`s), and register it in
|
|
1008
|
+
`cleaners/__init__.py`. The engine handles dry-run, confirmation, root checks,
|
|
1009
|
+
and the safety guard for you.
|
|
1010
|
+
|
|
1011
|
+
## License
|
|
1012
|
+
|
|
1013
|
+
MIT
|