Warden is a command-line file organization tool that automatically structures directories using customizable rules features a transaction-based Undo System to reverse operations.
You do not need to install the .NET SDK to use this. You can download the standalone application for Mac (Silicon/M-Series), Windows, or Linux.
- Download the latest release here
- Open your Terminal and go to your downloads:
cd ~/Downloads- Make the file executable (Mac/Linux only) and run it:
chmod +x warden
./warden --helpPro Tip: Move the executable to your
/usr/local/binfolder to runwardenfrom any directory!
Warden uses intuitive verbs to manage your files. Here are the core commands:
| Command | Description |
|---|---|
probe [path] |
Acts as a dry run. Safely visualizes how files will be organized without actually moving them. Takes all the same flags as sort. |
sort [path] |
Organize files in the target directory into subfolders. Defaults to sorting by category (e.g., /Images, /Docs). |
undo |
Reverses the last operation. Moves files back to their original locations. |
undo --force |
Reverses the last operation but skips files that are missing/deleted without crashing. |
audit |
View the history of file movements and batch operations. |
help |
Show the list of available commands and flags. |
Sort a messy downloads folder:
warden sort ~/DownloadsOops! Didn't mean to do that? Undo it:
warden undoForce an undo even if files are missing (skips errors):
warden undo --force- Smart Organization: Automatically detects file types (Images, Documents, Archives, Code) and moves them into clean, labeled subdirectories.
- Transaction-Based Undo: Every sort operation records a unique "Batch ID". The
undocommand uses this to strictly reverse only the most recent action. - Audit Logging: Maintains a local JSON ledger (
warden_log.json) of every file moved, including timestamps and original paths. - Absolute Path Tracking: Logs store absolute paths, meaning you can run the
undocommand from anywhere in your terminal, not just the target folder.
Warden is built with a "Safety First" philosophy:
- Non-Destructive: Warden moves files; it never deletes them.
- Conflict Resolution: If a file with the same name exists in the destination, Warden handles it gracefully rather than overwriting your data.
- Crash-Proof Undo: The Undo system performs "Pre-Flight Checks". If you manually deleted a file after sorting it, the
undocommand detects the "Ghost File," logs a warning, and skips it instead of crashing.
The project follows Clean Architecture principles, implemented as layered modules inside the main CLI project to ensure separation of concerns and testability.
- Presentation (Warden.CLI): Handles user input via
Spectre.Console. Commands (SortCommand,UndoCommand) act as controllers that delegate work to the Application layer. - Application: Contains the business orchestration.
FileOrganizerService: Coordinates file processing.AuditService: Manages transaction logs for the Audit and Undo system.
- Domain: Encapsulates core logic using the Strategy Pattern.
ISortRule: Interface implemented by specific rules (ExtensionSortRule,CategorySortRule) to determine file organization logic dynamically.
- Infrastructure: Implements system-level operations.
PhysicalFileSystem: WrapsSystem.IOto allow for safe disk operations and mockability during testing.
- Dependency Injection: Uses
Microsoft.Extensions.DependencyInjectionbridged withSpectre.Consolefor modular service management.
A separate test project containing:
- Unit Tests: Verify business logic in isolation using mocks.
- Integration Tests: Validate real-world behavior using temporary test directories.
- Language: C# (.NET 8.0)
- CLI Framework: System.CommandLine
- UI/UX: Spectre.Console (Rich text, Tables)
- Dependency Injection: Microsoft.Extensions.DependencyInjection
- Testing: xUnit, Moq