macmaint 2026.4.8

macOS maintenance CLI — updates, cleanup, and system maintenance

macmaint

A macOS maintenance CLI that keeps your system clean and up-to-date with a single command. Run macmaint to update Homebrew packages, the Mac App Store, uv-managed tools, clear caches, trim log files, vacuum Mail.app, flush DNS, and show you which apps you haven't opened in months.

Everything is idempotent and safe to run as a daily cron job. Use --dry-run to preview every action before it executes.

Install

uv tool install macmaint

Or with pipx:

pipx install macmaint

Prerequisites

Requirement	Notes
macOS 13 Ventura or later	macOS-only by design
Python 3.13+	Installed automatically by uv/pipx
Homebrew	Optional — needed for update and cleanup brew tasks
mas	Optional — brew install mas for App Store updates
uv	Optional — for uv tool upgrade --all in update
bun	Optional — for bun update -g (global JS CLIs installed via bun) in update
npm	Optional — for npm update -g (global JS CLIs like @openai/codex) in update and npm cache cleanup in cleanup
Docker	Optional — cleanup prunes this if available

Quick start

# Check which tools are wired up on your machine
macmaint doctor

# Preview all maintenance tasks without executing anything
macmaint --dry-run

# Run everything
macmaint

Subcommands

Command	What it does
macmaint update	Homebrew update/upgrade/cleanup + Mac App Store upgrades + uv tool upgrade --all + bun update -g + npm update -g + npm audit on ~/package.json
macmaint cleanup	Empty trash, clear user caches, purge pip/npm/uv caches, remove Xcode DerivedData, npm prune on ~/package.json, prune Docker, delete old logs
macmaint maintenance	Flush DNS cache, vacuum Mail.app envelope index, repair user permissions, rebuild Spotlight index, free APFS purgeable space
macmaint apps	Show all installed apps sorted by last used date (GUI apps, Homebrew formulae, Steam games)
macmaint doctor	Check which optional tools are available and what macmaint can do

Common flags

# Preview mode — show what would run, no changes
macmaint --dry-run
macmaint cleanup --dry-run

# Skip specific tasks
macmaint update --no-brew          # skip Homebrew
macmaint update --no-mas           # skip App Store
macmaint update --no-uv-tools      # skip uv tool upgrade --all
macmaint update --no-bun           # skip bun update -g
macmaint update --no-npm-globals   # skip npm update -g
macmaint update --no-npm-audit     # skip npm audit on ~/package.json
macmaint update --no-extras        # skip user-defined extras
macmaint cleanup --no-caches       # skip user caches
macmaint cleanup --no-npm-prune    # skip npm prune on ~/package.json
macmaint cleanup --no-docker       # skip Docker prune

# App usage filtering
macmaint apps --days 90            # highlight apps unused for 90+ days
macmaint apps --unused             # show only unused apps
macmaint apps --size               # include disk footprint column

Configuration

Create ~/.config/macmaint/config.toml to override defaults. All keys are optional.

[cleanup]
# Which cache directories under ~/Library/Caches/ to clear.
# Defaults to a curated safe list (Safari, Chrome, VSCode, JetBrains IDEs, etc.)
cache-allowlist = [
    "com.apple.Safari",
    "com.google.Chrome",
    "com.apple.WebKit.WebContent",
    "pip",
    "com.spotify.client",
    "com.microsoft.VSCode",
    "com.jetbrains.intellij",
    "PyCharm",
    "CLion",
    "Rider",
    "WebStorm",
    "DataGrip",
]

# Remove log files older than this many days from ~/Library/Logs/
# Default: 7
log-retention-days = 7

[apps]
# Glob patterns for Steam library volumes to scan in addition to ~/Library.
# Default: ["/Volumes/*"]
steam-volumes = ["/Volumes/*"]

[[extras]]
# Run after built-in tasks for this phase: update | cleanup | maintenance
phase = "update"
name = "dcg"
cmd = "curl -fsSL 'https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh?$(date +%s)' | bash -s -- --easy-mode --quiet"

[[extras]]
phase = "maintenance"
name = "custom-health-check"
cmd = "~/bin/health-check"
when = "command_exists:health-check"

Extras hooks

[[extras]] lets you register your own commands for update, cleanup, or maintenance. macmaint runs them after the built-in tasks for that phase.

• Use --dry-run to print the extra command without executing it.
• Use --no-extras to skip all configured extras for that invocation.
• A false when = "command_exists:foo" gate skips the extra cleanly.
• If one extra fails, macmaint logs the error and continues with the remaining extras.

For the current dcg workaround, put the update extra above into ~/.config/macmaint/config.toml and run macmaint update. macmaint will keep handling brew/mas/uv/bun/npm first, then reinstall dcg via the upstream curl | bash flow.

Caveats

• Mac App Store (mas upgrade) requires sudo. macmaint runs sudo mas upgrade; you will be prompted for your password. This is a mas limitation.

• macmaint apps uses the Screen Time database (knowledgeC.db) for last-used dates. This database is protected by macOS privacy controls. For accurate results, grant Full Disk Access to the terminal app running macmaint (System Settings → Privacy & Security → Full Disk Access). Without access, macmaint falls back to Spotlight metadata, which is less accurate.

• macmaint apps --size is slow for large app libraries. It runs du on each app bundle plus associated Library directories. Expect 30–120 seconds for 100+ apps.

• macOS-only. macmaint uses macOS-specific tools (mdls, tmutil, dscacheutil, diskutil, sqlite3) and will not run on Linux or Windows.

• npm audit and npm prune only run when ~/package.json exists. If you install JS CLIs into ~/node_modules via a top-level ~/package.json, macmaint update will surface high-severity advisories there and macmaint cleanup will remove orphaned installed packages no longer declared in the manifest. With no ~/package.json, both tasks are no-ops.

License

MIT — see LICENSE.