Point chest at cluttered directories and watch them organize into structured compartments. Equipped with interactive dry-runs, instant rollbacks, and offline SQLite storage intelligence.
$ chest sort ~/Downloads -p downloads --dry-runCHEST PLAN # 3 moves, 0 collisions detected anime_ep01.mkv → Downloads/Videos/ profile_shot.png → Downloads/Images/ q3_financials.pdf → Downloads/Documents/3 files prepared to move. No changes made (dry run).Run with -y or omit --dry-run to apply.
Every operation is predictable. No hidden telemetry, no destructive overwrites, and no cloud latency.
Every transaction is logged in an undo database and recorded honestly — Complete, Partial or Failed, never a lie. Run chest undo to rollback the latest run or revert a specific operation by ID at any time.
Utilizes fastwalk parallel concurrency and fzf/src/algo scoring. Traverses 100,000+ files across all CPU cores, hash in parallel, and batch DB writes — with live in-place progress bars while you wait.
Watches folders via fsnotify with a 500ms debounce guard. Add --initial to sort what's already there before watching, and get instant feedback when folders are created or removed.
Pure-Go embedded SQLite stores file metadata and incremental SHA-256 hashes locally. Incremental indexing skips unchanged files on repeat runs, enabling instant duplicate checks and storage breakdowns.
Extensible via HashiCorp go-plugin over RPC. Community plugins execute in isolated subprocesses so third-party code cannot crash your core workflow.
Two files resolving to the same destination can never destroy each other: the second is auto-renamed (photo (1).jpg), case-normalized across platforms, and every conflict is surfaced in the dry-run CONFLICTS block. Add --hash-collisions to hash only the conflict set; add --keep-identical when byte-identical copies should also be retained as (1) instead of skipped.
Blocks destructive operations on OS-critical directories (C:\Windows, /usr, drive roots) by default. Override with --allow-system and interactive confirmation.
Each verb is purpose-built with clean Unix ergonomics and structured JSON export options.
Turns a plan into a reviewable JSON artifact without touching disk. chest plan apply executes it after re-validating every source — all-or-nothing — and records history so undo reverts it. chest plan diff compares two plans.
Mark a named point in history, then revert everything after it as one atomic batch with chest undo --to. Selective undo --file reverts a single file and leaves the rest of the run undoable. chest history --prune bounds the log.
Hash a folder into a reproducible SHA-256 inventory, then prove it has not drifted — reporting OK, MODIFIED, MISSING and ADDED. Exits 4 on any drift so scripts can detect it. Both commands are read-only.
Normalize messy filenames in place from a template, using the same date machinery as sort. Dry-run, collision policy, history and full undo — and it never moves a file between folders.
doctor is one read-only health check over index freshness, un-undoable history, unreadable folders, broken symlinks, schedules and rules. tree draws a folder as a box-drawing tree with rolled-up sizes.
Explain which rule matches a given file, why it matched and where it would go. rule check validates syntax; rule eval validates behaviour. Read-only.
Categorizes target folder by preset, extension, or custom logic expressions with dry-run support. Rules persist in chest.toml (flags > --rule > project > user > preset), can match embedded metadata (camera=, artist=, codec=), and --hash-collisions --keep-identical preserves identical conflict participants under safe (1) names.
Build a rule set interactively. preview re-plans from your current rules after every edit and renders the same dry-run report as sort --dry-run — it never touches disk. Only apply moves files, recorded in history and reversible with chest undo. Save reusable rule sets to ~/.chest/templates.
Fuzzy filename scoring with in-file grep (line numbers + snippets). Combine category, extension, size, and date filters — or emit JSON for scripts.
Continuous background listener sorting newly downloaded files as soon as they settle. Plugin classifiers and custom rules apply here too, and each debounce window is recorded as a single undoable history entry.
Reverts file transfers by operation ID or rolls back the latest batch run instantly. Runs are recorded honestly — Complete, Partial or Failed — and undo validates the whole batch before restoring anything.
Finds exact byte-for-byte duplicate files across paths using incremental parallel SHA-256 hashes, with --except to skip noisy directories (excluded rows are also purged from the cache).
Compares Ookla and Cloudflare download, upload, ping, and jitter results. Transfer rows use a 16-cell diamond gauge with ◆ filled and ◇ empty cells. Pass --disk to run disk benchmark mode — sequential read/write MB/s plus random 4K IOPS, reported in a dedicated -- Disk section (size the test file with --disk-size, target another drive with --disk-path).
Generates storage breakdowns, largest-file rankings (absolute paths), and stale-item diagnostics. Scoped runs auto-refresh; bare runs repopulate an empty cache; --refresh forces a re-scan + purge. Reports export with --json, --csv or --out.
Periodic organizing without a foreground process — registered as a crontab entry on Linux/macOS or a scheduled task on Windows. Manage jobs with list, remove and run-now.
Validates the rule set for a directory — flags, presets and any chest.toml — without scanning or moving files. Catches invalid size values and unsupported field/operator combinations that would otherwise be silently ignored.
Installs shell tab-completion for bash, zsh, and fish in one command — auto-detects your shell and wires it into your profile.