🧹 DiskClean - macOS Disk Storage Manager

A beautiful, comprehensive CLI tool for managing disk storage on macOS with interactive HTML reports, charts, and smart cleanup suggestions.

✨ Features

• 🎨 Beautiful Dark Theme Reports - Modern HTML reports with Tailwind CSS
• 📊 Interactive Charts - Visualize storage usage with Chart.js
• 🔍 Smart File Detection - Find large files eating up your disk space
• 📅 Age-Based Filtering - Filter files by 3, 6, 12, or 24 months
• 🗑️ Safe Cleanup Scripts - Generate bash scripts with confirmation prompts
• 📈 Comprehensive KPIs - Disk usage, file types, age distribution
• 📋 CSV Export - Export detailed reports for analysis
• 🎯 File Type Analysis - See which file types consume the most space
• 💡 Smart Suggestions - Get actionable cleanup recommendations

📸 Screenshots

📦 Installation

Prerequisites

• Node.js >= 14.0.0
• macOS (tested on macOS 10.15+)

Install

npm install -g diskclean-cli

# Clone the repository
git clone https://github.com/mchinnappan100/diskclean-cli.git
cd diskclean-cli

# Install dependencies
npm install

# Make executable
chmod +x diskclean.js

# Install globally
npm link

🚀 Quick Start

# Scan your home directory
diskclean scan

# Scan a specific directory
diskclean scan --directory ~/Downloads

# Find files larger than 500MB
diskclean scan --min-size 500

# Find files older than 6 months
diskclean scan --older-than 6

# Find large old files in Downloads
diskclean scan -d ~/Downloads -s 100 -o 6 -l 200

📖 Usage

Basic Command Structure

diskclean scan [options]

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --directory <path> | -d | Directory to scan | ~/ (home directory) | | --min-size <mb> | -s | Minimum file size in MB | 100 | | --older-than <months> | -o | Only show files older than X months | 0 (all files) | | --limit <number> | -l | Maximum number of files to show | 100 | | --html <file> | | Output HTML report filename | disk-report.html | | --csv <file> | | Output CSV report filename | disk-report.csv |

Examples

Scan Downloads folder for files over 200MB

diskclean scan --directory ~/Downloads --min-size 200

Find files older than 3 months

diskclean scan --older-than 3

Comprehensive scan with custom output

diskclean scan \
  --directory ~/Documents \
  --min-size 50 \
  --older-than 6 \
  --limit 500 \
  --html documents-report.html \
  --csv documents-report.csv

Scan multiple directories (run separately)

# Scan Downloads
diskclean scan -d ~/Downloads -s 100 --html downloads-report.html

# Scan Documents
diskclean scan -d ~/Documents -s 100 --html documents-report.html

# Scan Desktop
diskclean scan -d ~/Desktop -s 50 --html desktop-report.html

📊 Report Features

HTML Report Includes:

1. KPI Dashboard

   • Total disk size
   • Used space percentage
   • Available space
   • Cleanable space

2. Interactive Charts

   • 📁 Storage by file type (Doughnut chart)
   • 📅 File age distribution (Bar chart)

3. File Type Statistics Table

   • Extension breakdown
   • File counts
   • Total size per type
   • Percentage visualization

4. Large Files List

   • Complete file paths
   • File sizes
   • Modification dates
   • Age in days (color-coded)

5. Cleanup Script Generator

   • Ready-to-use bash script
   • Automatic confirmation prompt
   • Safe deletion process
   • Progress tracking

CSV Report Includes:

• Disk usage summary
• File type statistics
• Complete file listing with metadata
• Easy to import into Excel/Numbers

🗑️ Using the Cleanup Script

The tool generates a safe cleanup script that you can review before executing:

# 1. Copy the script from the HTML report (click "Copy Script" button)

# 2. Save it to a file
pbpaste > cleanup.sh

# 3. Make it executable
chmod +x cleanup.sh

# 4. Review the script (IMPORTANT!)
cat cleanup.sh

# 5. Run it (it will ask for confirmation)
./cleanup.sh

Safety Features

The generated cleanup script includes:

• ✅ Confirmation prompt before deletion
• ✅ File-by-file deletion with feedback
• ✅ Error handling for each file
• ✅ Summary of deleted files and freed space
• ✅ Only deletes files that still exist

🎯 Common Use Cases

Case 1: Quick Cleanup of Downloads

# Find files in Downloads older than 3 months
diskclean scan -d ~/Downloads -o 3 -s 50

What to look for:

• Old installers (.dmg, .pkg)
• Temporary downloads
• Duplicate files

Case 2: Free Up Space on Boot Drive

# Scan home directory for large old files
diskclean scan -d ~/ -s 500 -o 6 -l 500

What to look for:

• Old video files
• Cached data
• Log files
• Old backups

Case 3: Clean Up Project Files

# Find old development files
diskclean scan -d ~/Projects -s 100 -o 12

What to look for:

• node_modules folders (run separately on each project)
• Build artifacts
• Old dependencies
• Temporary files

Case 4: Media File Cleanup

# Find large media files
diskclean scan -d ~/Pictures -s 200 -o 6
diskclean scan -d ~/Movies -s 500 -o 3

What to look for:

• Duplicate photos
• Old videos
• Raw camera files
• Unedited footage

📈 Understanding the Reports

Disk Usage KPIs

• Total Size: Your disk capacity
• Used Space: Currently occupied space with percentage
• Available: Free space remaining
• Cleanable: Space that can be freed from found files

File Type Analysis

Shows which file types are consuming the most space:

• Video files (.mp4, .mov, .avi)
• Images (.jpg, .png, .raw)
• Archives (.zip, .tar, .gz)
• Disk images (.dmg, .iso)
• Documents (.pdf, .doc)

Age Distribution

Files categorized by age:

• 0-3 months: Recent files
• 3-6 months: Moderately old
• 6-12 months: Old files (good cleanup candidates)
• 1-2 years: Very old files
• 2+ years: Ancient files (prime cleanup targets)

⚠️ Important Warnings

Before Deleting Files

1. Always review the cleanup script before running it
2. Backup important data before bulk deletion
3. Check file paths carefully to avoid deleting system files
4. Test with small batches first
5. Verify files aren't in use by running applications

Files to Be Careful With

❌ Never delete without checking:

• System files (anything in /System, /Library)
• Application bundles (.app files)
• Current project files
• Unsaved work
• Files currently open in applications

✅ Usually safe to delete:

• Old downloads
• Temporary files
• Cache files
• Old backups (if you have newer ones)
• Duplicate media files
• Old installers after installation

🔧 Configuration Tips

Recommended Settings for Different Scenarios

Conservative Cleanup (Safest)

diskclean scan -s 500 -o 12 -l 50

• Only very large files (500MB+)
• Only files over 1 year old
• Limited to 50 files for review

Moderate Cleanup (Balanced)

diskclean scan -s 200 -o 6 -l 100

• Large files (200MB+)
• Files older than 6 months
• Up to 100 files

Aggressive Cleanup (Maximum Space)

diskclean scan -s 50 -o 3 -l 500

• Medium-large files (50MB+)
• Files older than 3 months
• Up to 500 files

🎨 Report Screenshots

KPI Dashboard

Shows at-a-glance disk usage metrics with beautiful gradient cards.

Charts Section

Interactive doughnut chart for file types and bar chart for age distribution.

File List

Sortable table with color-coded age indicators (green = recent, yellow = old, red = ancient).

Cleanup Script

Syntax-highlighted bash script ready to copy and execute.

🛠️ Troubleshooting

Permission Denied Errors

If you get permission errors when scanning:

# Scan only your user directories
diskclean scan -d ~/Downloads

# Avoid system directories like /System, /Library

Script Not Opening in Browser

# Manually open the report
open disk-report.html

# Or specify full path
open ~/path/to/disk-report.html

Slow Scans

For faster scans:

• Increase --min-size to skip smaller files
• Reduce --limit to process fewer files
• Scan specific directories instead of entire home folder

Node.js Not Found

# Install Node.js via Homebrew
brew install node

# Or download from nodejs.org

📚 Advanced Usage

Scripting and Automation

Create a weekly cleanup report:

#!/bin/bash
# weekly-cleanup.sh

DATE=$(date +%Y-%m-%d)
diskclean scan \
  -d ~/Downloads \
  -s 100 \
  -o 4 \
  --html "cleanup-report-$DATE.html" \
  --csv "cleanup-report-$DATE.csv"

echo "Report generated: cleanup-report-$DATE.html"

Combine with Other Tools

# Find duplicate files first (using fdupes)
brew install fdupes
fdupes -r ~/Downloads > duplicates.txt

# Then run diskclean
diskclean scan -d ~/Downloads -s 50

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Ideas for Contributions

• [ ] Add support for Linux
• [ ] Add support for Windows
• [ ] Interactive mode for file selection
• [ ] Integration with Trash instead of permanent deletion
• [ ] Duplicate file detection
• [ ] Scheduled scans
• [ ] Email reports
• [ ] Slack/Discord notifications
• [ ] Custom file type filters
• [ ] Exclude patterns (gitignore style)

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Commander.js
• Styled with Tailwind CSS
• Charts powered by Chart.js

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🔗 Related Tools

• ncdu - NCurses Disk Usage
• DaisyDisk - Visual disk space analyzer (paid)
• GrandPerspective - Visual disk usage (free)
• CleanMyMac - Comprehensive Mac cleaner (paid)

Made with 🧹 and ☕ for a cleaner Mac

⭐ Show Your Support

If you find this tool helpful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing on Twitter (X)
• 📝 Writing a blog post
• 🤝 Contributing to the project

Happy Cleaning! 🎉