diskr

diskr is a lightweight terminal file explorer and disk/storage manager for macOS.

It shows a navigable file list, recursive directory sizes, allocated-vs-apparent size details, disk usage gauges, hidden-file toggling, sorting, largest-file reports, package/dependency inspection, reclaimable-space detection, scan baselines with diffing, and safe deletion through the macOS Trash. The disk and packages panes are selectable, so you can jump directly to mounted volumes and package paths.

Install

From crates.io:

cargo install diskr

From a local checkout:

cargo install --path .

Then run:

diskr

To start in a specific directory:

diskr ~/Downloads

If the path starts with -, use the conventional argument separator:

diskr -- -scratch

To print the largest files under a directory:

diskr --top 20 ~/Downloads

To find reclaimable space (developer/system caches and repeated build artifacts), each tagged with how safe it is to delete:

diskr --reclaim ~

To record a scan baseline and later see what changed:

diskr --save ~/Downloads
# ...time passes...
diskr --diff ~/Downloads

To explain APFS/free-space mismatches and local snapshots:

diskr --space ~

For scripts and reports:

diskr --top 20 --json ~/Downloads
diskr --reclaim --json ~
diskr --diff --json ~/Downloads
diskr --space --json ~
diskr --packages --json ~

To preview a Time Machine local snapshot thinning request:

diskr --thin-snapshots 10G ~

To execute it, add the explicit confirmation flag:

diskr --thin-snapshots 10G --yes ~

Keys

Notes

diskr is macOS-only. Directory sizing uses getattrlistbulk(2) for fast local scans. The TUI sorts by allocated on-disk size and shows apparent size in the status line when it differs. The reclaimable-space report classifies each item as safe, regenerable, or risky to delete, and never deletes anything itself. Scan baselines are stored under ~/Library/Application Support/diskr/ and --diff reports per-child growth without changing the baseline. The APFS space report uses statfs(2), diskutil info -plist, and tmutil listlocalsnapshots to surface free-space gaps and local snapshots. Deletion uses the macOS Trash rather than permanent removal.

Planned differentiators and cleanup ideas live in ROADMAP.md.

The minimum supported Rust version is 1.88.0.

Release Checks

cargo fmt -- --check
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked
cargo package --locked

Releases

Releases are automated through GitHub Actions and appear in the GitHub Releases tab.

One-time setup:

1. Add a repository secret named CARGO_REGISTRY_TOKEN with a crates.io API token that has publish access for diskr.

Release flow:

1. Update Cargo.toml to the new crate version.
2. Refresh Cargo.lock if needed and push the version bump to main.
3. Create and push a matching tag like v0.1.11.

git tag -a v0.1.11 -m "v0.1.11"
git push origin v0.1.11

When that tag is pushed, the Release workflow will:

1. Verify the tag matches the crate version.
2. Verify the tagged commit is reachable from main.
3. Run the full release validation set.
4. Publish the crate to crates.io if that version is not already published.
5. Create or update the matching GitHub release with generated notes.