cleanix-cli 1.0.1__tar.gz → 1.2.0__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.2.0/MANIFEST.in +4 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/PKG-INFO +90 -5
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/README.md +89 -4
- cleanix_cli-1.2.0/RELEASING.md +64 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/__init__.py +1 -1
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/__init__.py +16 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/base.py +31 -7
- cleanix_cli-1.2.0/cleanix/cleaners/big_files.py +83 -0
- cleanix_cli-1.2.0/cleanix/cleaners/browser_profiles.py +319 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/bsd.py +16 -10
- cleanix_cli-1.2.0/cleanix/cleaners/containerd.py +82 -0
- cleanix_cli-1.2.0/cleanix/cleaners/containers.py +235 -0
- cleanix_cli-1.2.0/cleanix/cleaners/downloads.py +91 -0
- cleanix_cli-1.2.0/cleanix/cleaners/duplicates.py +164 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/macos.py +16 -4
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/macos_extra.py +19 -7
- cleanix_cli-1.2.0/cleanix/cleaners/project_cruft.py +185 -0
- cleanix_cli-1.2.0/cleanix/cleaners/toolchains.py +149 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cli.py +361 -13
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/config.py +52 -2
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/history.py +36 -3
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/report.py +23 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/safety.py +60 -15
- cleanix_cli-1.2.0/cleanix/scheduler/__init__.py +34 -0
- cleanix_cli-1.2.0/cleanix/scheduler/cron.py +137 -0
- cleanix_cli-1.2.0/cleanix/scheduler/launchd.py +158 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/scheduler/systemd.py +6 -2
- cleanix_cli-1.2.0/cleanix.1 +202 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/PKG-INFO +90 -5
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/SOURCES.txt +18 -0
- cleanix_cli-1.2.0/packaging/README.md +49 -0
- cleanix_cli-1.2.0/packaging/aur/PKGBUILD +40 -0
- cleanix_cli-1.2.0/packaging/homebrew/cleanix.rb +45 -0
- cleanix_cli-1.2.0/packaging/rpm/cleanix-cli.spec +56 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/pyproject.toml +1 -1
- cleanix_cli-1.2.0/requirements.txt +2 -0
- cleanix_cli-1.2.0/scripts/gen_manpage.py +105 -0
- cleanix_cli-1.2.0/tests/test_cleanix.py +817 -0
- cleanix_cli-1.0.1/cleanix/cleaners/containers.py +0 -82
- cleanix_cli-1.0.1/cleanix/scheduler/__init__.py +0 -1
- cleanix_cli-1.0.1/tests/test_cleanix.py +0 -265
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/__main__.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ai_cli.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ai_tools.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/app_cruft.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apple_litter.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apps.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/apt.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/broken_symlinks.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/browsers.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/coredumps.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/desktop_extras.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/dev_caches.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/distro_pkg.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/dnf.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/editor_litter.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/font_cache.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/ide.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/kernels.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/lang_caches.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/linux_extras.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/localizations.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/logs.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/memory.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/more_pkg.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/npm_cache.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/packaging_extras.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/pacman.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/pip_cache.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/snapshots.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/sys_extras.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/temp_files.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/thumbnails.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/trash.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/user_cache.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/cleaners/virtualization.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/completion.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/__init__.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/context.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/engine.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/models.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/platform.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/quarantine.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/registry.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/core/utils.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix/reset.py +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/dependency_links.txt +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/entry_points.txt +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/requires.txt +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/cleanix_cli.egg-info/top_level.txt +0 -0
- {cleanix_cli-1.0.1 → cleanix_cli-1.2.0}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: cleanix-cli
|
|
3
|
-
Version: 1.0
|
|
3
|
+
Version: 1.2.0
|
|
4
4
|
Summary: A safe, thorough scheduled system cleaner for every *nix (Linux, macOS, BSD).
|
|
5
5
|
Author: cleanix-cli contributors
|
|
6
6
|
License: MIT
|
|
@@ -46,7 +46,8 @@ temp files, package-manager leftovers, orphaned packages, broken symlinks,
|
|
|
46
46
|
package-update config residue, rotated logs, trash, thumbnails, browser/dev
|
|
47
47
|
caches, container cruft — and only **removes** anything after you confirm.
|
|
48
48
|
|
|
49
|
-
It can run on a **schedule** (
|
|
49
|
+
It can run on a **schedule** (a systemd timer on Linux/BSD, a launchd agent on
|
|
50
|
+
macOS) to periodically analyze the
|
|
50
51
|
system and notify you. Scheduled runs *never delete anything*; they only produce
|
|
51
52
|
a report so you can review and clean on your own terms.
|
|
52
53
|
|
|
@@ -122,6 +123,84 @@ last day is always left alone, so cleaning never disturbs a live agent session.
|
|
|
122
123
|
Cleaners never offer the same path twice: dedicated cleaners own their
|
|
123
124
|
directories and the generic `~/.cache` catch-all defers to them.
|
|
124
125
|
|
|
126
|
+
## More reclamation & review
|
|
127
|
+
|
|
128
|
+
- **Old toolchain versions** (`toolchains`). Version managers hoard
|
|
129
|
+
multi-gigabyte installed runtimes — old `~/.nvm` node builds, `~/.pyenv` /
|
|
130
|
+
`~/.rbenv` versions, `rustup` toolchains, SDKMAN candidates, `asdf` installs.
|
|
131
|
+
Cleanix keeps the **active** version (always protected) plus the newest
|
|
132
|
+
`keep_toolchain_versions` (default 2) and offers the rest for removal. It
|
|
133
|
+
*skips a manager entirely if it can't prove which version is active* — pair
|
|
134
|
+
with `clean --quarantine` to make removals reversible. Disable with
|
|
135
|
+
`prune_old_toolchains: false`.
|
|
136
|
+
- **Stale project cruft** (`project_cruft`, report-only). Finds regenerable
|
|
137
|
+
`node_modules` / `.venv` / `target` / `.gradle` dirs in projects under
|
|
138
|
+
`project_scan_dirs` you haven't touched in `project_stale_days` (default 120).
|
|
139
|
+
- **Large files** (`big_files`, report-only). The biggest files in `$HOME`, so
|
|
140
|
+
you can see what filled the disk. Never deletes — just a sized list + `rm` hint.
|
|
141
|
+
- **Duplicate files** (`duplicates`, report-only). Identical large files (same
|
|
142
|
+
size + SHA-256) grouped with the space reclaimable by keeping one copy.
|
|
143
|
+
- **Stale downloads** (`downloads`, report-only). Old, large installers/ISOs in
|
|
144
|
+
`~/Downloads` (which stays hard-protected from deletion).
|
|
145
|
+
- **Orphaned browser profiles** (`browser_profiles`, report-only). Secondary
|
|
146
|
+
Chrome/Chromium/Firefox profiles idle for `browser_profile_stale_days`, with a
|
|
147
|
+
clear warning that a profile holds bookmarks/passwords/history.
|
|
148
|
+
|
|
149
|
+
## Working with what a scan finds
|
|
150
|
+
|
|
151
|
+
- `cleanix explain <id>` — read-only, shows the **exact** paths/commands one
|
|
152
|
+
cleaner would consider (with size, root, delete-vs-report), for building trust.
|
|
153
|
+
- `cleanix clean --interactive` — pick individual items from a checklist before
|
|
154
|
+
removing (selection is per-item, not just per-cleaner).
|
|
155
|
+
- `cleanix clean --simulate` — write the exact target list to a file, delete
|
|
156
|
+
nothing (stronger than the dry-run summary).
|
|
157
|
+
- `cleanix clean --execute` — writes a **per-file audit manifest** to
|
|
158
|
+
`~/.local/state/cleanix/runs/` and prints the real `df` free-space change.
|
|
159
|
+
- `--profile safe|balanced|aggressive` — one flag to bundle the opt-in settings
|
|
160
|
+
(aggressive enables offline-repo/backup/locale/all-image pruning; it never
|
|
161
|
+
bundles volume removal).
|
|
162
|
+
- `--min-size 100M` — ignore items below a threshold to cut table noise.
|
|
163
|
+
- `cleanix scan --json` emits a **versioned** schema (`schema_version`, host,
|
|
164
|
+
os, `cleanable_bytes` vs `report_only_bytes`) for CI/tooling.
|
|
165
|
+
- `cleanix dashboard` — lifetime reclaim trend (sparkline) plus the last
|
|
166
|
+
scheduled scan's top sources, at a glance.
|
|
167
|
+
|
|
168
|
+
## Install & packaging
|
|
169
|
+
|
|
170
|
+
- **PyPI:** `pip install cleanix-cli` (or `pipx install cleanix-cli`).
|
|
171
|
+
- **Standalone binaries** are attached to each [GitHub Release] alongside a
|
|
172
|
+
`SHA256SUMS` file and keyless **build-provenance attestations** — verify a
|
|
173
|
+
download with `gh attestation verify <file> --repo CloudOpsWorld/cleanix-cli`.
|
|
174
|
+
- **Homebrew / AUR / Fedora** packaging lives under [`packaging/`](packaging/),
|
|
175
|
+
along with a `cleanix.1` **man page** generated from the CLI
|
|
176
|
+
(`python scripts/gen_manpage.py`).
|
|
177
|
+
|
|
178
|
+
[GitHub Release]: https://github.com/CloudOpsWorld/cleanix-cli/releases
|
|
179
|
+
|
|
180
|
+
## Container leftovers (Docker / Podman / nerdctl / crictl)
|
|
181
|
+
|
|
182
|
+
A *leftover* is anything the engine keeps that **no existing container
|
|
183
|
+
references** and can be regenerated. Each category is surfaced as its own item
|
|
184
|
+
whose estimated size matches exactly what pruning it reclaims — so the number
|
|
185
|
+
you see is the number you get (no more counting unused-but-tagged images or
|
|
186
|
+
volumes you never asked to touch):
|
|
187
|
+
|
|
188
|
+
- **Dangling (untagged) images** — `docker image prune -f`
|
|
189
|
+
- **Stopped containers** (writable layers) — `docker container prune -f`
|
|
190
|
+
- **Build cache** — `docker builder prune -f`
|
|
191
|
+
- **Unused networks** — `docker network prune -f`
|
|
192
|
+
|
|
193
|
+
Two categories stay **opt-in** because they can destroy real work:
|
|
194
|
+
|
|
195
|
+
- `docker_prune_all_images` — also remove *tagged* images not used by any
|
|
196
|
+
container (`image prune -a`); frees more but forces a re-pull next time.
|
|
197
|
+
- `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
|
|
198
|
+
databases or other real data.
|
|
199
|
+
|
|
200
|
+
> On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
|
|
201
|
+
> space *inside* the VM; the host-side `Docker.raw` file may not shrink until
|
|
202
|
+
> Docker Desktop compacts it.
|
|
203
|
+
|
|
125
204
|
## Shell completion
|
|
126
205
|
|
|
127
206
|
```bash
|
|
@@ -197,7 +276,10 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
|
|
|
197
276
|
that declares the platforms it applies to.
|
|
198
277
|
- **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
|
|
199
278
|
note) when you run unprivileged.
|
|
200
|
-
- **Scheduling.** Install a
|
|
279
|
+
- **Scheduling.** Install a periodic read-only scan that reports (and notifies)
|
|
280
|
+
on a daily/weekly/monthly cadence — a **systemd user timer** on Linux, a
|
|
281
|
+
**launchd LaunchAgent** on macOS, and a **cron job** on the BSDs (or any
|
|
282
|
+
system with `crontab` but no systemd). Same `cleanix schedule` command on all.
|
|
201
283
|
|
|
202
284
|
## Install
|
|
203
285
|
|
|
@@ -234,7 +316,8 @@ cleanix clean --execute --yes --only trash,pip_cache
|
|
|
234
316
|
# Emit the scan report as JSON (for tooling / notifications)
|
|
235
317
|
cleanix scan --json
|
|
236
318
|
|
|
237
|
-
# Install a
|
|
319
|
+
# Install a weekly read-only scan that notifies you
|
|
320
|
+
# (systemd timer on Linux/BSD, launchd agent on macOS)
|
|
238
321
|
cleanix schedule install --frequency weekly
|
|
239
322
|
|
|
240
323
|
# Check / remove the schedule
|
|
@@ -423,7 +506,9 @@ cleanix/
|
|
|
423
506
|
# BSD
|
|
424
507
|
bsd (freebsd pkg, distfiles/work dirs, pkgin)
|
|
425
508
|
scheduler/
|
|
426
|
-
|
|
509
|
+
__init__.py # backend() — picks systemd or launchd for the OS
|
|
510
|
+
systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
|
|
511
|
+
launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
|
|
427
512
|
```
|
|
428
513
|
|
|
429
514
|
To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
|
|
@@ -11,7 +11,8 @@ temp files, package-manager leftovers, orphaned packages, broken symlinks,
|
|
|
11
11
|
package-update config residue, rotated logs, trash, thumbnails, browser/dev
|
|
12
12
|
caches, container cruft — and only **removes** anything after you confirm.
|
|
13
13
|
|
|
14
|
-
It can run on a **schedule** (
|
|
14
|
+
It can run on a **schedule** (a systemd timer on Linux/BSD, a launchd agent on
|
|
15
|
+
macOS) to periodically analyze the
|
|
15
16
|
system and notify you. Scheduled runs *never delete anything*; they only produce
|
|
16
17
|
a report so you can review and clean on your own terms.
|
|
17
18
|
|
|
@@ -87,6 +88,84 @@ last day is always left alone, so cleaning never disturbs a live agent session.
|
|
|
87
88
|
Cleaners never offer the same path twice: dedicated cleaners own their
|
|
88
89
|
directories and the generic `~/.cache` catch-all defers to them.
|
|
89
90
|
|
|
91
|
+
## More reclamation & review
|
|
92
|
+
|
|
93
|
+
- **Old toolchain versions** (`toolchains`). Version managers hoard
|
|
94
|
+
multi-gigabyte installed runtimes — old `~/.nvm` node builds, `~/.pyenv` /
|
|
95
|
+
`~/.rbenv` versions, `rustup` toolchains, SDKMAN candidates, `asdf` installs.
|
|
96
|
+
Cleanix keeps the **active** version (always protected) plus the newest
|
|
97
|
+
`keep_toolchain_versions` (default 2) and offers the rest for removal. It
|
|
98
|
+
*skips a manager entirely if it can't prove which version is active* — pair
|
|
99
|
+
with `clean --quarantine` to make removals reversible. Disable with
|
|
100
|
+
`prune_old_toolchains: false`.
|
|
101
|
+
- **Stale project cruft** (`project_cruft`, report-only). Finds regenerable
|
|
102
|
+
`node_modules` / `.venv` / `target` / `.gradle` dirs in projects under
|
|
103
|
+
`project_scan_dirs` you haven't touched in `project_stale_days` (default 120).
|
|
104
|
+
- **Large files** (`big_files`, report-only). The biggest files in `$HOME`, so
|
|
105
|
+
you can see what filled the disk. Never deletes — just a sized list + `rm` hint.
|
|
106
|
+
- **Duplicate files** (`duplicates`, report-only). Identical large files (same
|
|
107
|
+
size + SHA-256) grouped with the space reclaimable by keeping one copy.
|
|
108
|
+
- **Stale downloads** (`downloads`, report-only). Old, large installers/ISOs in
|
|
109
|
+
`~/Downloads` (which stays hard-protected from deletion).
|
|
110
|
+
- **Orphaned browser profiles** (`browser_profiles`, report-only). Secondary
|
|
111
|
+
Chrome/Chromium/Firefox profiles idle for `browser_profile_stale_days`, with a
|
|
112
|
+
clear warning that a profile holds bookmarks/passwords/history.
|
|
113
|
+
|
|
114
|
+
## Working with what a scan finds
|
|
115
|
+
|
|
116
|
+
- `cleanix explain <id>` — read-only, shows the **exact** paths/commands one
|
|
117
|
+
cleaner would consider (with size, root, delete-vs-report), for building trust.
|
|
118
|
+
- `cleanix clean --interactive` — pick individual items from a checklist before
|
|
119
|
+
removing (selection is per-item, not just per-cleaner).
|
|
120
|
+
- `cleanix clean --simulate` — write the exact target list to a file, delete
|
|
121
|
+
nothing (stronger than the dry-run summary).
|
|
122
|
+
- `cleanix clean --execute` — writes a **per-file audit manifest** to
|
|
123
|
+
`~/.local/state/cleanix/runs/` and prints the real `df` free-space change.
|
|
124
|
+
- `--profile safe|balanced|aggressive` — one flag to bundle the opt-in settings
|
|
125
|
+
(aggressive enables offline-repo/backup/locale/all-image pruning; it never
|
|
126
|
+
bundles volume removal).
|
|
127
|
+
- `--min-size 100M` — ignore items below a threshold to cut table noise.
|
|
128
|
+
- `cleanix scan --json` emits a **versioned** schema (`schema_version`, host,
|
|
129
|
+
os, `cleanable_bytes` vs `report_only_bytes`) for CI/tooling.
|
|
130
|
+
- `cleanix dashboard` — lifetime reclaim trend (sparkline) plus the last
|
|
131
|
+
scheduled scan's top sources, at a glance.
|
|
132
|
+
|
|
133
|
+
## Install & packaging
|
|
134
|
+
|
|
135
|
+
- **PyPI:** `pip install cleanix-cli` (or `pipx install cleanix-cli`).
|
|
136
|
+
- **Standalone binaries** are attached to each [GitHub Release] alongside a
|
|
137
|
+
`SHA256SUMS` file and keyless **build-provenance attestations** — verify a
|
|
138
|
+
download with `gh attestation verify <file> --repo CloudOpsWorld/cleanix-cli`.
|
|
139
|
+
- **Homebrew / AUR / Fedora** packaging lives under [`packaging/`](packaging/),
|
|
140
|
+
along with a `cleanix.1` **man page** generated from the CLI
|
|
141
|
+
(`python scripts/gen_manpage.py`).
|
|
142
|
+
|
|
143
|
+
[GitHub Release]: https://github.com/CloudOpsWorld/cleanix-cli/releases
|
|
144
|
+
|
|
145
|
+
## Container leftovers (Docker / Podman / nerdctl / crictl)
|
|
146
|
+
|
|
147
|
+
A *leftover* is anything the engine keeps that **no existing container
|
|
148
|
+
references** and can be regenerated. Each category is surfaced as its own item
|
|
149
|
+
whose estimated size matches exactly what pruning it reclaims — so the number
|
|
150
|
+
you see is the number you get (no more counting unused-but-tagged images or
|
|
151
|
+
volumes you never asked to touch):
|
|
152
|
+
|
|
153
|
+
- **Dangling (untagged) images** — `docker image prune -f`
|
|
154
|
+
- **Stopped containers** (writable layers) — `docker container prune -f`
|
|
155
|
+
- **Build cache** — `docker builder prune -f`
|
|
156
|
+
- **Unused networks** — `docker network prune -f`
|
|
157
|
+
|
|
158
|
+
Two categories stay **opt-in** because they can destroy real work:
|
|
159
|
+
|
|
160
|
+
- `docker_prune_all_images` — also remove *tagged* images not used by any
|
|
161
|
+
container (`image prune -a`); frees more but forces a re-pull next time.
|
|
162
|
+
- `docker_prune_volumes` — also remove unused anonymous volumes, which may hold
|
|
163
|
+
databases or other real data.
|
|
164
|
+
|
|
165
|
+
> On macOS, Docker Desktop stores everything in a VM disk image. Pruning frees
|
|
166
|
+
> space *inside* the VM; the host-side `Docker.raw` file may not shrink until
|
|
167
|
+
> Docker Desktop compacts it.
|
|
168
|
+
|
|
90
169
|
## Shell completion
|
|
91
170
|
|
|
92
171
|
```bash
|
|
@@ -162,7 +241,10 @@ sudo cleanix clean --only memory_macos --execute # macOS `purge`
|
|
|
162
241
|
that declares the platforms it applies to.
|
|
163
242
|
- **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
|
|
164
243
|
note) when you run unprivileged.
|
|
165
|
-
- **Scheduling.** Install a
|
|
244
|
+
- **Scheduling.** Install a periodic read-only scan that reports (and notifies)
|
|
245
|
+
on a daily/weekly/monthly cadence — a **systemd user timer** on Linux, a
|
|
246
|
+
**launchd LaunchAgent** on macOS, and a **cron job** on the BSDs (or any
|
|
247
|
+
system with `crontab` but no systemd). Same `cleanix schedule` command on all.
|
|
166
248
|
|
|
167
249
|
## Install
|
|
168
250
|
|
|
@@ -199,7 +281,8 @@ cleanix clean --execute --yes --only trash,pip_cache
|
|
|
199
281
|
# Emit the scan report as JSON (for tooling / notifications)
|
|
200
282
|
cleanix scan --json
|
|
201
283
|
|
|
202
|
-
# Install a
|
|
284
|
+
# Install a weekly read-only scan that notifies you
|
|
285
|
+
# (systemd timer on Linux/BSD, launchd agent on macOS)
|
|
203
286
|
cleanix schedule install --frequency weekly
|
|
204
287
|
|
|
205
288
|
# Check / remove the schedule
|
|
@@ -388,7 +471,9 @@ cleanix/
|
|
|
388
471
|
# BSD
|
|
389
472
|
bsd (freebsd pkg, distfiles/work dirs, pkgin)
|
|
390
473
|
scheduler/
|
|
391
|
-
|
|
474
|
+
__init__.py # backend() — picks systemd or launchd for the OS
|
|
475
|
+
systemd.py # install/uninstall/status of a user systemd timer (Linux/BSD)
|
|
476
|
+
launchd.py # install/uninstall/status of a launchd LaunchAgent (macOS)
|
|
392
477
|
```
|
|
393
478
|
|
|
394
479
|
To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Releasing cleanix-cli
|
|
2
|
+
|
|
3
|
+
Publishing is fully automated via GitHub Actions, modeled on a
|
|
4
|
+
push-to-`main`-triggers-release flow.
|
|
5
|
+
|
|
6
|
+
## Workflows
|
|
7
|
+
|
|
8
|
+
| Workflow | Trigger | What it does |
|
|
9
|
+
|----------|---------|--------------|
|
|
10
|
+
| `.github/workflows/ci.yml` | push / PR to `main`/`master` | Test matrix (Ubuntu + macOS × Python 3.9–3.13), advisory ruff lint & mypy |
|
|
11
|
+
| `.github/workflows/build.yml` | `workflow_call` / manual | Runs tests, builds standalone binaries (Linux + macOS via PyInstaller) and the wheel/sdist (`python -m build` + `twine check`) |
|
|
12
|
+
| `.github/workflows/release.yml` | push to `main`/`master` | Detects a new version, tags it, builds artifacts, creates a GitHub Release, and publishes to PyPI |
|
|
13
|
+
|
|
14
|
+
## How a release happens
|
|
15
|
+
|
|
16
|
+
1. Bump the version in **both** `pyproject.toml` and `cleanix/__init__.py`
|
|
17
|
+
(the release workflow fails if they disagree).
|
|
18
|
+
2. Commit and push to `main`.
|
|
19
|
+
3. `release.yml` will:
|
|
20
|
+
- see the version has no matching `vX.Y.Z` git tag,
|
|
21
|
+
- create and push that tag,
|
|
22
|
+
- build binaries + wheel/sdist,
|
|
23
|
+
- create a GitHub Release with the binaries and package attached,
|
|
24
|
+
- publish the wheel/sdist to PyPI.
|
|
25
|
+
|
|
26
|
+
If the tag already exists, the release is skipped — so pushing unrelated commits
|
|
27
|
+
never re-releases.
|
|
28
|
+
|
|
29
|
+
## One-time PyPI setup (Trusted Publishing — recommended)
|
|
30
|
+
|
|
31
|
+
No API token required. On PyPI:
|
|
32
|
+
|
|
33
|
+
1. Create the project owner/account, then go to **PyPI → Your projects →
|
|
34
|
+
Publishing → Add a new pending publisher** with:
|
|
35
|
+
- Owner: your GitHub org/user
|
|
36
|
+
- Repository: `cleanix-cli`
|
|
37
|
+
- Workflow name: `release.yml`
|
|
38
|
+
- Environment: `pypi`
|
|
39
|
+
2. In the GitHub repo, create an **Environment** named `pypi`
|
|
40
|
+
(Settings → Environments) — optionally add required reviewers for a manual
|
|
41
|
+
approval gate before publish.
|
|
42
|
+
|
|
43
|
+
That's it: `release.yml` requests an OIDC token (`id-token: write`) and PyPI
|
|
44
|
+
trusts it.
|
|
45
|
+
|
|
46
|
+
### Alternative: API token
|
|
47
|
+
|
|
48
|
+
If you prefer a token, add a repository secret `PYPI_API_TOKEN` and uncomment the
|
|
49
|
+
`password:` line in the `publish-pypi` job of `release.yml`.
|
|
50
|
+
|
|
51
|
+
## Testing the pipeline first
|
|
52
|
+
|
|
53
|
+
- Run **Build** manually (Actions → Build → Run workflow) to confirm binaries and
|
|
54
|
+
the package build without cutting a release.
|
|
55
|
+
- Optionally point at **TestPyPI** first by adding `repository-url:
|
|
56
|
+
https://test.pypi.org/legacy/` to the publish step.
|
|
57
|
+
|
|
58
|
+
## Local dry run
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install build twine
|
|
62
|
+
python -m build
|
|
63
|
+
twine check dist/*
|
|
64
|
+
```
|
|
@@ -25,6 +25,13 @@ from cleanix.cleaners.dev_caches import DevCacheCleaner
|
|
|
25
25
|
from cleanix.cleaners.pip_cache import PipCacheCleaner
|
|
26
26
|
from cleanix.cleaners.npm_cache import NpmCacheCleaner
|
|
27
27
|
from cleanix.cleaners.containers import DockerCleaner, PodmanCleaner
|
|
28
|
+
from cleanix.cleaners.containerd import CrictlCleaner, NerdctlCleaner
|
|
29
|
+
from cleanix.cleaners.toolchains import ToolchainVersionCleaner
|
|
30
|
+
from cleanix.cleaners.project_cruft import ProjectCruftCleaner
|
|
31
|
+
from cleanix.cleaners.big_files import BigFileReporter
|
|
32
|
+
from cleanix.cleaners.downloads import DownloadsReporter
|
|
33
|
+
from cleanix.cleaners.browser_profiles import BrowserProfileReporter
|
|
34
|
+
from cleanix.cleaners.duplicates import DuplicateFileReporter
|
|
28
35
|
|
|
29
36
|
# Logs / crashes
|
|
30
37
|
from cleanix.cleaners.logs import JournalCleaner, RotatedLogCleaner
|
|
@@ -171,6 +178,10 @@ ALL_CLEANERS: List[Type[Cleaner]] = [
|
|
|
171
178
|
NpmCacheCleaner,
|
|
172
179
|
DockerCleaner,
|
|
173
180
|
PodmanCleaner,
|
|
181
|
+
NerdctlCleaner,
|
|
182
|
+
CrictlCleaner,
|
|
183
|
+
# Language / toolchain versions
|
|
184
|
+
ToolchainVersionCleaner,
|
|
174
185
|
# Logs & crashes
|
|
175
186
|
RotatedLogCleaner,
|
|
176
187
|
JournalCleaner,
|
|
@@ -247,6 +258,11 @@ ALL_CLEANERS: List[Type[Cleaner]] = [
|
|
|
247
258
|
SnapshotReporter,
|
|
248
259
|
TimeMachineReporter,
|
|
249
260
|
DeviceBackupReporter,
|
|
261
|
+
ProjectCruftCleaner,
|
|
262
|
+
BigFileReporter,
|
|
263
|
+
DownloadsReporter,
|
|
264
|
+
BrowserProfileReporter,
|
|
265
|
+
DuplicateFileReporter,
|
|
250
266
|
# macOS extras
|
|
251
267
|
MacExtraCachesCleaner,
|
|
252
268
|
MacContainerCacheCleaner,
|
|
@@ -25,6 +25,20 @@ SCOPE_USER = "user"
|
|
|
25
25
|
SCOPE_SYSTEM = "system"
|
|
26
26
|
|
|
27
27
|
|
|
28
|
+
def _path_present(p: Path) -> bool:
|
|
29
|
+
"""True if ``p`` exists (or is a dangling symlink), never raising.
|
|
30
|
+
|
|
31
|
+
``Path.exists()`` does *not* swallow ``EPERM`` — on macOS a SIP-protected
|
|
32
|
+
entry under ``/Library/Caches`` raises ``PermissionError`` — so a bare
|
|
33
|
+
``p.exists()`` in a cleaner would abort the whole scan. We treat any
|
|
34
|
+
unreadable path as "not present" (we couldn't size or remove it anyway).
|
|
35
|
+
"""
|
|
36
|
+
try:
|
|
37
|
+
return p.exists() or p.is_symlink()
|
|
38
|
+
except OSError:
|
|
39
|
+
return False
|
|
40
|
+
|
|
41
|
+
|
|
28
42
|
class Cleaner(abc.ABC):
|
|
29
43
|
"""Base class for all cleaners.
|
|
30
44
|
|
|
@@ -76,7 +90,7 @@ class Cleaner(abc.ABC):
|
|
|
76
90
|
) -> Optional[CleanableItem]:
|
|
77
91
|
"""Build a PATH item for ``path`` if it exists and is non-empty."""
|
|
78
92
|
p = Path(path)
|
|
79
|
-
if not
|
|
93
|
+
if not _path_present(p):
|
|
80
94
|
return None
|
|
81
95
|
size = path_size(p)
|
|
82
96
|
return CleanableItem(
|
|
@@ -100,7 +114,7 @@ class Cleaner(abc.ABC):
|
|
|
100
114
|
) -> Optional[CleanableItem]:
|
|
101
115
|
"""Build a *report-only* PATH item (surfaced with size, never deleted)."""
|
|
102
116
|
p = Path(path)
|
|
103
|
-
if not
|
|
117
|
+
if not _path_present(p):
|
|
104
118
|
return None
|
|
105
119
|
return CleanableItem(
|
|
106
120
|
cleaner_id=self.id,
|
|
@@ -156,18 +170,28 @@ class Cleaner(abc.ABC):
|
|
|
156
170
|
return report
|
|
157
171
|
|
|
158
172
|
def _scan_all_users(self) -> List[CleanableItem]:
|
|
159
|
-
"""Run a per-user cleaner once for each target user, de-duplicating
|
|
160
|
-
|
|
173
|
+
"""Run a per-user cleaner once for each target user, de-duplicating so
|
|
174
|
+
shared directories and identical commands are never offered twice.
|
|
175
|
+
|
|
176
|
+
Command items are keyed by their argv: a per-user cleaner that yields a
|
|
177
|
+
fixed command (e.g. ``brew cleanup``) would otherwise appear once per
|
|
178
|
+
target user when running as root, yet the engine runs it only once."""
|
|
161
179
|
items: List[CleanableItem] = []
|
|
162
|
-
|
|
180
|
+
seen_paths: set = set()
|
|
181
|
+
seen_commands: set = set()
|
|
163
182
|
for user in get_target_users():
|
|
164
183
|
with use_user(user):
|
|
165
184
|
for item in self.find_items():
|
|
166
185
|
if item is None:
|
|
167
186
|
continue
|
|
168
187
|
if item.path is not None:
|
|
169
|
-
if item.path in
|
|
188
|
+
if item.path in seen_paths:
|
|
189
|
+
continue
|
|
190
|
+
seen_paths.add(item.path)
|
|
191
|
+
elif item.command is not None:
|
|
192
|
+
key = tuple(item.command)
|
|
193
|
+
if key in seen_commands:
|
|
170
194
|
continue
|
|
171
|
-
|
|
195
|
+
seen_commands.add(key)
|
|
172
196
|
items.append(item)
|
|
173
197
|
return items
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""Large-file finder (report-only).
|
|
2
|
+
|
|
3
|
+
A user who has filled their disk usually wants to *see* what is eating the
|
|
4
|
+
space, not have cleanix guess which giant files are junk — a 40 GiB video or VM
|
|
5
|
+
image may be exactly what they wanted to keep. So this cleaner never deletes
|
|
6
|
+
anything: it walks the home tree, surfaces the biggest files (with sizes and a
|
|
7
|
+
manual removal hint), and leaves the decision to the human.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import heapq
|
|
13
|
+
import os
|
|
14
|
+
import stat
|
|
15
|
+
from typing import Iterable, List, Tuple
|
|
16
|
+
|
|
17
|
+
from cleanix.cleaners.base import Cleaner
|
|
18
|
+
from cleanix.core.models import CleanableItem
|
|
19
|
+
from cleanix.core.platform import ALL
|
|
20
|
+
from cleanix.core.utils import (
|
|
21
|
+
_allocated_bytes,
|
|
22
|
+
home,
|
|
23
|
+
human_size,
|
|
24
|
+
modified_within,
|
|
25
|
+
walk_pruned,
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
# Leave anything touched within the last few minutes alone: a very recent mtime
|
|
29
|
+
# suggests the file is being actively written (a download in progress, a render
|
|
30
|
+
# still spooling), and its size is not yet meaningful.
|
|
31
|
+
_IN_USE_MINUTES = 5.0
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class BigFileReporter(Cleaner):
|
|
35
|
+
id = "big_files"
|
|
36
|
+
name = "Large files"
|
|
37
|
+
description = "Biggest files in your home directory (report only)"
|
|
38
|
+
requires_root = False
|
|
39
|
+
platforms = (ALL,)
|
|
40
|
+
|
|
41
|
+
def find_items(self) -> Iterable[CleanableItem]:
|
|
42
|
+
min_bytes = int(
|
|
43
|
+
getattr(self.config, "big_file_min_size_mb", 500.0) * 1024 * 1024
|
|
44
|
+
)
|
|
45
|
+
top_n = int(getattr(self.config, "big_files_top_n", 20))
|
|
46
|
+
if top_n <= 0:
|
|
47
|
+
return
|
|
48
|
+
|
|
49
|
+
# Keep a running min-heap of the top-N largest files seen so far. Each
|
|
50
|
+
# entry is (size, path); the smallest sits at heap[0] and is evicted
|
|
51
|
+
# once the heap is full and a bigger file arrives.
|
|
52
|
+
heap: List[Tuple[int, str]] = []
|
|
53
|
+
|
|
54
|
+
for dirpath, _dirnames, filenames in walk_pruned(home()):
|
|
55
|
+
for name in filenames:
|
|
56
|
+
fpath = os.path.join(dirpath, name)
|
|
57
|
+
try:
|
|
58
|
+
st = os.lstat(fpath)
|
|
59
|
+
except OSError:
|
|
60
|
+
continue
|
|
61
|
+
# Files only, never symlinks (walk_pruned already avoids
|
|
62
|
+
# descending through symlinked dirs).
|
|
63
|
+
if not stat.S_ISREG(st.st_mode):
|
|
64
|
+
continue
|
|
65
|
+
size = _allocated_bytes(st)
|
|
66
|
+
if size < min_bytes:
|
|
67
|
+
continue
|
|
68
|
+
if modified_within(fpath, _IN_USE_MINUTES):
|
|
69
|
+
continue
|
|
70
|
+
if len(heap) < top_n:
|
|
71
|
+
heapq.heappush(heap, (size, fpath))
|
|
72
|
+
elif size > heap[0][0]:
|
|
73
|
+
heapq.heapreplace(heap, (size, fpath))
|
|
74
|
+
|
|
75
|
+
# Emit largest-first.
|
|
76
|
+
for size, fpath in sorted(heap, key=lambda t: t[0], reverse=True):
|
|
77
|
+
item = self.report_item(
|
|
78
|
+
fpath,
|
|
79
|
+
f"Large file: {os.path.basename(fpath)} ({human_size(size)})",
|
|
80
|
+
hint="review and remove manually if no longer needed: rm <path>",
|
|
81
|
+
)
|
|
82
|
+
if item:
|
|
83
|
+
yield item
|