🚀 macOS Cleaner - Quick Start Guide

Get up and running with macOS Cleaner in under 5 minutes!

📦 Installation

Step 1: Clone the Repository

git clone https://github.com/QDenka/MacCleanCLI.git
cd MacCleanCLI

Step 2: Install the Application

# Install with pip (development mode)
pip install -e .

Why -e flag? This installs the package in "editable" mode, meaning any code changes are immediately available without reinstalling.

Step 3: Verify Installation

# Test both commands
macos-cleaner --help
mclean --help

Expected output: Usage information and available options

Troubleshooting Installation

If you get ModuleNotFoundError:

# Ensure setup.py is properly configured
pip uninstall MacCleanCLI
pip install -e .

If commands not found:

# Check Python scripts directory is in PATH
echo $PATH | grep -q "Python" && echo "✓ Python in PATH" || echo "✗ Add Python to PATH"

# Find where scripts are installed
which macos-cleaner

🎬 First Run

Launch the Application

macos-cleaner

Alternative commands:

mclean                    # Short alias
python main.py            # Direct Python execution
macos-cleaner --scan-only # Scan without cleaning (safe preview)

Grant Permissions (Important!)

For full functionality, grant Full Disk Access:

macOS Ventura/Sonoma:
- Open System Settings → Privacy & Security → Full Disk Access
macOS Big Sur/Monterey:
- Open System Preferences → Security & Privacy → Privacy → Full Disk Access
Click 🔒 to unlock, then click + and add your Terminal app
Restart Terminal
Re-run macos-cleaner

🎯 Basic Workflow

1️⃣ Scan Your System

Interactive Mode:

Launch: macos-cleaner
Select: [1] 🔍 Scan System
Choose option:
- [a] - Scan ALL categories (recommended for first run)
- [1-9] - Select specific category
- [q] - Go back

Command Line Mode:

# Scan everything (no deletion)
macos-cleaner --scan-only

# Scan with verbose output
macos-cleaner --scan-only --verbose

What gets scanned?

✅ System & User Caches
✅ Browser Data (Safari, Chrome, Firefox, etc.)
✅ Developer Tools (Xcode, Docker, Homebrew, Node.js, Python)
✅ Temporary Files & Logs
✅ Large Files & Duplicates
✅ Old Downloads
✅ App Leftovers

2️⃣ Review Scan Results

The scan shows:

╭─────────────── Scan Results ───────────────╮
│                                            │
│ 📊 System Cache:     1,234 files (2.5 GB) │
│    Priority: HIGH                          │
│                                            │
│ 🌐 Browser Cache:     856 files (1.2 GB)  │
│    Priority: MEDIUM                        │
│                                            │
│ 🔨 Xcode Data:        92 files (3.8 GB)   │
│    Priority: HIGH                          │
│                                            │
│ Total: 15.7 GB can be freed                │
╰────────────────────────────────────────────╯

Priority Levels:

🔴 HIGH - Safe to delete, significant space savings
🟡 MEDIUM - Generally safe, moderate savings
🔵 LOW - Safe but minimal impact
⚪ OPTIONAL - Review before cleaning

3️⃣ Preview Files (NEW Feature!)

Before cleaning, see exactly what will be deleted:

Show detailed file list before cleaning? [Y/n]: y

📁 System Cache Files (showing 1-20 of 156)
┌──────────────────────────────────────────────────┐
│ ~/Library/Caches/com.apple.Safari/Cache.db      │
│ Size: 45.2 MB | Safe: ✅ Yes                     │
├──────────────────────────────────────────────────┤
│ ~/Library/Caches/com.spotify.client/Data/       │
│ Size: 128.5 MB | Safe: ✅ Yes                    │
├──────────────────────────────────────────────────┤
│ ... (16 more files)                              │
└──────────────────────────────────────────────────┘

Continue to next page? [Y/n]:

File preview features:

✅ Pagination (20 files per page)
✅ Shortened paths (~ for home directory)
✅ File sizes in human-readable format
✅ Safety indicators
✅ Interactive navigation

4️⃣ Clean Files

Option A: Quick Clean (Recommended)

Select [2] 🧹 Clean Files
Choose [2] Quick Clean (HIGH priority items only)
Review preview
Confirm cleaning

Option B: Custom Clean

Select [2] 🧹 Clean Files
Choose [1] Select Categories
Select specific categories to clean
Review preview
Confirm cleaning

Command Line:

# Automatic clean (HIGH priority only)
macos-cleaner --auto

# Dry run (preview without deletion)
macos-cleaner --dry-run

5️⃣ Optimize System (Optional)

Select [3] ⚡ Optimize System and choose:

Memory Optimization:

Purge inactive memory
Free up RAM

Network Optimization:

Flush DNS cache
Reset network connections

Startup Management:

View startup items
Disable unnecessary apps
Manage LaunchAgents/Daemons

Spotlight:

Rebuild search index
Fix slow search

💡 Common Use Cases

Daily Quick Cleanup

# One command, automatic cleaning
macos-cleaner --auto

What it does:

Scans HIGH priority categories
Shows preview
Cleans confirmed items
~2-3 minutes

Weekly Deep Clean

Step-by-step:

macos-cleaner
Scan ALL categories [a]
Review results carefully
Clean by priority:
- First: HIGH priority items
- Then: MEDIUM priority items
- Optional: Review LOW priority
Empty trash
Optimize system

Time needed: ~10-15 minutes

Before System Update

# Free maximum space
macos-cleaner --scan-only --verbose

Then clean:

All caches (System + User + Browser)
Temporary files
Old downloads
Trash
Xcode data (if applicable)
Docker data (if applicable)

Expected gain: 5-20 GB

Developer Workflow

For developers working with:

Xcode:

# Scan developer categories only
macos-cleaner
# Select [1] → Choose Xcode categories

Expected savings: 5-15 GB (DerivedData + Archives)

Docker:

# Clean Docker data through app
macos-cleaner
# OR use Docker directly:
docker system prune -a

Expected savings: 2-10 GB

Node.js:

# Find all node_modules
macos-cleaner
# Select Node.js category

Warning: ⚠️ Only delete from old/unused projects!

Monthly Maintenance

Complete system refresh:

Week 1: Scan and clean HIGH priority
Week 2: Review MEDIUM priority
Week 3: Check large files and duplicates
Week 4: Optimize system and startup

⚙️ Configuration

Settings Menu

Access via [4] ⚙️ Settings:

Dry Run Mode - Preview without deletion
Backup System - Auto-backup before cleaning
Verification - Verify files are deleted
Worker Threads - Parallel processing (default: 4)
Retention - Backup retention days (default: 7)

Config File

Located at: ~/.MacCleanCLI/config.json

Quick edits:

# Open config in editor
nano ~/.MacCleanCLI/config.json

# Or reset to defaults
rm ~/.MacCleanCLI/config.json
macos-cleaner  # Will create new config

Example config:

{
  "dry_run": false,
  "enable_backup": true,
  "verify_cleaning": true,
  "max_workers": 4,
  "backup_retention_days": 7,
  "min_file_size_mb": 0.001,
  "scan_hidden_files": false
}

⌨️ Keyboard Shortcuts

Main Menu

1-4 - Quick select menu option
q - Quit / Go back
Enter - Confirm selection

Scan Menu

a - Select all categories
1-9 - Select specific category
q - Back to main menu

Clean Menu

1 - Custom clean (select categories)
2 - Quick clean (HIGH priority)
q - Back to main menu

File Preview

y / Enter - Continue to next page
n - Skip to cleaning
q - Cancel operation

🛡️ Safety Tips

For First-Time Users

Always start with scan-only:
```
macos-cleaner --scan-only
```
Enable backup mode (Settings menu)
Review file preview before confirming
Start with HIGH priority only
Keep Time Machine backups current

Best Practices

✅ DO:

Review scan results carefully
Enable file preview
Use backup mode for first clean
Clean HIGH priority items first
Keep system backups

❌ DON'T:

Skip file preview on first run
Clean OPTIONAL items without review
Disable all safety features
Delete without backup
Run during important work

Red Flags 🚩

Stop and review if you see:

Unexpected file paths
System directories in results
App files you're actively using
Configuration files
Important documents

🔧 Troubleshooting Quick Fixes

"Permission Denied"

# Grant Full Disk Access (see Installation section)
# Or run specific scan with sudo (not recommended)
sudo macos-cleaner --scan-only

"No Files Found"

# Your system might be clean, or permissions issue
# Check if cache directories exist:
ls -la ~/Library/Caches/

"Command Not Found"

# Reinstall package
pip uninstall MacCleanCLI
pip install -e .

# Or use direct Python
python main.py

Application Freezes

# Check logs
cat ~/.macos-cleaner/logs/*.log

# Reset config
rm ~/.MacCleanCLI/config.json

For more issues, see TROUBLESHOOTING.md

📚 Next Steps

Learn More

Advanced Usage

# Custom config file
macos-cleaner --config ~/my-config.json

# Combine multiple flags
macos-cleaner --scan-only --verbose --config ~/safe-config.json

# Direct Python with options
python main.py --auto --verbose

Development

# Run tests
pytest

# Check code coverage
pytest --cov=. --cov-report=html

# Format code
black . --line-length 100

🎯 Pro Tips

Schedule Weekly Scans

# Add to crontab for weekly scans
0 9 * * 1 /usr/local/bin/macos-cleaner --scan-only

Monitor Disk Space
- Use system info panel in app
- Check before and after cleaning
- Track savings over time
Developer Setup
- Create separate config for dev vs production
- Use --dry-run to test before batch operations
- Enable verbose logging for debugging
Backup Strategy
- Keep app backups for 7 days (default)
- Use Time Machine for critical files
- Export config before major changes
Performance Optimization
- Close browsers before cleaning browser cache
- Increase max_workers for faster scans (4-8)
- Run during system idle time

✨ What's New

Version 1.0 Features

✅ 19 cleaning categories
✅ NEW: File detail preview with pagination
✅ NEW: Developer tools cleanup (Xcode, Docker, Homebrew, Node.js, Python)
✅ Multi-threaded scanning
✅ Priority-based cleaning
✅ Rich console UI
✅ Backup system
✅ 87 tests passing

Happy Cleaning! 🧹✨

Need help? Open an issue on GitHub

FilesExpand file tree

QUICKSTART.md

Latest commit

History