noentropy/docs/USAGE.md

Usage Guide

This guide covers all the ways you can use NoEntropy to organize your files.

Quick Start

The simplest way to organize your downloads folder:

./noentropy

This will:

1. Scan your configured downloads folder
2. Ask Gemini AI to categorize files
3. Show you a preview of the organization plan
4. Ask for confirmation before moving files
5. Execute the organization if you approve

Command-Line Options

NoEntropy supports several command-line flags to customize its behavior:

Option	Short	Default	Description
[PATH]	-	-	Path to organize (defaults to configured download folder)
--dry-run	-d	false	Preview changes without moving files
--max-concurrent	-m	5	Maximum concurrent API requests
--recursive	-	false	Recursively search files in subdirectories
--undo	-	false	Undo the last file organization
--change-key	-	false	Change Gemini API key
--help	-h	-	Show help message

Usage Examples

Custom Path Organization

Organize any directory instead of the configured download folder:

./noentropy /path/to/folder

Usage with current directory:

./noentropy .

Usage with relative path:

./noentropy ./subfolder

When to use:

• Organize directories other than your Downloads folder
• Quickly organize the current working directory
• Test organization on specific folders before applying to Downloads
• Organize project directories, documents, or other file collections

Features:

• Path validation ensures the directory exists and is accessible
• Path normalization resolves ., .., and symlinks for consistency
• Works with all other options (--dry-run, --recursive, etc.)

Dry-Run Mode

Preview what NoEntropy would do without actually moving any files:

./noentropy --dry-run

When to use:

• First time using NoEntropy
• Testing new custom categories
• Checking how specific files will be categorized
• Verifying organization plan before execution

Example output:

Found 47 files. Asking Gemini to organize...
Gemini Plan received! Performing deep inspection...
Deep inspection complete!

--- EXECUTION PLAN (DRY RUN) ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: setup.exe -> Installers/
Plan: notes.txt -> Documents/Notes/
Plan: config.yaml -> Code/Config/

DRY RUN - No files were moved

Recursive Mode

Organize files in subdirectories recursively:

./noentropy --recursive

What it does:

• Scans all subdirectories within your download folder
• Organizes files from the entire directory tree
• Maintains relative folder structure when creating categories

Use case: When you have downloads organized in subfolders that you want to consolidate into proper categories.

Custom Concurrency

Adjust the number of concurrent API calls (default: 5):

./noentropy --max-concurrent 10

When to adjust:

• Increase (10-15): If you have fast internet and many files
• Decrease (1-3): If you're hitting rate limits or have slow internet
• Keep default (5): Works well for most use cases

Combined Options

You can combine multiple options:

./noentropy --dry-run --max-concurrent 3

./noentropy --recursive --max-concurrent 10

Custom path combinations:

# Preview organization of current directory
./noentropy . --dry-run

# Organize specific folder recursively
./noentropy /path/to/folder --recursive

# Organize current directory with custom concurrency
./noentropy . --max-concurrent 10

# Undo organization in specific directory
./noentropy /path/to/folder --undo

Undo Operations

NoEntropy tracks all file moves and allows you to undo them.

Basic Undo

Revert the last file organization:

./noentropy --undo

Example output:

--- UNDO PREVIEW ---
INFO: will restore 5 files:
  Documents/report.pdf -> Downloads/
  Documents/Notes/notes.txt -> Downloads/
  Code/Config/config.yaml -> Downloads/
  Code/Scripts/script.py -> Downloads/
  Images/photo.png -> Downloads/

Do you want to undo these changes? [y/N]: y

--- UNDOING MOVES ---
Restored: Documents/report.pdf -> Downloads/
Restored: Documents/Notes/notes.txt -> Downloads/
Restored: Code/Config/config.yaml -> Downloads/
Restored: Code/Scripts/script.py -> Downloads/
Restored: Images/photo.png -> Downloads/

INFO: Removed empty directory: Documents/Notes
INFO: Removed empty directory: Code/Config
INFO: Removed empty directory: Code/Scripts

UNDO COMPLETE!
Files restored: 5, Skipped: 0, Failed: 0

Undo Dry-Run

Preview what would be undone without actually reversing changes:

./noentropy --undo --dry-run

When to use:

• Check what files will be restored before undoing
• Verify undo log integrity
• See if any conflicts exist

Undo Features

The undo system provides several safety features:

• Preview Before Action: Always shows what will be undone before executing
• Conflict Detection: Checks if source path already exists before restoring
• Missing File Handling: Gracefully handles files that were deleted after move
• Partial Undo Support: Continues even if some operations fail
• Empty Directory Cleanup: Automatically removes empty directories after undo
• History Retention: Keeps undo history for 30 days with auto-cleanup

Undo Limitations

• Only the most recent organization can be undone
• Files deleted after organization cannot be restored
• Files moved outside NoEntropy cannot be tracked
• Undo log is cleared after 30 days

Interactive Confirmation

Before moving files, NoEntropy shows you the organization plan:

--- EXECUTION PLAN ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: setup.exe -> Installers/
...

Do you want to apply these changes? [y/N]:

Options:

• Type y or yes to proceed with organization
• Type n, no, or press Enter to cancel

Tip: Always review the plan carefully, especially when using custom categories for the first time.

Changing Configuration

Change API Key

Update your Gemini API key interactively:

./noentropy --change-key

This will prompt you to enter a new API key and save it to your configuration.

Change Download Folder

Edit your config file manually:

nano ~/.config/noentropy/config.toml

Update the download_folder value and save.

Typical Workflows

First-Time User Workflow

1. Install NoEntropy
2. Run with --dry-run to preview:

   ./noentropy --dry-run
   

3. Review the organization plan
4. If satisfied, run without dry-run:

   ./noentropy
   

5. Review and confirm the plan
6. Let NoEntropy organize your files

Regular Usage Workflow

1. Download files throughout the week
2. Periodically run NoEntropy:

   ./noentropy
   

3. Review and confirm the plan
4. Files are organized automatically

Testing Custom Categories

1. Edit config file and add custom categories
2. Test with dry-run:

   ./noentropy --dry-run
   

3. Review how files are categorized
4. Adjust categories if needed
5. Run without dry-run when satisfied

Recovery Workflow

If organization didn't work as expected:

1. Undo the changes:

   ./noentropy --undo
   

2. Adjust configuration or categories
3. Test with dry-run again
4. Re-run organization

Example Terminal Output

Successful Organization

$ ./noentropy

Found 47 files. Asking Gemini to organize...
Gemini Plan received! Performing deep inspection...
Reading content of report.pdf...
Reading content of config.yaml...
Reading content of script.py...
Deep inspection complete! Moving Files.....

--- EXECUTION PLAN ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: setup.exe -> Installers/
Plan: notes.txt -> Documents/Notes/
Plan: config.yaml -> Code/Config/
Plan: script.py -> Code/Scripts/

Do you want to apply these changes? [y/N]: y

--- MOVING FILES ---
Moved: image1.png -> Images/
Moved: document.pdf -> Documents/
Moved: setup.exe -> Installers/
Moved: notes.txt -> Documents/Notes/
Moved: config.yaml -> Code/Config/
Moved: script.py -> Code/Scripts/

Organization Complete!
Files moved: 47, Errors: 0
Done!

Tips and Best Practices

1. Start with dry-run: Always test first, especially with custom categories
2. Review the plan: Don't blindly accept the organization plan
3. Use undo when needed: Don't hesitate to undo and reorganize
4. Adjust concurrency: Lower it if you hit rate limits
5. Regular organization: Run NoEntropy regularly to keep folders tidy
6. Test categories: Use dry-run to test custom categories before committing
7. Backup important files: Always maintain backups of critical files

Performance Considerations

• Concurrency: Higher concurrency = faster processing but more API calls
• Caching: NoEntropy caches API responses for 7 days to minimize API usage
• File count: Large numbers of files (1000+) may take several minutes
• Rate limits: Gemini API has rate limits; adjust --max-concurrent if needed

Next Steps

• How It Works - Understand the organization process
• Configuration Guide - Learn about configuration options
• Troubleshooting - Solve common issues

---

Back to Main README