diskclean-cli/README.md

macOS Disk Storage Management CLI with beautiful HTML reports

# 🧹 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.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)
![Platform](https://img.shields.io/badge/platform-macOS-lightgrey.svg)

## ✨ 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

![KPI](https://raw.githubusercontent.com/mchinnappan100/npmjs-images/main/diskclean/disk-clean-1.png)

## 📦 Installation

### Prerequisites
- Node.js >= 14.0.0
- macOS (tested on macOS 10.15+)

### Install

```bash
npm install -g diskclean-cli

```

```bash
# 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

```bash
# 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

```bash
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
```bash
diskclean scan --directory ~/Downloads --min-size 200
```

#### Find files older than 3 months
```bash
diskclean scan --older-than 3
```

#### Comprehensive scan with custom output
```bash
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)
```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)
```bash
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)
```bash
diskclean scan -s 200 -o 6 -l 100
```
- Large files (200MB+)
- Files older than 6 months
- Up to 100 files

#### Aggressive Cleanup (Maximum Space)
```bash
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:

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

# Avoid system directories like /System, /Library
```

### Script Not Opening in Browser

```bash
# 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

```bash
# Install Node.js via Homebrew
brew install node

# Or download from nodejs.org
```

## 📚 Advanced Usage

### Scripting and Automation

Create a weekly cleanup report:

```bash
#!/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

```bash
# 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](https://github.com/tj/commander.js)
- Styled with [Tailwind CSS](https://tailwindcss.com/)
- Charts powered by [Chart.js](https://www.chartjs.org/)

## 📞 Support

- 🐛 **Issues**: [GitHub Issues](https://github.com/mchinnappan100/diskclean-cli/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/mchinnappan100/diskclean-cli/discussions)

## 🔗 Related Tools

- [ncdu](https://dev.yorhel.nl/ncdu) - NCurses Disk Usage
- [DaisyDisk](https://daisydiskapp.com/) - Visual disk space analyzer (paid)
- [GrandPerspective](http://grandperspectiv.sourceforge.net/) - Visual disk usage (free)
- [CleanMyMac](https://macpaw.com/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! 🎉**