cargo-cleanme
Find reclaimable Cargo build artifacts and clean them through Cargo — never by deleting directories.
$ cargo cleanme --dry-run
combined roots /home/you/Projects
Cleaned …/demo-app [private] output …/demo-app/target before 8.78 MiB — simulation: no `cargo clean` command was invoked
simulation: 1 would-clean, 0 skipped, 0 failed; estimated would-clean 8.78 MiB; no `cargo clean` command was invoked; 0 filesystem diagnostics
cargo cleanme with no arguments cleans. Every deletion is delegated to
Cargo and gated on a fresh complete ownership proof; --dry-run runs the whole
decision path and removes nothing. Scanning is the separate, always read-only
operation.
Install
Do not install 0.2.0. It is yanked, and two destructive defects were found in it after release:
--dry-run clean ROOT— the spelling Cargo itself passes — fell through to a real cleanup, and a workspace whose declared output directory contained another project's source tree was cleaned asprivate, deleting that neighbour's files. Both report success and exit 0. See docs/TROUBLESHOOTING.md.
Or install a verified prebuilt binary from a GitHub release:
|
Installing the package is enough for Cargo to expose the external subcommand,
so cargo cleanme … and cargo-cleanme … are equivalent.
→ docs/INSTALLING.md for pinned versions, Windows, destination and PATH handling, and what the installer refuses to do.
Prebuilt release targets
release/eggpack/distribution.toml is the
single authority for this matrix and the asset names; it is not maintained by
hand.
| Target triple | Install name |
|---|---|
x86_64-unknown-linux-gnu |
cargo-cleanme |
aarch64-unknown-linux-gnu |
cargo-cleanme |
x86_64-apple-darwin |
cargo-cleanme |
aarch64-apple-darwin |
cargo-cleanme |
x86_64-pc-windows-msvc |
cargo-cleanme.exe |
Each asset ships a .sha256 sidecar. armv7-unknown-linux-gnueabihf is a
recognized host with no prebuilt binary: it is Cargo-install-only, as are
musl, Windows ARM64/ARMv7, and any unlisted OS or architecture.
The Linux targets are built against a glibc 2.17 floor, but that floor is not yet claimed as support — no runtime evidence for the exact release bytes exists yet, so nothing here advertises a minimum glibc. See the ABI floor section.
Quickstart
The surface
| Command | What it does | Runs cargo clean? |
|---|---|---|
cargo cleanme |
Routine cleanup over the maintenance scope | yes |
cargo cleanme --dry-run |
Simulation: every gate runs, nothing is removed | never, not even preview |
cargo cleanme scan |
Full read-only reconciliation | never |
cargo cleanme scan --known |
Routine read-only inventory | never |
cargo cleanme scan ROOT |
One bounded read-only scope | never |
cargo cleanme clean ROOT |
Cleanup of one explicit root (Execute by default) | yes |
cargo cleanme clean --known / --full |
Advanced orchestration | yes |
cargo cleanme clean … --cargo-preview |
Cargo's own clean --dry-run --verbose, after the same proof |
yes, as a dry run |
The maintenance scope is a configured legacy scan.root when one is set
(exclusive, explicit), otherwise bounded seed roots plus active learned roots.
Rootless scan is always Full and ignores scan.root, so configuration can
never silently narrow the reconciliation command.
Scan output
Scan finds inactive output. It never deletes.
$ cargo cleanme scan ~/projects
8.78 MiB /home/you/projects/demo-app/target [private]
8.78 MiB inventory estimate across 1 inactive Cargo output groups
A group is reported as [private] only when cargo-cleanme can prove it
owns those bytes exclusively. [shared], [external-unproven], and
[uncertain] groups are inventory only and are never cleaned.
If
scanreports 0 groups on a project you just built, that is the safety guard working. Anything whose source changed within the last 300 seconds is active and protected. Backdate the sources, or wait, and it will appear.
Clean modes
Three modes, and dry-run means one specific thing:
| Flag | Mode | Runs cargo clean? |
|---|---|---|
| (none) | Execute | yes |
--dry-run |
Simulation | never, not even preview |
--cargo-preview |
Cargo preview | yes, as cargo clean --dry-run --verbose |
$ cargo cleanme clean ~/projects/demo-app --cargo-preview --no-progress
combined scope: 1 root(s) […], 1 manifest(s), 1 resolved workspace(s), 1 CleanupUnit(s), 0 unresolved ownership participant(s)
Previewed …/demo-app [private] output …/demo-app/target before 8.78 MiB — … /warning: no files deleted due to --dry-run/
cargo preview: 1 previewed, 0 skipped, 0 failed; pre-clean estimate 8.78 MiB; no cleanup executed; 0 filesystem diagnostics
$ cargo cleanme clean ~/projects/demo-app --dry-run --no-progress
Simulated …/demo-app [private] output …/demo-app/target before 8.78 MiB — simulation: no `cargo clean` command was invoked
simulation: 1 would-clean, 0 skipped, 0 failed; estimated would-clean 8.78 MiB; no `cargo clean` command was invoked; 0 filesystem diagnostics
--dry-run still runs discovery, resolution, ownership proof, authorization,
sizing, revalidation, and reporting — it differs only in that it stops before
spawning anything. That makes it the mode to use when testing a change to the
gates. --cargo-preview is the lower-level debugging view that hands the
mutation decision to Cargo itself.
Real cleanup, made explicit:
$ cargo cleanme clean ~/projects/demo-app --no-progress
Cleaned …/demo-app [private] output …/demo-app/target before 8.78 MiB after 0.00 B observed decrease 8.78 MiB — Removed 22 files, 8.7MiB total
cleanup: 1 cleaned, 0 skipped, 0 failed; pre-clean estimate 8.78 MiB, post-clean measured 0.00 B, observed decrease 8.78 MiB; 0 filesystem diagnostics
Every candidate must prove exclusive ownership of its bytes, and the proof is
repeated immediately before each cargo clean. If any manifest under the
scope cannot be resolved, no cleanup command runs at all and you get a
typed block instead:
$ cargo cleanme --format json; echo "exit $?"
{
"scope_blocked": true,
"scope_reason": "cleanup ownership could not be proven: 1 discovered Cargo manifest did not resolve; no cleanup commands were run",
"unresolved_participants": [
{ "manifest": "…/broken/Cargo.toml", "stage": "locate", "reason": "cargo locate-project failed" }
],
"units_considered": 0
}
exit 1
→ docs/USAGE.md for the full safety model, and docs/USAGE.md for exit codes.
Unattended
$ cargo cleanme --format log
cargo-cleanme op=clean status=ok scope=routine mode=execute cleaned=7 skipped=3 failed=0 reclaimed_bytes=19778387968 diagnostics=0
log exists for schedulers that keep a short history pane: one ASCII line, at
most 384 bytes, no paths, no progress output. Anything parsing output should
parse --format json, which remains the complete versioned contract.
→ docs/AUTOMATION.md for the field list, a worked greggd configuration, scheduler-neutral alternatives, and exit-code triage.
Config
Created on first use, never overwritten, and validated after every edit.
[]
= 300 # protect anything touched in the last 5 minutes
= [] # literal path segments
= [] # literal relative paths, NOT globs
= 30
[]
= [] # authorizes a location; never grants ownership
[]
= 0
# min_inactive_seconds = 2592000
= []
= []
allowed_output_roots can widen where cleanup is permitted. It can never
turn a shared or unproven group into a cleanable one.
Common flags
| Flag | Effect |
|---|---|
--format human|json|log |
interactive detail; one schema-1 JSON document; or one bounded ASCII line for an unattended scheduler |
--dry-run |
simulate: the whole decision path, zero cargo clean processes |
--no-progress |
disable the transient TTY UI (stderr only) |
--stats |
counters and phase timings on stderr; stdout stays byte-identical |
--config PATH |
use a specific config.toml |
--min-reclaimable-bytes N |
only clean units above this measured size (clean) |
--older-than SECONDS |
extra quiet-age requirement; never replaces the recency guard (clean) |
--known / --full |
Routine roots / Full reconciliation, on clean and scan |
--dry-run, --cargo-preview, and --yes conflict pairwise on purpose.
Upgrading from 0.1.x
Bare cargo cleanme changed from a read-only Routine scan to Routine cleanup,
and --dry-run changed from Cargo preview to simulation.
| 0.1.x | Now | Meaning |
|---|---|---|
cargo cleanme |
cargo cleanme scan --known |
same old read-only Routine inventory |
cargo cleanme scan --full |
cargo cleanme scan |
Full reconciliation |
cargo cleanme clean R --dry-run |
cargo cleanme clean R --cargo-preview |
same Cargo preview |
cargo cleanme clean R --dryrun |
cargo cleanme clean R --dry-run |
same simulation |
cargo cleanme clean R --yes |
cargo cleanme clean R |
Execute is now the default |
--dryrun and --yes still work on clean as hidden aliases for the
pre-1.0 migration period. They print nothing.
Exit codes
| Code | Meaning |
|---|---|
0 |
the operation completed, including safe per-unit skips |
1 |
scope incomplete, ownership unproven, or an operation failed |
2 |
invocation or configuration error, before a report could be formed |
1 on clean with scope_blocked: true is a success-shaped result with a
typed blocker, not a crash. Read the block.
Keep it current
update refuses to touch a Cargo-managed install and will not downgrade or
accept a prerelease. → docs/UPDATE.md.
Documentation
| Document | What it covers |
|---|---|
| docs/USAGE.md | full command reference, discovery model, cleanup safety model, config, JSON schema, selectors |
| docs/AUTOMATION.md | bounded log output, scheduler integration, unattended limits and exit-code triage |
| docs/INSTALLING.md | install paths, prebuilt targets, destinations, uninstalling |
| docs/UPDATE.md | self-update rules, what it refuses, integrity vs authenticity |
| docs/TROUBLESHOOTING.md | known defects by version, installer and updater failure modes |
| docs/RELEASING.md | maintainer release checklist |
| CHANGELOG.md | released changes, including known defects per version |
For contributors and coding agents: AGENTS.md and architecture/overview.md.
Support and policy
- MSRV 1.89. Prebuilt for the five targets in Prebuilt release targets. Musl, Windows ARM64, and ARMv7 are Cargo-only.
- Integrity, not authenticity. Published
.sha256files prove the bytes match what the release built. There is no signature and no authenticity claim. macOS binaries are unsigned and not notarized — Gatekeeper will refuse a downloaded binary on first launch. - No glibc floor is advertised yet. See the ABI floor note.
- Pre-1.0. Breaking changes to the CLI, JSON schema, or asset names can
occur in any
0.xrelease. Read CHANGELOG.md before upgrading.1.0.0is when those are declared stable. - Library API is not stable. The crate ships a library because the tests and tooling need one. The CLI, the versioned JSON schema, and the release-asset names are the stable surfaces.
- cargo-cleanme never installs a service or daemon, and never modifies your
PATH.
Uninstall
License
MIT or Apache-2.0, at your option.