{"id":36965456,"url":"https://github.com/guhcostan/mac-cleaner-cli","last_synced_at":"2026-06-09T19:00:24.573Z","repository":{"id":327574300,"uuid":"1109901849","full_name":"guhcostan/mac-cleaner-cli","owner":"guhcostan","description":"macOS CLI to free disk space — clears caches, logs, Homebrew and Xcode junk","archived":false,"fork":false,"pushed_at":"2026-04-14T12:05:57.000Z","size":2356,"stargazers_count":1674,"open_issues_count":2,"forks_count":157,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-04-14T14:13:02.147Z","etag":null,"topics":["cache-cleaner","cleanup","cli","disk-space","homebrew","macos","nodejs","open-source","typescript","xcode"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/mac-cleaner-cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guhcostan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"guhcostan","ko_fi":"guhcostan"}},"created_at":"2025-12-04T12:49:07.000Z","updated_at":"2026-04-14T02:58:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/guhcostan/mac-cleaner-cli","commit_stats":null,"previous_names":["guhcostan/clean-my-mac","guhcostan/-clean-my-mac"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/guhcostan/mac-cleaner-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guhcostan%2Fmac-cleaner-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guhcostan%2Fmac-cleaner-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guhcostan%2Fmac-cleaner-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guhcostan%2Fmac-cleaner-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guhcostan","download_url":"https://codeload.github.com/guhcostan/mac-cleaner-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guhcostan%2Fmac-cleaner-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34121022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache-cleaner","cleanup","cli","disk-space","homebrew","macos","nodejs","open-source","typescript","xcode"],"created_at":"2026-01-13T19:59:55.439Z","updated_at":"2026-06-09T19:00:24.550Z","avatar_url":"https://github.com/guhcostan.png","language":"TypeScript","funding_links":["https://github.com/sponsors/guhcostan","https://ko-fi.com/guhcostan"],"categories":[],"sub_categories":[],"readme":"# mac-cleaner-cli\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/guhcostan/mac-cleaner-cli/main/assets/banner.png\" alt=\"mac-cleaner-cli — free macOS disk space cleaner CLI tool\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Free up disk space on macOS with a single command. Removes caches, logs, Homebrew leftovers, Xcode DerivedData, and junk files — all from your terminal.\u003cbr\u003e\n  No subscription. No telemetry. No bloatware.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/mac-cleaner-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/mac-cleaner-cli?color=cb3837\u0026label=npm\u0026logo=npm\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/mac-cleaner-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/mac-cleaner-cli?color=cb3837\u0026logo=npm\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/guhcostan/mac-cleaner-cli/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/guhcostan/mac-cleaner-cli/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/node/v/mac-cleaner-cli\" alt=\"Node.js Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.apple.com/macos/\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-macOS-000?logo=apple\" alt=\"Platform: macOS\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-6.0-3178c6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://socket.dev/npm/package/mac-cleaner-cli\"\u003e\u003cimg src=\"https://socket.dev/api/badge/npm/package/mac-cleaner-cli\" alt=\"Socket Badge\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/guhcostan/mac-cleaner-cli/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/guhcostan/mac-cleaner-cli?style=social\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/guhcostan/mac-cleaner-cli/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/guhcostan/mac-cleaner-cli?style=social\" alt=\"GitHub Forks\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ko-fi.com/guhcostan\"\u003e\u003cimg src=\"https://img.shields.io/badge/Ko--fi-Support_this_project-FF5E5B?style=for-the-badge\u0026logo=ko-fi\u0026logoColor=white\" alt=\"Support on Ko-fi\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🪟 Also available for Windows:\u003c/strong\u003e \u003ca href=\"https://github.com/guhcostan/windows-cleaner-cli\"\u003ewindows-cleaner-cli\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ⚡ Quick Start\n\n```bash\nnpx mac-cleaner-cli\n```\n\nThat's it. No installation needed. The CLI will:\n\n1. 🔍 **Scan** your Mac for cleanable files\n2. 📋 **Show** you what was found with sizes\n3. ✅ **Let you select** exactly what to clean\n4. 🗑️ **Clean** only what you chose\n\n## 🎬 See It In Action\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/guhcostan/mac-cleaner-cli/main/assets/demo.gif\" alt=\"mac-cleaner-cli demo\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🚀 **One Command** | Just run `npx mac-cleaner-cli` — no complex setup |\n| 🎯 **Interactive** | Select exactly what you want to clean with checkboxes |\n| 📁 **File Explorer** | Drill down (`→`) into categories to select specific folders/files |\n| 🛡️ **Safe by Default** | Risky items hidden unless you use `--risky` |\n| 🔍 **Smart Scanning** | Finds caches, logs, dev files, browser data, and more |\n| 📱 **App Uninstaller** | Remove apps completely with all associated files |\n| 🔧 **Maintenance** | Flush DNS cache, free purgeable space |\n| 🔒 **Privacy First** | 100% offline — no data ever leaves your machine |\n| 📦 **Minimal Dependencies** | Only 5 runtime deps, all from trusted maintainers |\n\n## 💰 vs. Paid Alternatives\n\n| | Mac Cleaner CLI | CleanMyMac X | DaisyDisk |\n|---|---|---|---|\n| **Price** | **Free** | $39.95/year | $9.99 one-time |\n| **Open Source** | ✅ | ❌ | ❌ |\n| **Telemetry / Analytics** | ❌ None | ⚠️ Yes | ⚠️ Yes |\n| **Works via terminal** | ✅ | ❌ | ❌ |\n| **CI/CD friendly** | ✅ | ❌ | ❌ |\n| **Customizable** | ✅ Fork it | ❌ | ❌ |\n| **App Uninstaller** | ✅ | ✅ | ❌ |\n| **File-level selection** | ✅ | ✅ | ✅ |\n\n## 🎯 What It Cleans\n\n### 🟢 Safe (always safe to delete)\n\n| Category | What it cleans |\n|----------|---------------|\n| `trash` | Files in the Trash bin |\n| `temp-files` | Temporary files in /tmp and /var/folders |\n| `browser-cache` | Chrome, Safari, Firefox, Arc cache |\n| `homebrew` | Homebrew download cache |\n| `docker` | Unused Docker images, containers, volumes |\n\n### 🟡 Moderate (generally safe)\n\n| Category | What it cleans |\n|----------|---------------|\n| `system-cache` | Application caches in ~/Library/Caches |\n| `system-logs` | System and application logs |\n| `dev-cache` | npm, yarn, pip, Xcode DerivedData, CocoaPods |\n| `node-modules` | Orphaned node_modules in old projects |\n\n### 🔴 Risky (use `--risky` flag)\n\n| Category | What it cleans |\n|----------|---------------|\n| `downloads` | Downloads older than 30 days |\n| `ios-backups` | iPhone and iPad backup files |\n| `mail-attachments` | Downloaded email attachments |\n| `duplicates` | Duplicate files (keeps newest) |\n| `large-files` | Files larger than 500MB |\n| `language-files` | Unused language localizations |\n\n## 📖 Usage\n\n### Basic Usage\n\n```bash\n# Interactive mode — scan, select, and clean\nnpx mac-cleaner-cli\n\n# Include risky categories\nnpx mac-cleaner-cli --risky\n\n# Enable file picker for all categories\nnpx mac-cleaner-cli --risky -f\n```\n\n### Folder-Level Selection (Interactive)\n\nIn interactive mode, press `→` on supported categories to drill into specific folders/files:\n\n- `↑↓` navigate • `←` back • `→` enter • `space` select • `a` all • `i` invert • `⏎` submit\n\nSupported categories: User Cache Files, Temporary Files, System Log Files, Development Cache, Browser Cache, Homebrew Cache.\n\n### Uninstall Apps\n\nRemove applications completely with all their preferences, caches, and support files:\n\n```bash\nnpx mac-cleaner-cli uninstall\n```\n\n### Maintenance Tasks\n\n```bash\n# Flush DNS cache (may require sudo)\nnpx mac-cleaner-cli maintenance --dns\n\n# Free purgeable space\nnpx mac-cleaner-cli maintenance --purgeable\n```\n\n### Other Commands\n\n```bash\n# List all available categories\nnpx mac-cleaner-cli categories\n\n# Manage configuration\nnpx mac-cleaner-cli config --init\nnpx mac-cleaner-cli config --show\n\n# Manage backups\nnpx mac-cleaner-cli backup --list\nnpx mac-cleaner-cli backup --clean\n```\n\n### Flags\n\n```bash\n-V, --version          Show version number\n-h, --help             Show help\n-r, --risky            Include risky categories\n-f, --file-picker      Force file picker for ALL categories\n-A, --absolute-paths   Show absolute paths\n    --no-progress      Disable progress bars\n```\n\n## 💻 Global Installation\n\nIf you use this tool frequently:\n\n```bash\nnpm install -g mac-cleaner-cli\nmac-cleaner-cli\n```\n\n## 🔒 Security\n\n| | |\n|---|---|\n| ✅ **Open Source** | All code publicly available for audit |\n| ✅ **No Network** | Operates 100% offline |\n| ✅ **No Root Required** | All operations run as current user |\n| ✅ **Minimal Deps** | Only 5 runtime dependencies |\n| ✅ **CI/CD** | Every release tested with TypeScript, ESLint, and automated tests |\n| ✅ **Socket.dev** | Dependencies monitored for supply chain attacks |\n\nFound a vulnerability? Report it via [GitHub Security Advisories](https://github.com/guhcostan/mac-cleaner-cli/security/advisories/new).\n\n## 🛠️ Development\n\n```bash\ngit clone https://github.com/guhcostan/mac-cleaner-cli.git\ncd mac-cleaner-cli\nbun install\nbun run dev      # Run in dev mode\nbun run test     # Run tests\nbun run lint     # Run linter\nbun run build    # Build for production\n```\n\n## 🤝 Contributing\n\nContributions are very welcome! Whether it's a new scanner, a bug fix, or a documentation improvement — we'd love your help.\n\n**Read the full guide:** [CONTRIBUTING.md](CONTRIBUTING.md)\n\nQuick steps:\n1. Fork the repo\n2. Create your branch: `git checkout -b feat/my-feature`\n3. Make your changes and add tests\n4. Run `bun run lint \u0026\u0026 bun run test`\n5. Open a Pull Request\n\nLooking for a place to start? Check issues labeled [`good first issue`](https://github.com/guhcostan/mac-cleaner-cli/labels/good%20first%20issue) or [`help wanted`](https://github.com/guhcostan/mac-cleaner-cli/labels/help%20wanted).\n\n## 💬 Community\n\n- [GitHub Discussions](https://github.com/guhcostan/mac-cleaner-cli/discussions) — questions, ideas, show \u0026 tell\n- [Issues](https://github.com/guhcostan/mac-cleaner-cli/issues) — bug reports and feature requests\n\n## ⭐ Star History\n\nIf this tool saved you disk space, a star goes a long way! It helps more Mac users discover this free alternative to paid cleaners.\n\n[![Star History Chart](https://api.star-history.com/svg?repos=guhcostan/mac-cleaner-cli\u0026type=Date)](https://star-history.com/#guhcostan/mac-cleaner-cli\u0026Date)\n\n## 💚 Support\n\nIf this tool saved you time or disk space, consider supporting the project!\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ko-fi.com/guhcostan\"\u003e\u003cimg src=\"https://ko-fi.com/img/githubbutton_sm.svg\" alt=\"Support on Ko-fi\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nYour support helps maintain and improve this tool. Thank you! 🙏\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e⚠️ Disclaimer\u003c/strong\u003e\u003cbr\u003e\n  This tool deletes files from your system. While we've implemented safety measures, always ensure you have backups of important data.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ for Mac users everywhere\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguhcostan%2Fmac-cleaner-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguhcostan%2Fmac-cleaner-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguhcostan%2Fmac-cleaner-cli/lists"}