mac-cleaner-cli-disk-cleanup

mac-cleaner-cli Skill

Skill by ara.so — Devtools Skills collection.

What It Does

mac-cleaner-cli is a TypeScript-based CLI tool that helps free up disk space on macOS by cleaning:

• System and user caches
• Browser caches (Chrome, Safari, Firefox, Arc)
• Temporary files
• Development caches (npm, yarn, pip, Xcode DerivedData, CocoaPods)
• Homebrew downloads and cache
• Docker images and containers
• System logs
• Trash
• Orphaned node_modules
• iOS backups, downloads, mail attachments (risky categories)

Key features:

• Interactive checkbox selection
• Drill-down file explorer for granular control
• Safe by default (risky items require --risky flag)
• App uninstaller with complete cleanup
• 100% offline, no telemetry
• Minimal dependencies

Installation

One-Time Usage (Recommended)

npx mac-cleaner-cli

Global Installation

npm install -g mac-cleaner-cli
mac-cleaner-cli

For Development

git clone https://github.com/guhcostan/mac-cleaner-cli.git
cd mac-cleaner-cli
bun install
bun run dev

Key Commands

Interactive Cleanup (Main Command)

# Basic interactive mode - scan and clean
npx mac-cleaner-cli

# Include risky categories (downloads, iOS backups, duplicates, large files)
npx mac-cleaner-cli --risky

# Force file picker for ALL categories
npx mac-cleaner-cli --risky -f

# Show absolute paths
npx mac-cleaner-cli -A

# Disable progress bars
npx mac-cleaner-cli --no-progress

Interactive controls:

• ↑↓ navigate items
• ← go back
• → drill into category (file explorer)
• space toggle selection
• a select all
• i invert selection
• ⏎ submit/confirm

App Uninstaller

# Uninstall apps completely with preferences and support files
npx mac-cleaner-cli uninstall

Maintenance Tasks

# Flush DNS cache (may require sudo)
npx mac-cleaner-cli maintenance --dns

# Free purgeable space
npx mac-cleaner-cli maintenance --purgeable

Category Management

# List all available cleaning categories
npx mac-cleaner-cli categories

Configuration

# Initialize configuration file
npx mac-cleaner-cli config --init

# Show current configuration
npx mac-cleaner-cli config --show

Backup Management

# List all backups
npx mac-cleaner-cli backup --list

# Clean old backups
npx mac-cleaner-cli backup --clean

Help and Version

# Show version
npx mac-cleaner-cli --version
npx mac-cleaner-cli -V

# Show help
npx mac-cleaner-cli --help
npx mac-cleaner-cli -h

Categories

Safe Categories (Always Safe)

Category	Description
trash	Files in Trash bin
temp-files	Temporary files in /tmp and /var/folders
browser-cache	Chrome, Safari, Firefox, Arc cache
homebrew	Homebrew download cache
docker	Unused Docker images, containers, volumes

Moderate Categories (Generally Safe)

Category	Description
system-cache	Application caches in ~/Library/Caches
system-logs	System and application logs
dev-cache	npm, yarn, pip, Xcode DerivedData, CocoaPods
node-modules	Orphaned node_modules in old projects

Risky Categories (Requires --risky Flag)

Category	Description
downloads	Downloads older than 30 days
ios-backups	iPhone and iPad backup files
mail-attachments	Downloaded email attachments
duplicates	Duplicate files (keeps newest)
large-files	Files larger than 500MB
language-files	Unused language localizations

Common Usage Patterns

Quick Disk Cleanup

# Run interactively, select common safe categories
npx mac-cleaner-cli
# Select: Trash, Browser Cache, Temporary Files, User Cache Files, Development Cache

Developer Cleanup

# Clean development caches and orphaned node_modules
npx mac-cleaner-cli
# Focus on: Development Cache, node_modules folders

Deep Clean with Risky Categories

# Include all categories including risky ones
npx mac-cleaner-cli --risky
# Review carefully before cleaning downloads, iOS backups, etc.

Drill Down into Specific Folders

# Run interactive mode
npx mac-cleaner-cli

# Navigate to a category like "User Cache Files"
# Press → to open file explorer
# Select specific app caches to remove
# Press ← to go back, space to toggle, ⏎ to confirm

CI/CD Usage

# Non-interactive cleanup (future feature)
# Currently, the tool is interactive-first
# For automated scripts, consider using with expect or similar tools

Complete App Removal

# Remove app with all associated files
npx mac-cleaner-cli uninstall
# Select app from list
# Confirms removal of .app, preferences, caches, support files

Configuration

The tool supports a configuration file for customizing behavior.

Initialize Config

npx mac-cleaner-cli config --init

This creates a config file at ~/.mac-cleaner-cli/config.json (exact location may vary).

View Current Config

npx mac-cleaner-cli config --show

Configuration Options

While the exact schema isn't fully documented in the README, typical options might include:

{
  "defaultCategories": ["trash", "temp-files", "browser-cache"],
  "excludePaths": [
    "/Users/username/important-cache"
  ],
  "backupBeforeClean": true,
  "showAbsolutePaths": false
}

Troubleshooting

Permission Errors

Problem: "Permission denied" when cleaning certain files.

Solution:

# Some system files may require elevated permissions
# The tool generally runs as current user
# For DNS flush:
sudo npx mac-cleaner-cli maintenance --dns

Categories Not Showing

Problem: Risky categories aren't visible.

Solution:

# Use the --risky flag
npx mac-cleaner-cli --risky

File Picker Not Available

Problem: Can't drill down into a category.

Solution:

# Not all categories support file-level selection
# Supported: User Cache Files, Temporary Files, System Log Files, 
#            Development Cache, Browser Cache, Homebrew Cache
# Use -f to force file picker for all categories
npx mac-cleaner-cli -f

Large Scan Times

Problem: Scanning takes a long time.

Solution:

• This is normal for Macs with many files
• Consider excluding large directories if you have custom config
• The tool scans common locations efficiently

Accidental Deletion

Problem: Deleted something important.

Solution:

# Check if backups are enabled in config
npx mac-cleaner-cli backup --list

# Restore from Time Machine or system backups
# Always verify selections before confirming cleanup

Docker Cleanup Issues

Problem: Docker containers still running after cleanup attempt.

Solution:

# Stop all containers first
docker stop $(docker ps -aq)

# Then run cleaner
npx mac-cleaner-cli

Tool Not Found After Global Install

Problem: mac-cleaner-cli: command not found

Solution:

# Ensure npm global bin is in PATH
npm config get prefix
# Add to PATH: export PATH="$PATH:$(npm config get prefix)/bin"

# Or use npx
npx mac-cleaner-cli

Development Integration

Using in Scripts

// Example: Potential programmatic usage (check actual API)
import { scan, clean } from 'mac-cleaner-cli';

// Note: The tool is primarily CLI-focused
// Check package exports for programmatic API availability

Building from Source

git clone https://github.com/guhcostan/mac-cleaner-cli.git
cd mac-cleaner-cli

# Install dependencies
bun install

# Run in development
bun run dev

# Run tests
bun run test

# Lint code
bun run lint

# Build for production
bun run build

Project Structure

mac-cleaner-cli/
├── src/               # TypeScript source code
├── tests/             # Test files
├── assets/            # Banner images, assets
├── package.json       # Dependencies and scripts
├── tsconfig.json      # TypeScript configuration
└── README.md          # Documentation

Best Practices

1. Always review before cleaning: Use the interactive checkboxes to verify what will be deleted
2. Start with safe categories: Run without --risky first
3. Use file explorer: Press → on categories to select specific folders
4. Keep backups: Enable backup settings in config for critical data
5. Regular maintenance: Run weekly/monthly to prevent disk space issues
6. Check app uninstaller: Use built-in uninstaller instead of dragging to Trash
7. Monitor freed space: Note the summary after cleanup to track effectiveness

Security Notes

• 100% offline: No network requests, no telemetry
• Open source: All code available for audit at https://github.com/guhcostan/mac-cleaner-cli
• No root required: Runs as current user (except DNS flush with sudo)
• Minimal dependencies: Only 5 runtime dependencies, monitored by Socket.dev
• Safe defaults: Risky operations hidden behind --risky flag

Platform Support

• macOS only: Designed specifically for macOS
• Node.js required: Check compatibility with package.json (typically Node.js 16+)
• Windows alternative: See windows-cleaner-cli for Windows support

Related Commands

# Check disk usage before cleanup
df -h

# Check specific directory sizes
du -sh ~/Library/Caches/*

# Manual cleanup alternatives
brew cleanup --prune=all
docker system prune -a
rm -rf ~/Library/Developer/Xcode/DerivedData

# Check what's using disk space
ncdu /

Additional Resources

• GitHub Repository: https://github.com/guhcostan/mac-cleaner-cli
• npm Package: https://www.npmjs.com/package/mac-cleaner-cli
• Issues: https://github.com/guhcostan/mac-cleaner-cli/issues
• Discussions: https://github.com/guhcostan/mac-cleaner-cli/discussions
• License: MIT