DOCSEARCHbyAlgolia
Submit Docs

mac-cleaner-cli

repository·main·Indexed 23 days ago

https://github.com/guhcostan/mac-cleaner-cli

A free, open-source macOS command-line tool (v1.3.5) designed to free up disk space by removing caches, logs, Homebrew leftovers, Xcode DerivedData, and other junk files. It features an interactive TUI for granular file selection, automated modes for CI/CD or cron jobs, and system maintenance utilities such as flushing DNS cache and freeing purgeable space.

Tokens
7K
Snippets
16
Records
59
Agent score
80%

What's inside mac-cleaner-cli

  1. Understand the File Picker System architecture

    main

    The File Picker System is an interactive TUI (Terminal User Interface) designed for granular file selection using directory grouping. It is built on @inquirer/core and manages two distinct types of state:

    1. UI State (FilePickerStatesStore): Manages ephemeral navigation data like caretPosition, expandLimits (how many files are visible in a directory), and isShowingFiles (pane visibility). This state persists as you navigate between categories.
    2. Global Selection State: Manages what is actually being cleaned. It uses selectedCategories (a Set of category names) and selectedFilesByCategory (a Map of category names to Sets of file paths).

    The system uses a File Display Pipeline to transform raw scan results into a navigable list:

    1. Group by Directory: Items are grouped by parent directory and sorted by size (descending).
    2. Apply Expand Limits: Visibility limits are applied to each directory.
    3. Format Display Items: The list is flattened into a structure containing headers, file entries, and expand hints.

  2. Understand Category-File Coupling and Selection Behavior

    main

    The File Picker enforces strict coupling between categories and their constituent files to ensure data integrity:

    • Automatic Category Selection: Selecting an individual file automatically selects its parent category.
    • Automatic Category Deselection: Deselecting the last remaining file in a category automatically deselects that category.
    • Category Deselection: Deselecting a category clears all file selections within that category.
    • Directory Toggling: Pressing d in the Files Pane toggles all files within the current directory (where the caret is located) but does not affect the overall category selection state.
    • Isolation: Selections are isolated by category; operations in one category do not impact others, and state is preserved when switching between them.

  3. Use Interactive Mode

    main

    The default mode is interactive. It provides a UI to scan, select, and clean files.

    Navigation Controls:

    • ↑↓: Navigate
    • ←: Go back
    • →: Enter/Drill down into a category
    • space: Select/Deselect item
    • a: Select all
    • i: Invert selection
    • ⏎: Submit/Confirm

    Drill-down Support: You can use → to drill into specific folders/files for the following categories:

    • User Cache Files
    • Temporary Files
    • System Log Files
    • Development Cache
    • Browser Cache
    • Homebrew Cache
    npx mac-cleaner-cli

  5. Automate cleaning with non-interactive commands

    main

    For CI/CD or cron jobs, use specific commands to bypass the interactive UI.

    Scan only:

    npx mac-cleaner-cli scan

    Scan with JSON output (for scripts):

    npx mac-cleaner-cli scan --json
npx mac-cleaner-cli scan --json --verbose # includes item paths

    Clean specific categories without prompts:

    npx mac-cleaner-cli clean --categories trash,browser-cache,homebrew --yes

    Dry run (preview changes):

    npx mac-cleaner-cli clean --categories dev-cache --dry-run

    Clean all safe items automatically:

    npx mac-cleaner-cli clean --all --yes

  7. Reference File Picker Configuration Constants

    main

    The following constants control the behavior and appearance of the file picker:

    FILES_PAGE_SIZE = 6; // Centered pagination window
DIR_VIS_CHILD_LIMIT = 5; // Default files shown per directory
EXPAND_INCREMENT = 10; // Files added per expand action
FILE_NAME_WIDTH = 35; // Filename truncation width

  8. Understand safety levels for cleaning

    main

    The tool categorizes files into three safety levels, which determine how they are displayed and how they should be handled during cleaning:

    • safe (🟢): Always safe to delete.
    • moderate (🟡): Generally safe to delete.
    • risky (🔴): Use with caution. Requires the --unsafe flag (or equivalent logic) to proceed with cleaning.

    When scanning, these levels help you understand the potential impact of removing the identified files.

  9. Use the mac-cleaner-cli interactive mode

    main
    Running the mac-cleaner-cli command without a sub-command launches the interactive mode. This mode allows you to scan, select, and clean files through a guided interface. You can pass global options to modify the interactive experience.

  10. Configure mac-cleaner-cli via JSON configuration files

    main

    You can customize the behavior of mac-cleaner-cli by creating a configuration file. The CLI looks for configuration in the following locations (in order of priority):

    1. ~/.maccleanerrc
    2. ~/.config/mac-cleaner-cli/config.json

    If you provide a custom path via the loadConfig function, it must reside within your home directory or ~/.config for security reasons. The configuration file must be a valid JSON object and cannot exceed 100KB.

  11. Perform system maintenance tasks

    main

    The maintenance command allows you to perform specific system cleanup tasks.

    • Flush DNS cache: npx mac-cleaner-cli maintenance --dns (may require sudo)
    • Free purgeable space: npx mac-cleaner-cli maintenance --purgeable
    npx mac-cleaner-cli maintenance --dns