Metadata-Version: 2.4
Name: macmaint
Version: 2026.4.4
Summary: macOS maintenance CLI — updates, cleanup, and system maintenance
Project-URL: Homepage, https://github.com/sussdorff/macmaint
Project-URL: Repository, https://github.com/sussdorff/macmaint
Project-URL: Changelog, https://github.com/sussdorff/macmaint/blob/main/CHANGELOG.md
Author-email: Malte Sussdorff <shiki@shikigami.de>
License-Expression: MIT
License-File: LICENSE
Keywords: cleanup,cli,homebrew,macos,maintenance
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# macmaint

[![PyPI version](https://img.shields.io/pypi/v/macmaint.svg)](https://pypi.org/project/macmaint/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
uv tool install macmaint
```

Or with pipx:

```bash
pipx install macmaint
```

## Prerequisites

| Requirement | Notes |
|-------------|-------|
| macOS 13 Ventura or later | macOS-only by design |
| Python 3.13+ | Installed automatically by uv/pipx |
| [Homebrew](https://brew.sh) | Optional — needed for `update` and `cleanup` brew tasks |
| [mas](https://github.com/mas-cli/mas) | Optional — `brew install mas` for App Store updates |
| [uv](https://docs.astral.sh/uv/) | Optional — for `uv tool upgrade --all` in `update` |
| Docker, npm | Optional — `cleanup` prunes these if available |

## Quick start

```bash
# 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` |
| `macmaint cleanup` | Empty trash, clear user caches, purge pip/npm/uv caches, remove Xcode DerivedData, 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

```bash
# 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 cleanup --no-caches       # skip user caches
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.

```toml
[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/*"]
```

## 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.

## License

MIT — see [LICENSE](LICENSE).
