cleanix-cli 1.0.1__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.0.1/PKG-INFO +436 -0
- cleanix_cli-1.0.1/README.md +401 -0
- cleanix_cli-1.0.1/cleanix/__init__.py +4 -0
- cleanix_cli-1.0.1/cleanix/__main__.py +6 -0
- cleanix_cli-1.0.1/cleanix/cleaners/__init__.py +269 -0
- cleanix_cli-1.0.1/cleanix/cleaners/ai_cli.py +193 -0
- cleanix_cli-1.0.1/cleanix/cleaners/ai_tools.py +224 -0
- cleanix_cli-1.0.1/cleanix/cleaners/app_cruft.py +201 -0
- cleanix_cli-1.0.1/cleanix/cleaners/apple_litter.py +41 -0
- cleanix_cli-1.0.1/cleanix/cleaners/apps.py +89 -0
- cleanix_cli-1.0.1/cleanix/cleaners/apt.py +70 -0
- cleanix_cli-1.0.1/cleanix/cleaners/base.py +173 -0
- cleanix_cli-1.0.1/cleanix/cleaners/broken_symlinks.py +51 -0
- cleanix_cli-1.0.1/cleanix/cleaners/browsers.py +68 -0
- cleanix_cli-1.0.1/cleanix/cleaners/bsd.py +108 -0
- cleanix_cli-1.0.1/cleanix/cleaners/containers.py +82 -0
- cleanix_cli-1.0.1/cleanix/cleaners/coredumps.py +32 -0
- cleanix_cli-1.0.1/cleanix/cleaners/desktop_extras.py +42 -0
- cleanix_cli-1.0.1/cleanix/cleaners/dev_caches.py +57 -0
- cleanix_cli-1.0.1/cleanix/cleaners/distro_pkg.py +127 -0
- cleanix_cli-1.0.1/cleanix/cleaners/dnf.py +56 -0
- cleanix_cli-1.0.1/cleanix/cleaners/editor_litter.py +115 -0
- cleanix_cli-1.0.1/cleanix/cleaners/font_cache.py +29 -0
- cleanix_cli-1.0.1/cleanix/cleaners/ide.py +87 -0
- cleanix_cli-1.0.1/cleanix/cleaners/kernels.py +115 -0
- cleanix_cli-1.0.1/cleanix/cleaners/lang_caches.py +70 -0
- cleanix_cli-1.0.1/cleanix/cleaners/linux_extras.py +77 -0
- cleanix_cli-1.0.1/cleanix/cleaners/localizations.py +70 -0
- cleanix_cli-1.0.1/cleanix/cleaners/logs.py +80 -0
- cleanix_cli-1.0.1/cleanix/cleaners/macos.py +166 -0
- cleanix_cli-1.0.1/cleanix/cleaners/macos_extra.py +125 -0
- cleanix_cli-1.0.1/cleanix/cleaners/memory.py +110 -0
- cleanix_cli-1.0.1/cleanix/cleaners/more_pkg.py +168 -0
- cleanix_cli-1.0.1/cleanix/cleaners/npm_cache.py +36 -0
- cleanix_cli-1.0.1/cleanix/cleaners/packaging_extras.py +140 -0
- cleanix_cli-1.0.1/cleanix/cleaners/pacman.py +63 -0
- cleanix_cli-1.0.1/cleanix/cleaners/pip_cache.py +27 -0
- cleanix_cli-1.0.1/cleanix/cleaners/snapshots.py +126 -0
- cleanix_cli-1.0.1/cleanix/cleaners/sys_extras.py +109 -0
- cleanix_cli-1.0.1/cleanix/cleaners/temp_files.py +48 -0
- cleanix_cli-1.0.1/cleanix/cleaners/thumbnails.py +31 -0
- cleanix_cli-1.0.1/cleanix/cleaners/trash.py +47 -0
- cleanix_cli-1.0.1/cleanix/cleaners/user_cache.py +69 -0
- cleanix_cli-1.0.1/cleanix/cleaners/virtualization.py +76 -0
- cleanix_cli-1.0.1/cleanix/cli.py +810 -0
- cleanix_cli-1.0.1/cleanix/completion.py +131 -0
- cleanix_cli-1.0.1/cleanix/config.py +225 -0
- cleanix_cli-1.0.1/cleanix/core/__init__.py +1 -0
- cleanix_cli-1.0.1/cleanix/core/context.py +147 -0
- cleanix_cli-1.0.1/cleanix/core/engine.py +155 -0
- cleanix_cli-1.0.1/cleanix/core/history.py +55 -0
- cleanix_cli-1.0.1/cleanix/core/models.py +141 -0
- cleanix_cli-1.0.1/cleanix/core/platform.py +117 -0
- cleanix_cli-1.0.1/cleanix/core/quarantine.py +147 -0
- cleanix_cli-1.0.1/cleanix/core/registry.py +58 -0
- cleanix_cli-1.0.1/cleanix/core/report.py +130 -0
- cleanix_cli-1.0.1/cleanix/core/safety.py +166 -0
- cleanix_cli-1.0.1/cleanix/core/utils.py +244 -0
- cleanix_cli-1.0.1/cleanix/reset.py +328 -0
- cleanix_cli-1.0.1/cleanix/scheduler/__init__.py +1 -0
- cleanix_cli-1.0.1/cleanix/scheduler/systemd.py +160 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/PKG-INFO +436 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/SOURCES.txt +68 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/dependency_links.txt +1 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/entry_points.txt +2 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/requires.txt +8 -0
- cleanix_cli-1.0.1/cleanix_cli.egg-info/top_level.txt +1 -0
- cleanix_cli-1.0.1/pyproject.toml +66 -0
- cleanix_cli-1.0.1/setup.cfg +4 -0
- cleanix_cli-1.0.1/tests/test_cleanix.py +265 -0
|
@@ -0,0 +1,436 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cleanix-cli
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: A safe, thorough scheduled system cleaner for every *nix (Linux, macOS, BSD).
|
|
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,cache
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
+
Classifier: Intended Audience :: System Administrators
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
18
|
+
Classifier: Operating System :: POSIX :: BSD
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Topic :: System :: Systems Administration
|
|
25
|
+
Classifier: Topic :: Utilities
|
|
26
|
+
Requires-Python: >=3.10
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
Requires-Dist: rich>=15.0.0
|
|
29
|
+
Requires-Dist: PyYAML>=6.0.3
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest>=9.1.1; extra == "dev"
|
|
32
|
+
Requires-Dist: ruff>=0.15.21; extra == "dev"
|
|
33
|
+
Requires-Dist: mypy>=2.3.0; extra == "dev"
|
|
34
|
+
Requires-Dist: build>=1.5.1; extra == "dev"
|
|
35
|
+
|
|
36
|
+
# Cleanix CLI
|
|
37
|
+
|
|
38
|
+
[](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml)
|
|
39
|
+
[](https://pypi.org/project/cleanix-cli/)
|
|
40
|
+
[](https://pypi.org/project/cleanix-cli/)
|
|
41
|
+
[](https://opensource.org/licenses/MIT)
|
|
42
|
+
|
|
43
|
+
A safe, thorough system cleaner for **every *nix flavour** — Linux (all
|
|
44
|
+
major distros), macOS, and the BSDs. It **analyzes** your OS for junk — caches,
|
|
45
|
+
temp files, package-manager leftovers, orphaned packages, broken symlinks,
|
|
46
|
+
package-update config residue, rotated logs, trash, thumbnails, browser/dev
|
|
47
|
+
caches, container cruft — and only **removes** anything after you confirm.
|
|
48
|
+
|
|
49
|
+
It can run on a **schedule** (via a systemd timer) to periodically analyze the
|
|
50
|
+
system and notify you. Scheduled runs *never delete anything*; they only produce
|
|
51
|
+
a report so you can review and clean on your own terms.
|
|
52
|
+
|
|
53
|
+
## Platform support
|
|
54
|
+
|
|
55
|
+
Cleaners declare which platforms they apply to; `cleanix` auto-detects the OS
|
|
56
|
+
(and Linux distro via `/etc/os-release`) and only runs the relevant ones.
|
|
57
|
+
|
|
58
|
+
| Family | Detected as | Package/system cleaners |
|
|
59
|
+
|----------|------------------------------------|-------------------------|
|
|
60
|
+
| Linux | `linux` + distro id | apt, dnf/yum, pacman, zypper, apk, xbps, portage, flatpak, snap, nix, journald, coredumps, `/var/crash`, `.rpmnew`/`.pacnew`/`.dpkg-old` residue |
|
|
61
|
+
| macOS | `macos` | Homebrew, MacPorts, Xcode (DerivedData/DeviceSupport/simulators), ~/Library caches & logs, Trash |
|
|
62
|
+
| FreeBSD | `freebsd` | pkg cache + autoremove, ports distfiles & work dirs |
|
|
63
|
+
| NetBSD | `netbsd` | pkg, pkgin cache |
|
|
64
|
+
| OpenBSD | `openbsd` | pkg |
|
|
65
|
+
| 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 |
|
|
66
|
+
|
|
67
|
+
Run `cleanix list` to see what applies to your machine, or `cleanix list --all`
|
|
68
|
+
to see every platform's cleaners.
|
|
69
|
+
|
|
70
|
+
## AI / LLM leftovers (triaged, not nuked)
|
|
71
|
+
|
|
72
|
+
Local AI tooling scatters a lot of disposable junk *and* a lot of data you
|
|
73
|
+
deliberately downloaded. Cleanix **triages** — it removes the trash and leaves
|
|
74
|
+
your models and chat history alone:
|
|
75
|
+
|
|
76
|
+
| Tool | Removed (trash) | Kept (your data) |
|
|
77
|
+
|------|-----------------|------------------|
|
|
78
|
+
| **Ollama** | dangling blobs from interrupted pulls, server logs | installed models (referenced blobs/manifests) |
|
|
79
|
+
| **Hugging Face** | `*.incomplete` downloads, `.locks`, `.no_exist` | downloaded model/dataset weights |
|
|
80
|
+
| **PyTorch/Triton/vLLM/CUDA** | Triton, `torch.compile`/inductor, `torch_extensions`, vLLM, `~/.nv/ComputeCache`, FlashInfer JIT caches | — (all pure compile caches) |
|
|
81
|
+
| **LM Studio / Jan** | server logs | models, presets, conversations |
|
|
82
|
+
| **Continue.dev** | rebuildable embeddings index, logs, telemetry | sessions/config |
|
|
83
|
+
| **Claude Code** | throwaway shell snapshots, telemetry cache | projects, history |
|
|
84
|
+
| **Aider** | stray `.aider.tags.cache.*`, `.aider.chat.history.md`, `.aider.input.history` in project trees | — |
|
|
85
|
+
|
|
86
|
+
### AI coding-agent CLIs (retention-aware)
|
|
87
|
+
|
|
88
|
+
These accumulate rolling backups, per-session file-history/checkpoints, debug
|
|
89
|
+
logs, and transcripts that no built-in command reliably prunes. Cleanix applies
|
|
90
|
+
proper **retention** instead of all-or-nothing deletion:
|
|
91
|
+
|
|
92
|
+
| Tool | Removed | Kept |
|
|
93
|
+
|------|---------|------|
|
|
94
|
+
| **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** |
|
|
95
|
+
| **OpenAI Codex** (`~/.codex`) | session rollouts & TUI logs older than the retention age | recent sessions, config |
|
|
96
|
+
| **Gemini CLI** (`~/.gemini/tmp`) | stale per-project session/log data | config, recent sessions |
|
|
97
|
+
| **OpenCode** (`~/.local/share/opencode`) | logs, snapshots, tool-output | the SQLite DB, auth, storage |
|
|
98
|
+
|
|
99
|
+
Two knobs control retention (see `config/default.yaml`):
|
|
100
|
+
|
|
101
|
+
- `keep_backups: 2` — how many newest rolling backups to keep.
|
|
102
|
+
- `ai_history_max_age_days: 30` — transcripts/history/logs older than this are
|
|
103
|
+
offered (chat history is your data, so it's age-gated and conservative).
|
|
104
|
+
|
|
105
|
+
Per-session scratch (todos, shell snapshots, session env) touched within the
|
|
106
|
+
last day is always left alone, so cleaning never disturbs a live agent session.
|
|
107
|
+
|
|
108
|
+
## General app bloat
|
|
109
|
+
|
|
110
|
+
- **Electron/Chromium apps** (VS Code, Slack, Discord, Signal, Obsidian, …):
|
|
111
|
+
removes only rebuildable `Cache`/`Code Cache`/`GPUCache`/`Dawn*Cache`/
|
|
112
|
+
`CachedData`/`Crashpad` — **never** `Local Storage`, `IndexedDB`,
|
|
113
|
+
`Service Worker`, or cookies (so you stay logged in). Covers both
|
|
114
|
+
`~/.config/*` and Flatpak (`~/.var/app/*`) apps.
|
|
115
|
+
- **Flatpak app caches** — every app's `~/.var/app/*/cache`.
|
|
116
|
+
- **GPU shader caches** — Mesa (`mesa_shader_cache[_db]`), NVIDIA `GLCache`,
|
|
117
|
+
RADV/AMD Vulkan caches (rebuilt after driver updates).
|
|
118
|
+
- **Steam** — per-game shader caches, interrupted downloads, HTTP cache.
|
|
119
|
+
- **JetBrains IDEs** — caches, logs, and indexes (Linux `~/.cache/JetBrains`,
|
|
120
|
+
macOS `~/Library/Caches/JetBrains`).
|
|
121
|
+
|
|
122
|
+
Cleaners never offer the same path twice: dedicated cleaners own their
|
|
123
|
+
directories and the generic `~/.cache` catch-all defers to them.
|
|
124
|
+
|
|
125
|
+
## Shell completion
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
cleanix completion bash | sudo tee /etc/bash_completion.d/cleanix
|
|
129
|
+
cleanix completion zsh > ~/.zfunc/_cleanix # a dir on your $fpath
|
|
130
|
+
cleanix completion fish > ~/.config/fish/completions/cleanix.fish
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Completes subcommands, options, cleaner ids (for `--only`/`--exclude`) and config
|
|
134
|
+
keys — baked in from the live build.
|
|
135
|
+
|
|
136
|
+
## Safe memory reclamation (RAM + swap)
|
|
137
|
+
|
|
138
|
+
Opt-in cleaners that free memory **without ever killing or trimming apps**:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
sudo cleanix clean --only memory --execute # drop clean page/dentry/inode cache
|
|
142
|
+
sudo cleanix clean --only swap --execute # move swap back to RAM (OOM-guarded)
|
|
143
|
+
sudo cleanix clean --only memory_macos --execute # macOS `purge`
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- `memory` runs `sync` then `drop_caches` — the kernel only releases *clean*
|
|
147
|
+
cached pages, re-reading from disk later; no process loses data.
|
|
148
|
+
- `swap` runs `swapoff -a && swapon -a` **only when free RAM comfortably exceeds
|
|
149
|
+
swap in use** (20% headroom), so it can never trigger an OOM kill.
|
|
150
|
+
- These are excluded from the default `scan`/`clean` (their effect is transient);
|
|
151
|
+
run them explicitly with `--only`.
|
|
152
|
+
|
|
153
|
+
## IDE & application coverage
|
|
154
|
+
|
|
155
|
+
- **IDEs** (`ide_caches`): VS Code and forks (VSCodium, Cursor, Windsurf, …)
|
|
156
|
+
logs / `CachedExtensionVSIXs` / stale workspace storage, Sublime, Atom, Emacs
|
|
157
|
+
native-comp cache, Zed logs, Qt Creator, Godot, Unity — plus JetBrains and
|
|
158
|
+
Xcode via their dedicated cleaners.
|
|
159
|
+
- **Apps** (`app_leftovers`, `snap_app_cache`): logs/crash-reports/temp for
|
|
160
|
+
Minecraft, Steam, Heroic, Lutris, Bottles, OBS, Zoom, Skype, Kodi, Nextcloud,
|
|
161
|
+
Dropbox, Ferdium/Rambox, browser crash reports, and every snap's per-app cache.
|
|
162
|
+
|
|
163
|
+
## Reversible cleaning, history & dashboard
|
|
164
|
+
|
|
165
|
+
- **Quarantine (undo):** `cleanix clean --quarantine` *moves* junk into a
|
|
166
|
+
per-run quarantine instead of deleting it. Undo with `cleanix restore`, reclaim
|
|
167
|
+
the space for good with `cleanix quarantine empty`, review with
|
|
168
|
+
`cleanix quarantine list`. A safety net most cleaners don't offer.
|
|
169
|
+
- **History & stats:** every real clean is logged; `cleanix stats` shows lifetime
|
|
170
|
+
space reclaimed and recent runs.
|
|
171
|
+
- **`cleanix info`:** one-glance dashboard — OS/distro, detected package
|
|
172
|
+
managers, applicable cleaner counts, config path, lifetime cleaned, quarantine
|
|
173
|
+
size.
|
|
174
|
+
- **Parallel scanning** across a thread pool (≈1.4×+ faster), with a live
|
|
175
|
+
progress bar.
|
|
176
|
+
- **`scan --sort size --top N`** to focus on the biggest wins.
|
|
177
|
+
- **User ignore-globs:** `protected_globs` in config adds your own never-delete
|
|
178
|
+
paths on top of the built-in guard.
|
|
179
|
+
|
|
180
|
+
## Highlights
|
|
181
|
+
|
|
182
|
+
- **Scan first, clean on confirmation.** Nothing is deleted without an explicit
|
|
183
|
+
`--yes` or an interactive confirmation.
|
|
184
|
+
- **Dry-run by default.** `cleanix clean` shows what *would* be removed unless you
|
|
185
|
+
pass `--execute`.
|
|
186
|
+
- **Safe deletes.** A hard-coded protected-path guard refuses to touch critical
|
|
187
|
+
system directories on every platform (`/`, `/etc`, `/usr`, `/System`,
|
|
188
|
+
`/Library`, `$HOME`, `~/Library`, `/usr/ports`, ...).
|
|
189
|
+
- **Orphan & leftover aware.** Finds orphaned packages, residual configs
|
|
190
|
+
(dpkg `rc` state), package-update residue (`.rpmnew`/`.pacnew`/`.dpkg-old`),
|
|
191
|
+
dangling symlinks, and orphaned launcher entries — the cruft "improperly
|
|
192
|
+
designed" packages leave behind.
|
|
193
|
+
- **Accurate sizing.** Uses actual allocated blocks, not apparent size, so
|
|
194
|
+
sparse files don't wildly overstate reclaimable space. Actively-written files
|
|
195
|
+
are left alone (in-use guard).
|
|
196
|
+
- **Modular & platform-gated.** Each junk source is an isolated, auditable module
|
|
197
|
+
that declares the platforms it applies to.
|
|
198
|
+
- **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
|
|
199
|
+
note) when you run unprivileged.
|
|
200
|
+
- **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
|
|
201
|
+
|
|
202
|
+
## Install
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
pip install cleanix-cli # from PyPI
|
|
206
|
+
# or from source:
|
|
207
|
+
cd cleanix-cli && pip install -e .
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
This installs the `cleanix` command. Standalone Linux/macOS binaries are also
|
|
211
|
+
attached to each [GitHub Release](https://github.com/CloudOpsWorld/cleanix-cli/releases).
|
|
212
|
+
|
|
213
|
+
## Usage
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
# List available cleaners
|
|
217
|
+
cleanix list
|
|
218
|
+
|
|
219
|
+
# Analyze the system (read-only) and print a report
|
|
220
|
+
cleanix scan
|
|
221
|
+
|
|
222
|
+
# Analyze only specific cleaners
|
|
223
|
+
cleanix scan --only trash,thumbnails,apt
|
|
224
|
+
|
|
225
|
+
# Preview what a clean would remove (dry-run, the default)
|
|
226
|
+
cleanix clean
|
|
227
|
+
|
|
228
|
+
# Actually delete, asking for confirmation
|
|
229
|
+
cleanix clean --execute
|
|
230
|
+
|
|
231
|
+
# Delete without prompting (for scripts)
|
|
232
|
+
cleanix clean --execute --yes --only trash,pip_cache
|
|
233
|
+
|
|
234
|
+
# Emit the scan report as JSON (for tooling / notifications)
|
|
235
|
+
cleanix scan --json
|
|
236
|
+
|
|
237
|
+
# Install a systemd timer that scans weekly and notifies you
|
|
238
|
+
cleanix schedule install --frequency weekly
|
|
239
|
+
|
|
240
|
+
# Check / remove the schedule
|
|
241
|
+
cleanix schedule status
|
|
242
|
+
cleanix schedule uninstall
|
|
243
|
+
|
|
244
|
+
# View and change settings (no YAML editing needed)
|
|
245
|
+
cleanix config list
|
|
246
|
+
cleanix config set remove_old_kernels false
|
|
247
|
+
cleanix config set keep_kernels 3
|
|
248
|
+
cleanix config unset keep_kernels # revert to default
|
|
249
|
+
|
|
250
|
+
# See a factory-reset plan for this OS (advisory — runs nothing)
|
|
251
|
+
cleanix factory-reset
|
|
252
|
+
cleanix factory-reset --scope user
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
## Configuration via CLI
|
|
256
|
+
|
|
257
|
+
`cleanix config` reads/writes `~/.config/cleanix/config.yaml` with type-checked
|
|
258
|
+
values, so you never have to hand-edit YAML:
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
cleanix config list # every setting, value, source, description
|
|
262
|
+
cleanix config get <key>
|
|
263
|
+
cleanix config set <key> <value> # bool/int/float/list are validated
|
|
264
|
+
cleanix config unset <key> # revert to the built-in default
|
|
265
|
+
cleanix config path
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## Factory-reset advisor
|
|
269
|
+
|
|
270
|
+
`cleanix factory-reset` detects how your OS can be reset and prints a **tiered,
|
|
271
|
+
copy-pasteable plan** — it never executes anything destructive:
|
|
272
|
+
|
|
273
|
+
- **NixOS / Guix** → declarative rollback to a prior generation (✅ reversible)
|
|
274
|
+
- **rpm-ostree** (Silverblue/Kinoite) → `rpm-ostree reset` to the base image (✅)
|
|
275
|
+
- **openSUSE MicroOS** → `snapper rollback` (✅)
|
|
276
|
+
- **macOS** → the built-in "Erase All Content and Settings" (recommended)
|
|
277
|
+
- **Traditional distros** (Fedora/Ubuntu/Arch) → honestly reports there is *no*
|
|
278
|
+
true factory reset; suggests snapshot-restore/reinstall and gives best-effort
|
|
279
|
+
package/config/user reset steps.
|
|
280
|
+
|
|
281
|
+
`--scope user|packages|system|full` controls how much the plan covers.
|
|
282
|
+
|
|
283
|
+
### Executing a reversible reset
|
|
284
|
+
|
|
285
|
+
On reversible systems only, cleanix can run the rollback for you:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
sudo cleanix factory-reset --execute
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
This is heavily gated:
|
|
292
|
+
|
|
293
|
+
- **Only reversible strategies** run — NixOS (`nixos-rebuild switch --rollback`),
|
|
294
|
+
rpm-ostree (`rpm-ostree reset`), MicroOS (`snapper rollback`), Guix
|
|
295
|
+
(`guix system roll-back`). Traditional distros and macOS **refuse to execute**.
|
|
296
|
+
- **Only the reversible rollback command** runs — never the irreversible
|
|
297
|
+
dotfile/`rm -rf` steps (those stay advisory).
|
|
298
|
+
- Requires **root**, an **interactive terminal**, and a **typed confirmation
|
|
299
|
+
phrase** (`reset <hostname>`). Each action prints its **undo** command.
|
|
300
|
+
- Stops on the first failure.
|
|
301
|
+
|
|
302
|
+
Without `--execute`, `factory-reset` only prints the plan.
|
|
303
|
+
|
|
304
|
+
## System-wide mode (root)
|
|
305
|
+
|
|
306
|
+
Run unprivileged, cleanix scans **your** home. Run as **root/sudo**, it
|
|
307
|
+
automatically sweeps **every real user's home** plus system-wide locations:
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
sudo cleanix scan # all users + system (auto when root)
|
|
311
|
+
sudo cleanix scan --current-user # restrict to the invoking user
|
|
312
|
+
cleanix scan --all-users # force multi-user even unprivileged
|
|
313
|
+
sudo cleanix scan --min-uid 500 # change the "real user" uid threshold
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
How it works:
|
|
317
|
+
|
|
318
|
+
- Cleaners declare a **scope**: *user* (trash, caches, browsers, AI tools, …)
|
|
319
|
+
or *system* (package managers, `/var/log`, journal, coredumps, …).
|
|
320
|
+
- User-scoped cleaners run **once per target user**, resolving `~`, `~/.cache`,
|
|
321
|
+
`~/.config`, uid, etc. against *that* user — never leaking root's environment.
|
|
322
|
+
- Target users come from `/etc/passwd`: root plus accounts with uid ≥ `min_uid`
|
|
323
|
+
(1000 on Linux/BSD, 500 on macOS) that have a real home directory.
|
|
324
|
+
- Shared/system paths yielded for multiple users are **de-duplicated**, so
|
|
325
|
+
nothing is offered — or deleted — twice.
|
|
326
|
+
- The protected-path guard is extended to cover **every** scanned user's home
|
|
327
|
+
(and their `~/.config`, `~/.local`, `~/Library`, …), so a bug can never wipe
|
|
328
|
+
another user's home.
|
|
329
|
+
|
|
330
|
+
## Report-only tier (backups & snapshots)
|
|
331
|
+
|
|
332
|
+
Some things are *leftovers* but also *recovery data* — filesystem snapshots,
|
|
333
|
+
mobile-device backups, suspended-VM memory images. Cleanix surfaces these with
|
|
334
|
+
their size and the **correct removal command**, but they are **never** eligible
|
|
335
|
+
for deletion (`clean` skips them; even a forced attempt is refused):
|
|
336
|
+
|
|
337
|
+
```
|
|
338
|
+
Report-only — review and remove manually (never auto-deleted)
|
|
339
|
+
7.5 GiB Timeshift snapshot: 2026-01-01 timeshift --delete --snapshot '2026-01-01'
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Covered report-only: Timeshift/Snapper snapshots, libvirt saved VM states,
|
|
343
|
+
macOS Time Machine local snapshots, iOS device backups, macOS sleep image.
|
|
344
|
+
|
|
345
|
+
## Extended coverage
|
|
346
|
+
|
|
347
|
+
Beyond the core cleaners, cleanix also handles:
|
|
348
|
+
|
|
349
|
+
- **Old kernels** — package-manager-driven; always keeps the running kernel and
|
|
350
|
+
the newest `keep_kernels` (default 2). Set `remove_old_kernels: false` to skip.
|
|
351
|
+
- **System caches & spools** — `/var/cache` (PackageKit/man/fontconfig/cups),
|
|
352
|
+
Debian `/var/backups`, ABRT/apport crash spool, staged offline-update payloads.
|
|
353
|
+
- **Language package caches** — Go modcache, rustup/deno/bun/nvm/pnpm, Android
|
|
354
|
+
SDK. Offline repos (Maven/Ivy/sbt/Coursier/NuGet/RubyGems) gated behind
|
|
355
|
+
`include_offline_repos`.
|
|
356
|
+
- **Desktop search indexes** — Baloo, Tracker, Zeitgeist, GVFS metadata.
|
|
357
|
+
- **VM/cloud tooling** — VirtualBox logs, Vagrant boxes, kube/minikube/helm,
|
|
358
|
+
AWS/Azure/gcloud/Terraform/Pulumi caches.
|
|
359
|
+
- **Editor & build litter** — Vim/Neovim swap/undo, `__pycache__`,
|
|
360
|
+
`.pytest_cache`/`.mypy_cache`/`.ruff_cache`/`.tox`, loose core dumps.
|
|
361
|
+
- **macOS extras** — Saved Application State, CocoaPods/Carthage, QuickLook.
|
|
362
|
+
- **Opt-in** (off by default): editor backup files (`*~`/`*.bak`/`*.orig`) via
|
|
363
|
+
`remove_backup_files`, and localepurge-style unused locales/man-pages via
|
|
364
|
+
`purge_unused_locales`.
|
|
365
|
+
|
|
366
|
+
## Safety model
|
|
367
|
+
|
|
368
|
+
1. **Two-phase**: `scan` is always read-only. `clean` defaults to dry-run.
|
|
369
|
+
2. **Protected paths**: deletion of (or inside) critical paths is refused at the
|
|
370
|
+
lowest level — see `cleanix/core/safety.py`.
|
|
371
|
+
3. **Age thresholds**: temp/log cleaners only consider files older than a
|
|
372
|
+
configurable age, so in-use files are left alone.
|
|
373
|
+
4. **Scheduled = analyze only**: the timer runs `scan` and writes a report; it
|
|
374
|
+
does not clean.
|
|
375
|
+
|
|
376
|
+
## Configuration
|
|
377
|
+
|
|
378
|
+
Defaults live in `cleanix/config.py`. Override them with a YAML file at
|
|
379
|
+
`~/.config/cleanix/config.yaml` (see `config/default.yaml` for the shape).
|
|
380
|
+
|
|
381
|
+
## Project layout
|
|
382
|
+
|
|
383
|
+
```
|
|
384
|
+
cleanix/
|
|
385
|
+
cli.py # argparse entry point (scan / clean / list / schedule)
|
|
386
|
+
config.py # defaults + YAML overrides
|
|
387
|
+
core/
|
|
388
|
+
models.py # CleanableItem, CleanerReport, dataclasses
|
|
389
|
+
platform.py # OS + distro detection, platform tokens
|
|
390
|
+
context.py # multi-user scanning (target users, current-user binding)
|
|
391
|
+
safety.py # protected-path guard + safe delete
|
|
392
|
+
engine.py # runs cleaners, aggregates reports, executes cleans
|
|
393
|
+
registry.py # discovers, platform-filters & instantiates cleaners
|
|
394
|
+
utils.py # sizes (allocated blocks), walking, age/in-use guards
|
|
395
|
+
report.py # rich tables + JSON rendering
|
|
396
|
+
cleaners/
|
|
397
|
+
base.py # Cleaner ABC (declares .platforms)
|
|
398
|
+
# cross-platform
|
|
399
|
+
trash, thumbnails, user_cache, temp_files, font_cache, browsers,
|
|
400
|
+
broken_symlinks, apple_litter, dev_caches, pip_cache, npm_cache, containers
|
|
401
|
+
# logs & crashes
|
|
402
|
+
logs, coredumps, linux_extras (config residue + /var/crash)
|
|
403
|
+
# linux package managers
|
|
404
|
+
apt, dnf/yum, pacman, distro_pkg (zypper/apk/xbps/portage),
|
|
405
|
+
more_pkg (conda/mamba, guix, eopkg, swupd, opam, sdkman, gem, cpanm),
|
|
406
|
+
packaging_extras (flatpak/snap/nix/appimage)
|
|
407
|
+
# AI / LLM engines & clients
|
|
408
|
+
ai_tools (ollama, huggingface, compile caches, ai clients, aider)
|
|
409
|
+
ai_cli (claude code, codex, gemini cli, opencode — retention-aware)
|
|
410
|
+
# desktop-app bloat
|
|
411
|
+
app_cruft (electron caches, flatpak caches, gpu shaders, steam, jetbrains)
|
|
412
|
+
# extended system leftovers
|
|
413
|
+
sys_extras (/var/cache, /var/backups, crash spool, offline updates)
|
|
414
|
+
kernels (old-kernel purge), localizations (localepurge, opt-in)
|
|
415
|
+
# extended user leftovers
|
|
416
|
+
lang_caches (go/rust/js/.net/jvm), desktop_extras (search indexes)
|
|
417
|
+
virtualization (vbox/vagrant/k8s/cloud), editor_litter (swap/pycache/cores)
|
|
418
|
+
# backups & snapshots (report-only tier)
|
|
419
|
+
snapshots (timeshift/snapper/timemachine/device backups)
|
|
420
|
+
# macOS
|
|
421
|
+
macos (caches, trash, diagnostics, homebrew, macports, xcode)
|
|
422
|
+
macos_extra (saved state, cocoapods, sleep image)
|
|
423
|
+
# BSD
|
|
424
|
+
bsd (freebsd pkg, distfiles/work dirs, pkgin)
|
|
425
|
+
scheduler/
|
|
426
|
+
systemd.py # install/uninstall/status of a user systemd timer
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
|
|
430
|
+
implement `find_items()` (read-only, yields `CleanableItem`s), and register it in
|
|
431
|
+
`cleaners/__init__.py`. The engine handles dry-run, confirmation, root checks,
|
|
432
|
+
and the safety guard for you.
|
|
433
|
+
|
|
434
|
+
## License
|
|
435
|
+
|
|
436
|
+
MIT
|