MacPackMate

MacPackMate / CLI

Terminal / CLI

Everything the app does. In your terminal.

The command-line tool macpackmate is the actual logic of MacPackMate – the app is the interface on top and launches exactly this tool. Same data, same logic: for developers, admins and anything you can automate.

01

One tool. Two interfaces.

--same

Same logic.

The app calls the embedded tool and reads its output. Whatever you click, you can type – and script.

--lang

English & German.

Language follows MACPACKMATE_LANG=en|de. Coloured in the style of Claude Code: warm orange, ⏺ steps, an animated status line. NO_COLOR and FORCE_COLOR are respected.

--json

Built for scripts.

--json gives machine-readable output; long commands then stream NDJSON events. Every output has a JSON Schema (2020-12).

guide

Manual included.

macpackmate guide shows the whole manual in your terminal – the same as ⌘? in the app.

02

Set up in two lines.

The tool lives inside the app. One symlink brings it into your PATH:

macpackmate — zsh
❯ mkdir -p ~/.local/bin
❯ ln -sf /Applications/MacPackMate.app/Contents/Helpers/macpackmate ~/.local/bin/macpackmate

If ~/.local/bin is not on your PATH yet, add this line to ~/.zshrc:

macpackmate — zsh
❯ export PATH="$HOME/.local/bin:$PATH"

03

Commands, sorted by task.

An overview taken from macpackmate --help. macpackmate help <command> shows the details of each one.

Overview & search

  • scanlist every package in parallel (default command)
  • infoevery detail of a package
  • searchsearch all package managers
  • managerswhich managers are installed – install missing ones
  • versionsall versions of a package
  • changesrelease notes before you update

Change

  • installinstall, optionally a specific version
  • updateone by one or --all
  • uninstallafter checking what depends on it
  • reinstall · rollbackreinstall · back to the previous version
  • pin · unpin · pinsfreeze a version
  • link · unlinkput a Homebrew formula on the PATH (node@22)
  • migrate · adopt · adoptablepip → pipx/uv · apps → casks
  • reason · extras · variants · tapinstall reason, extra packages, variants, taps

Maintenance

  • cleanupclean up, with a dry run
  • unusedprobably unused
  • dependentswho depends on whom
  • conflictsPATH conflicts, duplicates, fixes
  • doctor · remedycheck health and fix it
  • update-managersupdate the managers themselves
  • resumecontinue after a power failure

Security & background

  • auditvulnerabilities (OSV.dev), --fail-on for CI
  • checkupdates and vulnerabilities, what’s new since the last check
  • backgrounddaily check as a LaunchAgent

Backup & migration

  • exportwrite a pack file or Brewfile
  • importrestore a pack file or Brewfile, --exact-versions, --install-managers, --dry-run

Services

  • servicesHomebrew background services
  • autostartLaunchAgents and LaunchDaemons: view, switch on/off, remove, log

Order & knowledge

  • note · noteswhy is this installed?
  • profilegroup packages
  • historyevery action with versions and log
  • guidethe whole manual in the terminal
  • licensetrial and licence

04

A few examples.

All examples are real commands – --dry-run shows what would happen first.

macpackmate — zsh
❯ macpackmate scan --outdated-only
❯ macpackmate search ripgrep
❯ macpackmate update --all --dry-run
❯ macpackmate audit --fail-on high
❯ macpackmate export -o MacPackMate.json
❯ macpackmate import MacPackMate.json --dry-run
❯ macpackmate export --format brewfile -o Brewfile
❯ macpackmate autostart list
❯ macpackmate guide

Real output: the manual

This is what macpackmate guide prints in version 0.47.0 (terminal without colours, verbatim).

macpackmate — zsh
❯ macpackmate guide
MacPackMate Handbook

TOPIC             TITLE
getting-started   Getting Started
app               Using the App
install           Search & Install
versions          Versions, Rollback & Reinstall
release-notes     What’s New Before Updating
background        Background Check & Menu Bar
adopt             Take Over
security          Security Check
services          Services
autostart         Launch Items
conflicts         Conflicts & PATH
doctor            Health Check
history           History
library           Notes & Profiles
edits             More Changes
updating          Updating & Pinning
uninstalling      Uninstalling & Dependencies
cleanup           Cleaning Up
unused            Probably Unused
backup            Backup & Restore
privileges        Administrator Rights & Security
managers          Package Managers in Detail
runtimes          Language Versions, SDKs & Docker
cli               Command-Line Reference
automation        JSON & Automation
troubleshooting   Troubleshooting
license           Trial & Licence
about             About MacPackMate
disclaimer        Disclaimer

Show a topic: macpackmate guide <topic>

05

Made for automation.

Stable exit codes, JSON Schemas and no stored passwords make the tool fit for cron, CI and dotfiles.

JSON and events

scan, managers, info and others print a document with --json. Long-running commands such as update, install or import print one event per line in JSON mode; the last line is always the result.

macpackmate — zsh
❯ macpackmate scan --json --skip-outdated | jq '.packages[] | select(.isOutdated) | .id'
❯ macpackmate update --all --json | jq -c 'select(.type == "result") | .summary'

Exit codes

0ok
1error
3blocked (dependents or confirmation)
4password prompt cancelled
5vulnerability found (audit --fail-on)
6trial over, licence needed
64wrong usage

Environment variables

MACPACKMATE_LANGen or de – language of all output
MACPACKMATE_AUTHterminal – ask for administrator rights via sudo in the terminal
MACPACKMATE_NO_HISTORY1 – do not record actions in the history
GITHUB_TOKENhigher request limit for GitHub release notes
NO_COLOR · FORCE_COLORcolours off – or on even when output is piped

The safety promise applies here too.

  • Actions are visible first: commands appear before they run.
  • --dry-run shows the plan as a dry run.
  • Before removing anything, MacPackMate checks dependents.
  • update --all skips pinned packages.
  • No stored passwords: sudo in the terminal, the native admin dialog in the app.
  • The security check runs only on command – just package names and versions go to OSV.dev.

Part of the app. Same licence.

The tool is part of MacPackMate: a 14-day trial with everything, then read-only mode. Scanning, searching, viewing and dry runs keep working; installing, updating and removing need a licence (exit code 6). €34 via Polar.

Manual: command-line reference (macpackmate guide cli) · ← Back to the home page