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

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

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.