FileFlow CLI

A smart command-line tool to automate repetitive file tasks — organize, rename, convert, and find duplicates in seconds.

Features

| Command | Description | |---|---| | organize | Auto-sort files into folders by type, date, or size | | rename | Bulk rename using templates, find/replace, or case conversion | | convert | Convert data files between CSV, JSON, and Excel | | duplicates | Find and remove duplicate files using MD5 hashing | | watch | Monitor a folder and auto-process new files |

Installation

Global install (recommended)

Install once, use fileflow anywhere on your system:

npm install -g fileflow-clitool

# Then use directly:
fileflow --help
fileflow organize ./downloads
fileflow rename ./photos --find "IMG_" --replace "photo_"

Local install (per project)

Install into a specific project folder:

npm install fileflow-clitool

# Use via npx (no -g required):
npx fileflow --help
npx fileflow organize ./downloads
npx fileflow rename ./photos --find "IMG_" --replace "photo_"

| | Global (-g) | Local (no -g) | |---|---|---| | Command | fileflow ... | npx fileflow ... | | Available from | Anywhere | Only inside that project folder | | Best for | End users | Scripts / CI pipelines |

Clone and link locally (for development)

git clone https://github.com/Vall-Here/fileflow-cli.git
cd fileflow-cli
npm install
npm link

Usage

organize — Sort files into folders

# Sort by file type (images, documents, videos...)
fileflow organize ./downloads

# Sort by month (2024-01, 2024-02...)
fileflow organize ./photos --by date

# Sort by size (small, medium, large, huge)
fileflow organize ./downloads --by size

# Preview without moving anything
fileflow organize ./downloads --dry-run

# Include subdirectories
fileflow organize ./downloads --recursive

rename — Bulk rename files

# Rename with a template
fileflow rename ./invoices --pattern "invoice_{date}_{index:3}"
# → invoice_2024-01-15_001.pdf, invoice_2024-01-16_002.pdf

# Find and replace in filenames
fileflow rename ./photos --find "IMG_" --replace "photo_"
# → photo_001.jpg, photo_002.jpg

# Change case style
fileflow rename ./docs --case kebab
# → my-document.pdf, another-file.txt

# Only rename .jpg files
fileflow rename ./photos --case snake --ext jpg

# Preview first
fileflow rename ./files --pattern "{name}_{date}" --dry-run

Template tokens:

| Token | Description | Example | |---|---|---| | {name} | Original filename (no extension) | report | | {ext} | File extension | pdf | | {index} | Sequential number | 1, 2, 3 | | {index:3} | Zero-padded number | 001, 002 | | {date} | File modification date | 2024-01-15 | | {timestamp} | Unix timestamp | 1705276800 |

convert — Convert data files

# Single file
fileflow convert data.csv --to json
fileflow convert data.json --to xlsx
fileflow convert data.xlsx --to csv

# Batch convert entire folder
fileflow convert ./data-folder --to json

# Specify Excel sheet
fileflow convert report.xlsx --to csv --sheet "Sales Q4"

# Custom output directory
fileflow convert data.csv --to json --output ./output

# Minify JSON output
fileflow convert data.csv --to json --minify

duplicates — Find and clean duplicates

# Find duplicates (report only)
fileflow duplicates ./downloads

# Include subdirectories
fileflow duplicates ./photos --recursive

# Preview what would be deleted
fileflow duplicates ./downloads --delete --dry-run

# Actually delete duplicates (keeps first copy)
fileflow duplicates ./downloads --delete

watch — Auto-process new files

# Watch and auto-organize by file type
fileflow watch ./downloads

# Watch and organize by date
fileflow watch ./inbox --by date

Project Structure

fileflow-cli/
├── bin/
│   └── fileflow.js          # CLI entry point
├── src/
│   ├── commands/
│   │   ├── organize.js      # File organizer
│   │   ├── rename.js        # Bulk renamer
│   │   ├── convert.js       # Data converter
│   │   ├── duplicates.js    # Duplicate finder
│   │   └── watch.js         # Folder watcher
│   └── utils/
│       ├── fileHelpers.js   # Shared file utilities
│       └── logger.js        # Consistent CLI output
├── tests/
│   └── commands/
│       └── organize.test.js
├── package.json
└── README.md

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

# Run locally without installing
node bin/fileflow.js organize ./test-folder

🛠️ Tech Stack

• Commander.js — CLI argument parsing
• Chalk — Terminal colors
• Ora — Spinner/loading indicators
• fs-extra — Enhanced file operations
• PapaParse — CSV parsing
• SheetJS — Excel read/write
• glob — File pattern matching
• Jest — Testing framework

Roadmap

• [ ] Config file support (.fileflowrc)
• [ ] Plugin system for custom actions
• [ ] Image resize/compress command
• [ ] Undo last operation
• [ ] Interactive mode with prompts

License

MIT © Ahmad Noval

Contributing

Pull requests welcome! Please open an issue first to discuss major changes.

git checkout -b feature/your-feature
npm test
git commit -m "feat: add your feature"
git push origin feature/your-feature