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.
Files changed (193) hide show
  1. cleanix_cli-1.4.0b1/PKG-INFO +1013 -0
  2. cleanix_cli-1.4.0b1/README.md +971 -0
  3. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/RELEASING.md +12 -1
  4. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/__init__.py +2 -2
  5. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/__init__.py +69 -0
  6. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ai_cli.py +5 -1
  7. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ai_tools.py +9 -1
  8. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/app_cruft.py +32 -3
  9. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/base.py +12 -1
  10. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/big_files.py +2 -2
  11. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/browser_profiles.py +18 -4
  12. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/browsers.py +1 -0
  13. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/containers.py +2 -0
  14. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/dev_caches.py +14 -0
  15. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/downloads.py +2 -2
  16. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/duplicates.py +2 -2
  17. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/lang_caches.py +1 -0
  18. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/linux_extras.py +8 -3
  19. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/logs.py +12 -2
  20. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/npm_cache.py +9 -0
  21. cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_app_data.py +470 -0
  22. cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_common.py +567 -0
  23. cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_files.py +382 -0
  24. cleanix_cli-1.4.0b1/cleanix/cleaners/orphan_launch_jobs.py +191 -0
  25. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/pip_cache.py +9 -2
  26. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/project_cruft.py +8 -2
  27. cleanix_cli-1.4.0b1/cleanix/cleaners/stale_launchers.py +352 -0
  28. cleanix_cli-1.4.0b1/cleanix/cleaners/stale_receipts.py +261 -0
  29. cleanix_cli-1.4.0b1/cleanix/cleaners/stale_services.py +349 -0
  30. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/sys_extras.py +7 -3
  31. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/temp_files.py +12 -5
  32. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/thumbnails.py +1 -0
  33. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/user_cache.py +1 -0
  34. cleanix_cli-1.4.0b1/cleanix/cleaners/windows_apps.py +143 -0
  35. cleanix_cli-1.4.0b1/cleanix/cleaners/windows_core.py +105 -0
  36. cleanix_cli-1.4.0b1/cleanix/cleaners/windows_system.py +157 -0
  37. cleanix_cli-1.4.0b1/cleanix/cleaners/windows_wsl.py +58 -0
  38. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_app_paths.py +84 -0
  39. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_base.py +114 -0
  40. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_file_assoc.py +162 -0
  41. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_shared_dlls.py +106 -0
  42. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_startup.py +81 -0
  43. cleanix_cli-1.4.0b1/cleanix/cleaners/winreg_uninstall.py +185 -0
  44. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cli.py +355 -49
  45. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/completion.py +8 -2
  46. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/config.py +24 -4
  47. cleanix_cli-1.4.0b1/cleanix/core/catalog.py +184 -0
  48. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/context.py +6 -1
  49. cleanix_cli-1.4.0b1/cleanix/core/curation.py +303 -0
  50. cleanix_cli-1.4.0b1/cleanix/core/elevate.py +559 -0
  51. cleanix_cli-1.4.0b1/cleanix/core/elevate_launch.py +158 -0
  52. cleanix_cli-1.4.0b1/cleanix/core/engine.py +333 -0
  53. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/history.py +16 -5
  54. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/models.py +79 -0
  55. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/platform.py +10 -1
  56. cleanix_cli-1.4.0b1/cleanix/core/quarantine.py +696 -0
  57. cleanix_cli-1.4.0b1/cleanix/core/regbackup.py +1012 -0
  58. cleanix_cli-1.4.0b1/cleanix/core/regclean.py +469 -0
  59. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/registry.py +5 -0
  60. cleanix_cli-1.4.0b1/cleanix/core/regpromises.py +54 -0
  61. cleanix_cli-1.4.0b1/cleanix/core/regsafety.py +296 -0
  62. cleanix_cli-1.4.0b1/cleanix/core/regsnap.py +190 -0
  63. cleanix_cli-1.4.0b1/cleanix/core/regtargets.py +543 -0
  64. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/report.py +72 -7
  65. cleanix_cli-1.4.0b1/cleanix/core/safety.py +486 -0
  66. cleanix_cli-1.4.0b1/cleanix/core/safety_windows.py +217 -0
  67. cleanix_cli-1.4.0b1/cleanix/core/scanmode.py +62 -0
  68. cleanix_cli-1.4.0b1/cleanix/core/service.py +205 -0
  69. cleanix_cli-1.4.0b1/cleanix/core/utils.py +452 -0
  70. cleanix_cli-1.4.0b1/cleanix/core/winenv.py +198 -0
  71. cleanix_cli-1.4.0b1/cleanix/core/winregistry.py +129 -0
  72. cleanix_cli-1.4.0b1/cleanix/core/winregistry_win.py +317 -0
  73. cleanix_cli-1.4.0b1/cleanix/elevated.py +1436 -0
  74. cleanix_cli-1.4.0b1/cleanix/gui/__init__.py +1 -0
  75. cleanix_cli-1.4.0b1/cleanix/gui/app.py +65 -0
  76. cleanix_cli-1.4.0b1/cleanix/gui/elevation.py +722 -0
  77. cleanix_cli-1.4.0b1/cleanix/gui/grouped_results.py +482 -0
  78. cleanix_cli-1.4.0b1/cleanix/gui/main_window.py +303 -0
  79. cleanix_cli-1.4.0b1/cleanix/gui/models.py +272 -0
  80. cleanix_cli-1.4.0b1/cleanix/gui/panels_config.py +434 -0
  81. cleanix_cli-1.4.0b1/cleanix/gui/panels_data.py +287 -0
  82. cleanix_cli-1.4.0b1/cleanix/gui/power_view.py +785 -0
  83. cleanix_cli-1.4.0b1/cleanix/gui/reveal.py +64 -0
  84. cleanix_cli-1.4.0b1/cleanix/gui/simple_view.py +760 -0
  85. cleanix_cli-1.4.0b1/cleanix/gui/theme.py +19 -0
  86. cleanix_cli-1.4.0b1/cleanix/gui/workers.py +302 -0
  87. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/__init__.py +5 -1
  88. cleanix_cli-1.4.0b1/cleanix/scheduler/schtasks.py +150 -0
  89. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix.1 +19 -3
  90. cleanix_cli-1.4.0b1/cleanix_cli.egg-info/PKG-INFO +1013 -0
  91. cleanix_cli-1.4.0b1/cleanix_cli.egg-info/SOURCES.txt +182 -0
  92. cleanix_cli-1.4.0b1/cleanix_cli.egg-info/entry_points.txt +5 -0
  93. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/requires.txt +7 -0
  94. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/pyproject.toml +10 -3
  95. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/scripts/gen_manpage.py +11 -3
  96. cleanix_cli-1.4.0b1/tests/test_admin_eligibility.py +135 -0
  97. cleanix_cli-1.4.0b1/tests/test_catalog.py +160 -0
  98. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/tests/test_cleanix.py +29 -5
  99. cleanix_cli-1.4.0b1/tests/test_curation.py +247 -0
  100. cleanix_cli-1.4.0b1/tests/test_elevate.py +1630 -0
  101. cleanix_cli-1.4.0b1/tests/test_elevate_launch.py +277 -0
  102. cleanix_cli-1.4.0b1/tests/test_elevated_registry.py +1867 -0
  103. cleanix_cli-1.4.0b1/tests/test_gui_isolation.py +109 -0
  104. cleanix_cli-1.4.0b1/tests/test_orphan_app_data.py +504 -0
  105. cleanix_cli-1.4.0b1/tests/test_orphan_budget.py +128 -0
  106. cleanix_cli-1.4.0b1/tests/test_orphan_common.py +518 -0
  107. cleanix_cli-1.4.0b1/tests/test_orphan_files.py +600 -0
  108. cleanix_cli-1.4.0b1/tests/test_orphan_launch_jobs.py +267 -0
  109. cleanix_cli-1.4.0b1/tests/test_orphans_wiring.py +88 -0
  110. cleanix_cli-1.4.0b1/tests/test_owner_matches.py +426 -0
  111. cleanix_cli-1.4.0b1/tests/test_regbackup.py +1027 -0
  112. cleanix_cli-1.4.0b1/tests/test_regclean.py +1596 -0
  113. cleanix_cli-1.4.0b1/tests/test_registry_cli.py +805 -0
  114. cleanix_cli-1.4.0b1/tests/test_registry_foundation.py +681 -0
  115. cleanix_cli-1.4.0b1/tests/test_regtargets.py +378 -0
  116. cleanix_cli-1.4.0b1/tests/test_service.py +212 -0
  117. cleanix_cli-1.4.0b1/tests/test_stale_launchers.py +390 -0
  118. cleanix_cli-1.4.0b1/tests/test_stale_receipts.py +394 -0
  119. cleanix_cli-1.4.0b1/tests/test_stale_services.py +315 -0
  120. cleanix_cli-1.4.0b1/tests/test_verify_registry_script.py +307 -0
  121. cleanix_cli-1.4.0b1/tests/test_windows_cleaners_apps.py +142 -0
  122. cleanix_cli-1.4.0b1/tests/test_windows_cleaners_core.py +123 -0
  123. cleanix_cli-1.4.0b1/tests/test_windows_cleaners_system.py +160 -0
  124. cleanix_cli-1.4.0b1/tests/test_windows_cli.py +77 -0
  125. cleanix_cli-1.4.0b1/tests/test_windows_command_timeout.py +65 -0
  126. cleanix_cli-1.4.0b1/tests/test_windows_crossplatform.py +377 -0
  127. cleanix_cli-1.4.0b1/tests/test_windows_encoding.py +62 -0
  128. cleanix_cli-1.4.0b1/tests/test_windows_env.py +55 -0
  129. cleanix_cli-1.4.0b1/tests/test_windows_exec_resolution.py +204 -0
  130. cleanix_cli-1.4.0b1/tests/test_windows_minors.py +234 -0
  131. cleanix_cli-1.4.0b1/tests/test_windows_platform.py +31 -0
  132. cleanix_cli-1.4.0b1/tests/test_windows_profiles_cache.py +76 -0
  133. cleanix_cli-1.4.0b1/tests/test_windows_quarantine.py +217 -0
  134. cleanix_cli-1.4.0b1/tests/test_windows_rmtree_toctou.py +86 -0
  135. cleanix_cli-1.4.0b1/tests/test_windows_safety_integration.py +286 -0
  136. cleanix_cli-1.4.0b1/tests/test_windows_safety_model.py +149 -0
  137. cleanix_cli-1.4.0b1/tests/test_windows_safety_profiles.py +154 -0
  138. cleanix_cli-1.4.0b1/tests/test_windows_scheduler.py +145 -0
  139. cleanix_cli-1.4.0b1/tests/test_winreg_app_paths.py +282 -0
  140. cleanix_cli-1.4.0b1/tests/test_winreg_backend.py +944 -0
  141. cleanix_cli-1.4.0b1/tests/test_winreg_file_assoc.py +461 -0
  142. cleanix_cli-1.4.0b1/tests/test_winreg_shared_dlls.py +280 -0
  143. cleanix_cli-1.4.0b1/tests/test_winreg_startup.py +253 -0
  144. cleanix_cli-1.4.0b1/tests/test_winreg_uninstall.py +390 -0
  145. cleanix_cli-1.2.0/PKG-INFO +0 -521
  146. cleanix_cli-1.2.0/README.md +0 -486
  147. cleanix_cli-1.2.0/cleanix/core/engine.py +0 -155
  148. cleanix_cli-1.2.0/cleanix/core/quarantine.py +0 -147
  149. cleanix_cli-1.2.0/cleanix/core/safety.py +0 -211
  150. cleanix_cli-1.2.0/cleanix/core/utils.py +0 -244
  151. cleanix_cli-1.2.0/cleanix_cli.egg-info/PKG-INFO +0 -521
  152. cleanix_cli-1.2.0/cleanix_cli.egg-info/SOURCES.txt +0 -86
  153. cleanix_cli-1.2.0/cleanix_cli.egg-info/entry_points.txt +0 -2
  154. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/MANIFEST.in +0 -0
  155. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/__main__.py +0 -0
  156. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apple_litter.py +0 -0
  157. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apps.py +0 -0
  158. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/apt.py +0 -0
  159. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/broken_symlinks.py +0 -0
  160. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/bsd.py +0 -0
  161. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/containerd.py +0 -0
  162. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/coredumps.py +0 -0
  163. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/desktop_extras.py +0 -0
  164. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/distro_pkg.py +0 -0
  165. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/dnf.py +0 -0
  166. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/editor_litter.py +0 -0
  167. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/font_cache.py +0 -0
  168. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/ide.py +0 -0
  169. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/kernels.py +0 -0
  170. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/localizations.py +0 -0
  171. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/macos.py +0 -0
  172. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/macos_extra.py +0 -0
  173. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/memory.py +0 -0
  174. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/more_pkg.py +0 -0
  175. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/packaging_extras.py +0 -0
  176. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/pacman.py +0 -0
  177. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/snapshots.py +0 -0
  178. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/toolchains.py +0 -0
  179. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/trash.py +0 -0
  180. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/cleaners/virtualization.py +0 -0
  181. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/core/__init__.py +0 -0
  182. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/reset.py +0 -0
  183. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/cron.py +0 -0
  184. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/launchd.py +0 -0
  185. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix/scheduler/systemd.py +0 -0
  186. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/dependency_links.txt +0 -0
  187. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/cleanix_cli.egg-info/top_level.txt +0 -0
  188. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/README.md +0 -0
  189. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/aur/PKGBUILD +0 -0
  190. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/homebrew/cleanix.rb +0 -0
  191. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/packaging/rpm/cleanix-cli.spec +0 -0
  192. {cleanix_cli-1.2.0 → cleanix_cli-1.4.0b1}/requirements.txt +0 -0
  193. {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
+ [![CI](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml)
46
+ [![PyPI version](https://img.shields.io/pypi/v/cleanix-cli.svg)](https://pypi.org/project/cleanix-cli/)
47
+ [![Python versions](https://img.shields.io/pypi/pyversions/cleanix-cli.svg)](https://pypi.org/project/cleanix-cli/)
48
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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