mac-cleaner-cli-disk-cleanup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mac-cleaner-cli Skill

mac-cleaner-cli 工具

Skill by ara.so — Devtools Skills collection.

由 ara.so 开发的工具 — 属于Devtools Skills工具集。

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

mac-cleaner-cli

是一款基于TypeScript的CLI工具，可通过清理以下内容为macOS释放磁盘空间：

系统与用户缓存
浏览器缓存（Chrome、Safari、Firefox、Arc）
临时文件
开发缓存（npm、yarn、pip、Xcode DerivedData、CocoaPods）
Homebrew下载文件与缓存
Docker镜像与容器
系统日志
回收站文件
孤立的node_modules
iOS备份、下载文件、邮件附件（高风险类别）

核心特性：

交互式复选框选择
可深入查看的文件资源管理器，支持精细化控制
默认安全模式（高风险项目需使用
```
--risky
```
参数）
应用卸载器，可完成彻底清理
100%离线运行，无遥测数据收集
依赖项极少

Installation

安装方法

One-Time Usage (Recommended)

一次性使用（推荐）

bash

npx mac-cleaner-cli

bash

npx mac-cleaner-cli

Global Installation

全局安装

bash

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

bash

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

For Development

开发环境安装

bash

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

bash

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)

交互式清理（主命令）

bash

undefined

bash

undefined

Basic interactive mode - scan and clean

基础交互模式 - 扫描并清理

npx mac-cleaner-cli

Include risky categories (downloads, iOS backups, duplicates, large files)

包含高风险类别（下载文件、iOS备份、重复文件、大文件）

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

npx mac-cleaner-cli --no-progress


**交互操作说明：**
- `↑↓` 导航项目
- `←` 返回上一级
- `→` 深入查看类别（文件资源管理器）
- `space` 切换选中状态
- `a` 全选
- `i` 反选
- `⏎` 提交/确认

App Uninstaller

应用卸载器

bash

undefined

bash

undefined

Uninstall apps completely with preferences and support files

彻底卸载应用，包括偏好设置和支持文件

npx mac-cleaner-cli uninstall

undefined

npx mac-cleaner-cli uninstall

undefined

Maintenance Tasks

维护任务

bash

undefined

bash

undefined

Flush DNS cache (may require sudo)

刷新DNS缓存（可能需要sudo权限）

npx mac-cleaner-cli maintenance --dns

Free purgeable space

释放可清除空间

npx mac-cleaner-cli maintenance --purgeable

undefined

npx mac-cleaner-cli maintenance --purgeable

undefined

Category Management

类别管理

bash

undefined

bash

undefined

List all available cleaning categories

列出所有可用的清理类别

npx mac-cleaner-cli categories

undefined

npx mac-cleaner-cli categories

undefined

Configuration

配置管理

bash

undefined

bash

undefined

Initialize configuration file

初始化配置文件

npx mac-cleaner-cli config --init

Show current configuration

显示当前配置

npx mac-cleaner-cli config --show

undefined

npx mac-cleaner-cli config --show

undefined

Backup Management

备份管理

bash

undefined

bash

undefined

List all backups

列出所有备份

npx mac-cleaner-cli backup --list

Clean old backups

清理旧备份

npx mac-cleaner-cli backup --clean

undefined

npx mac-cleaner-cli backup --clean

undefined

Help and Version

帮助与版本信息

bash

undefined

bash

undefined

Show version

显示版本号

npx mac-cleaner-cli --version npx mac-cleaner-cli -V

Show help

显示帮助信息

npx mac-cleaner-cli --help npx mac-cleaner-cli -h

undefined

npx mac-cleaner-cli --help npx mac-cleaner-cli -h

undefined

清理类别

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

类别	描述
`trash`	回收站中的文件
`temp-files`	/tmp和/var/folders中的临时文件
`browser-cache`	Chrome、Safari、Firefox、Arc的缓存
`homebrew`	Homebrew的下载缓存
`docker`	未使用的Docker镜像、容器、卷

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

类别	描述
`system-cache`	~/Library/Caches中的应用缓存
`system-logs`	系统与应用日志
`dev-cache`	npm、yarn、pip、Xcode DerivedData、CocoaPods的缓存
`node-modules`	旧项目中孤立的node_modules

Risky Categories (Requires

--risky

Flag)

高风险类别（需使用

--risky

参数）

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

类别	描述
`downloads`	超过30天的下载文件
`ios-backups`	iPhone和iPad的备份文件
`mail-attachments`	已下载的邮件附件
`duplicates`	重复文件（保留最新版本）
`large-files`	大于500MB的文件
`language-files`	未使用的语言本地化文件

Common Usage Patterns

常见使用场景

Quick Disk Cleanup

快速磁盘清理

bash

undefined

bash

undefined

Run interactively, select common safe categories

以交互模式运行，选择常见的安全类别

npx mac-cleaner-cli

Select: Trash, Browser Cache, Temporary Files, User Cache Files, Development Cache

选择：回收站、浏览器缓存、临时文件、用户缓存文件、开发缓存

undefined

undefined

Developer Cleanup

开发者专属清理

bash

undefined

bash

undefined

Clean development caches and orphaned node_modules

清理开发缓存和孤立的node_modules

npx mac-cleaner-cli

Focus on: Development Cache, node_modules folders

重点选择：开发缓存、node_modules文件夹

undefined

undefined

Deep Clean with Risky Categories

包含高风险类别的深度清理

bash

undefined

bash

undefined

Include all categories including risky ones

包含所有类别，包括高风险类别

npx mac-cleaner-cli --risky

Review carefully before cleaning downloads, iOS backups, etc.

清理下载文件、iOS备份等内容前请仔细检查

undefined

undefined

Drill Down into Specific Folders

深入查看特定文件夹

bash

undefined

bash

undefined

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

按←返回，space切换选中状态，⏎确认

undefined

undefined

CI/CD Usage

CI/CD 使用

bash

undefined

bash

undefined

Non-interactive cleanup (future feature)

非交互式清理（未来功能）

Currently, the tool is interactive-first

当前工具优先支持交互模式

For automated scripts, consider using with expect or similar tools

如需自动化脚本，可考虑搭配expect等工具使用

undefined

undefined

Complete App Removal

彻底卸载应用

bash

undefined

bash

undefined

Remove app with all associated files

删除应用及所有关联文件

npx mac-cleaner-cli uninstall

Select app from list

从列表中选择应用

Confirms removal of .app, preferences, caches, support files

确认删除.app文件、偏好设置、缓存、支持文件

undefined

undefined

Configuration

配置说明

The tool supports a configuration file for customizing behavior.

该工具支持通过配置文件自定义行为。

Initialize Config

初始化配置

bash

npx mac-cleaner-cli config --init

This creates a config file at

~/.mac-cleaner-cli/config.json

(exact location may vary).

bash

npx mac-cleaner-cli config --init

此命令会在

~/.mac-cleaner-cli/config.json

创建配置文件（具体位置可能有所不同）。

View Current Config

查看当前配置

bash

npx mac-cleaner-cli config --show

bash

npx mac-cleaner-cli config --show

Configuration Options

配置选项

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

json

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

虽然README中未完整记录确切的配置 schema，但典型选项可能包括：

json

{
  "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:

bash

undefined

问题： 清理某些文件时出现“Permission denied”（权限不足）。

解决方案：

bash

undefined

Some system files may require elevated permissions

部分系统文件可能需要提升权限

The tool generally runs as current user

工具通常以当前用户身份运行

For DNS flush:

如需刷新DNS缓存：

sudo npx mac-cleaner-cli maintenance --dns

undefined

sudo npx mac-cleaner-cli maintenance --dns

undefined

Categories Not Showing

类别未显示

Problem: Risky categories aren't visible.

Solution:

bash

undefined

问题： 高风险类别不可见。

解决方案：

bash

undefined

Use the --risky flag

使用--risky参数

npx mac-cleaner-cli --risky

undefined

npx mac-cleaner-cli --risky

undefined

File Picker Not Available

文件选择器不可用

Problem: Can't drill down into a category.

Solution:

bash

undefined

问题： 无法深入查看某个类别。

解决方案：

bash

undefined

Not all categories support file-level selection

并非所有类别都支持文件级选择

Supported: User Cache Files, Temporary Files, System Log Files,

支持的类别：用户缓存文件、临时文件、系统日志文件、

Development Cache, Browser Cache, Homebrew Cache

开发缓存、浏览器缓存、Homebrew缓存

Use -f to force file picker for all categories

使用-f参数强制为所有类别启用文件选择器

npx mac-cleaner-cli -f

undefined

npx mac-cleaner-cli -f

undefined

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

问题： 扫描耗时很久。

解决方案：

对于文件众多的Mac来说，这属于正常现象
若有自定义配置，可考虑排除大型目录
工具会高效扫描常见位置

Accidental Deletion

误删文件

Problem: Deleted something important.

Solution:

bash

undefined

问题： 删除了重要内容。

解决方案：

bash

undefined

Check if backups are enabled in config

检查配置中是否启用了备份功能

npx mac-cleaner-cli backup --list

Restore from Time Machine or system backups

从Time Machine或系统备份中恢复

Always verify selections before confirming cleanup

确认清理前务必仔细核对所选内容

undefined

undefined

Docker Cleanup Issues

Docker清理问题

Problem: Docker containers still running after cleanup attempt.

Solution:

bash

undefined

问题： 尝试清理后Docker容器仍在运行。

解决方案：

bash

undefined

Stop all containers first

先停止所有容器

docker stop $(docker ps -aq)

Then run cleaner

再运行清理工具

npx mac-cleaner-cli

undefined

npx mac-cleaner-cli

undefined

Tool Not Found After Global Install

全局安装后找不到工具

Problem:

mac-cleaner-cli: command not found

Solution:

bash

undefined

问题： 出现

mac-cleaner-cli: command not found

。

解决方案：

bash

undefined

Ensure npm global bin is in PATH

确保npm全局bin目录在PATH中

npm config get prefix

Add to PATH: export PATH="$PATH:$(npm config get prefix)/bin"

添加到PATH：export PATH="$PATH:$(npm config get prefix)/bin"

Or use npx

或使用npx

npx mac-cleaner-cli

undefined

npx mac-cleaner-cli

undefined

Development Integration

开发集成

Using in Scripts

在脚本中使用

typescript

// 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

typescript

// 示例：潜在的程序化用法（请查看实际API）
import { scan, clean } from 'mac-cleaner-cli';

// 注意：该工具主要面向CLI
// 请查看包的导出内容以确认程序化API是否可用

Building from Source

从源码构建

bash

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

bash

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

undefined

bun run build

undefined

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

mac-cleaner-cli/
├── src/               # TypeScript源码
├── tests/             # 测试文件
├── assets/            # 横幅图片、资源文件
├── package.json       # 依赖项与脚本
├── tsconfig.json      # TypeScript配置
└── README.md          # 文档

Best Practices

最佳实践

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

清理前务必检查：使用交互式复选框确认即将删除的内容
从安全类别开始：先不使用
```
--risky
```
参数运行工具
使用文件资源管理器：按→深入查看类别，选择特定文件夹
保留备份：在配置中启用关键数据的备份设置
定期维护：每周/每月运行一次，避免磁盘空间不足
使用内置卸载器：使用工具自带的卸载器替代拖到回收站的方式
监控释放空间：清理后查看摘要，跟踪清理效果

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

100%离线：无网络请求，无遥测数据收集
开源：所有代码可在https://github.com/guhcostan/mac-cleaner-cli查看审计
无需root权限：以当前用户身份运行（除了使用sudo刷新DNS缓存）
依赖项极少：仅5个运行时依赖项，由Socket.dev监控
默认安全：高风险操作隐藏在
```
--risky
```
参数后

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

仅支持macOS：专为macOS设计
需要Node.js：请查看
```
package.json
```
确认兼容性（通常要求Node.js 16+）
Windows替代工具：Windows用户可使用
```
windows-cleaner-cli
```

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 /

undefined

ncdu /

undefined

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

GitHub仓库：https://github.com/guhcostan/mac-cleaner-cli
npm包：https://www.npmjs.com/package/mac-cleaner-cli
问题反馈：https://github.com/guhcostan/mac-cleaner-cli/issues
讨论区：https://github.com/guhcostan/mac-cleaner-cli/discussions
许可证：MIT

mac-cleaner-cli-disk-cleanup

Original

Translation

mac-cleaner-cli Skill

mac-cleaner-cli 工具

What It Does

功能介绍

Installation

安装方法

One-Time Usage (Recommended)

一次性使用（推荐）

Global Installation

全局安装

For Development

开发环境安装

Key Commands

核心命令

Interactive Cleanup (Main Command)

交互式清理（主命令）

Basic interactive mode - scan and clean

基础交互模式 - 扫描并清理

Include risky categories (downloads, iOS backups, duplicates, large files)

包含高风险类别（下载文件、iOS备份、重复文件、大文件）

Force file picker for ALL categories

强制为所有类别启用文件选择器

Show absolute paths

显示绝对路径

Disable progress bars

禁用进度条

App Uninstaller

应用卸载器

Uninstall apps completely with preferences and support files

彻底卸载应用，包括偏好设置和支持文件

Maintenance Tasks

维护任务

Flush DNS cache (may require sudo)

刷新DNS缓存（可能需要sudo权限）

Free purgeable space

释放可清除空间

Category Management

类别管理

List all available cleaning categories

列出所有可用的清理类别

Configuration

配置管理

Initialize configuration file

初始化配置文件

Show current configuration

显示当前配置

Backup Management

备份管理

List all backups

列出所有备份

Clean old backups

清理旧备份

Help and Version

帮助与版本信息

Show version

显示版本号

Show help

显示帮助信息

Categories

清理类别

Safe Categories (Always Safe)

安全类别（始终安全）

Moderate Categories (Generally Safe)

中等风险类别（通常安全）

Risky Categories (Requires --risky Flag)

高风险类别（需使用--risky参数）

Common Usage Patterns

常见使用场景

Quick Disk Cleanup

快速磁盘清理

Run interactively, select common safe categories

以交互模式运行，选择常见的安全类别

Select: Trash, Browser Cache, Temporary Files, User Cache Files, Development Cache

选择：回收站、浏览器缓存、临时文件、用户缓存文件、开发缓存

Developer Cleanup

开发者专属清理

Clean development caches and orphaned node_modules

Risky Categories (Requires
`--risky`
Flag)

高风险类别（需使用
`--risky`
参数）