CLI parameters¶

The reference below walks the live command tree at build time, so every help screen matches the documented release. Each command section is anchored by its command path (like #mpm-install), the same scheme the readme and benchmark pages link to.

Help screen¶

$ mpm --help
Usage: mpm [OPTIONS] COMMAND [ARGS]...

  CLI options shared by all subcommands.

Package manager selection:
  Use these options to restrict the subcommand to a subset of managers.

  - By default, mpm will evaluate all managers supported on the current platform.
  - Use the --<manager-id> selectors to restrict target to a subset of managers.
  - To remove a manager from the selection, use --no-<manager-id> selectors.
  - Order of the selectors is preserved for priority-sensitive subcommands.
  - Exclusion of a manager always takes precedence over its inclusion.
  --apk               Select Alpine apk.
  --apm               Select Atom apm. (DEPRECATED)
  --apt               Select Debian apt.
  --apt-mint          Select Linux Mint apt.
  --asdf              Select asdf.
  --brew              Select Homebrew Formulae.
  --cask              Select Homebrew Cask.
  --choco             Select Chocolatey.
  --composer          Select PHP Composer.
  --conda             Select Conda.
  --deb-get           Select deb-get.
  --dnf               Select Fedora DNF.
  --dnf5              Select Fedora DNF5.
  --emerge            Select Gentoo emerge.
  --eopkg             Select Solus eopkg.
  --flatpak           Select Flatpak.
  --fwupd             Select Linux fwupd.
  --gem               Select RubyGems.
  --guix              Select GNU Guix.
  --macports          Select MacPorts.
  --mas               Select Mac App Store.
  --mise              Select mise.
  --nix               Select Nix.
  --npm               Select Node npm.
  --pacaur            Select Arch Linux pacaur.
  --pacman            Select Arch Linux pacman.
  --pacstall          Select Pacstall.
  --paru              Select Arch Linux paru.
  --pip               Select Python pip.
  --pipx              Select Python pipx.
  --pkcon             Select PackageKit.
  --pkg               Select FreeBSD pkg.
  --pnpm              Select Node pnpm.
  --ports             Select FreeBSD Ports Collection.
  --pwsh-gallery      Select PowerShell Gallery.
  --scoop             Select Scoop.
  --sdkman            Select SDKMAN.
  --sfsu              Select Scoop sfsu.
  --snap              Select Snap.
  --stew              Select stew.
  --sun-tools         Select Solaris SVR4 package tools.
  --tazpkg            Select TazPkg.
  --uv                Select Python uv.
  --uvx               Select Python uvx.
  --winget            Select WinGet.
  --xbps              Select Void XBPS.
  --yarn-berry        Select Yarn Berry.
  --yarn              Select Yarn Classic.
  --yay               Select Arch Linux yay.
  --yum               Select Fedora YUM.
  --zerobrew          Select zerobrew.
  --zypper            Select openSUSE Zypper.
  --apt-cyg           Select apt-cyg.
  --cargo             Select Rust cargo.
  --cave              Select cave.
  --chromebrew        Select Chromebrew.
  --cpan              Select Perl CPAN.
  --fink              Select Fink.
  --gh-ext            Select GitHub CLI extensions.
  --opkg              Select opkg.
  --pkg-tools         Select OpenBSD pkg tools.
  --pkgin             Select Pkgin.
  --slapt-get         Select slapt-get.
  --soar              Select Soar.
  --sorcery           Select Sorcery.
  --steamcmd          Select Valve SteamCMD.
  --swupd             Select Clear Linux Software Updater.
  --tlmgr             Select TeX Live Manager.
  --topgrade          Select Topgrade.
  --urpmi             Select urpmi.
  --vscode            Select Visual Studio Code.
  --vscodium          Select VSCodium.
  --no-apk            Deselect Alpine apk.
  --no-apm            Deselect Atom apm. (DEPRECATED)
  --no-apt            Deselect Debian apt.
  --no-apt-mint       Deselect Linux Mint apt.
  --no-asdf           Deselect asdf.
  --no-brew           Deselect Homebrew Formulae.
  --no-cask           Deselect Homebrew Cask.
  --no-choco          Deselect Chocolatey.
  --no-composer       Deselect PHP Composer.
  --no-conda          Deselect Conda.
  --no-deb-get        Deselect deb-get.
  --no-dnf            Deselect Fedora DNF.
  --no-dnf5           Deselect Fedora DNF5.
  --no-emerge         Deselect Gentoo emerge.
  --no-eopkg          Deselect Solus eopkg.
  --no-flatpak        Deselect Flatpak.
  --no-fwupd          Deselect Linux fwupd.
  --no-gem            Deselect RubyGems.
  --no-guix           Deselect GNU Guix.
  --no-macports       Deselect MacPorts.
  --no-mas            Deselect Mac App Store.
  --no-mise           Deselect mise.
  --no-nix            Deselect Nix.
  --no-npm            Deselect Node npm.
  --no-pacaur         Deselect Arch Linux pacaur.
  --no-pacman         Deselect Arch Linux pacman.
  --no-pacstall       Deselect Pacstall.
  --no-paru           Deselect Arch Linux paru.
  --no-pip            Deselect Python pip.
  --no-pipx           Deselect Python pipx.
  --no-pkcon          Deselect PackageKit.
  --no-pkg            Deselect FreeBSD pkg.
  --no-pnpm           Deselect Node pnpm.
  --no-ports          Deselect FreeBSD Ports Collection.
  --no-pwsh-gallery   Deselect PowerShell Gallery.
  --no-scoop          Deselect Scoop.
  --no-sdkman         Deselect SDKMAN.
  --no-sfsu           Deselect Scoop sfsu.
  --no-snap           Deselect Snap.
  --no-stew           Deselect stew.
  --no-sun-tools      Deselect Solaris SVR4 package tools.
  --no-tazpkg         Deselect TazPkg.
  --no-uv             Deselect Python uv.
  --no-uvx            Deselect Python uvx.
  --no-winget         Deselect WinGet.
  --no-xbps           Deselect Void XBPS.
  --no-yarn-berry     Deselect Yarn Berry.
  --no-yarn           Deselect Yarn Classic.
  --no-yay            Deselect Arch Linux yay.
  --no-yum            Deselect Fedora YUM.
  --no-zerobrew       Deselect zerobrew.
  --no-zypper         Deselect openSUSE Zypper.
  --no-apt-cyg        Deselect apt-cyg.
  --no-cargo          Deselect Rust cargo.
  --no-cave           Deselect cave.
  --no-chromebrew     Deselect Chromebrew.
  --no-cpan           Deselect Perl CPAN.
  --no-fink           Deselect Fink.
  --no-gh-ext         Deselect GitHub CLI extensions.
  --no-opkg           Deselect opkg.
  --no-pkg-tools      Deselect OpenBSD pkg tools.
  --no-pkgin          Deselect Pkgin.
  --no-slapt-get      Deselect slapt-get.
  --no-soar           Deselect Soar.
  --no-sorcery        Deselect Sorcery.
  --no-steamcmd       Deselect Valve SteamCMD.
  --no-swupd          Deselect Clear Linux Software Updater.
  --no-tlmgr          Deselect TeX Live Manager.
  --no-topgrade       Deselect Topgrade.
  --no-urpmi          Deselect urpmi.
  --no-vscode         Deselect Visual Studio Code.
  --no-vscodium       Deselect VSCodium.
  -a, --all-managers  Force evaluation of all managers implemented by mpm,
                      including those not supported by the current platform or
                      deprecated. Still applies filtering by --<manager-id> /
                      --no-<manager-id> options before calling the subcommand.
  -x, --xkcd          Preset manager selection as defined by XKCD #1654.
                      Equivalent to: --pip --brew --npm --dnf --apt --steamcmd.

Manager options:
  --ignore-auto-updates / --include-auto-updates
                                 Report all outdated packages, including those
                                 tagged as auto-updating. Only applies to
                                 outdated and upgrade subcommands.  [default:
                                 ignore-auto-updates]
  --stop-on-error / --continue-on-error
                                 Stop right away or continue operations on
                                 manager CLI error.  [default: continue-on-
                                 error]
  --sudo / --no-sudo             Force running privileged manager operations
                                 with (or without) sudo. Unset by default,
                                 letting each manager decide: system managers
                                 (apt, dnf, pacman, ...) escalate, user-level
                                 managers do not. When escalation is needed on a
                                 terminal, mpm authenticates once up front
                                 instead of prompting mid-run; off a terminal,
                                 managers needing root fail fast rather than
                                 stalling.
  -d, --dry-run                  Do not actually perform any action, just
                                 simulate CLI calls.
  -t, --timeout INTEGER RANGE    Maximum duration in seconds for each CLI call.
                                 Applies to every manager and operation. When
                                 unset, a per-operation default is used instead:
                                 a short cap for read-only queries (installed,
                                 outdated, search) and a longer one for state-
                                 changing operations (install, upgrade, remove,
                                 sync, cleanup).  [x>=0]
  --cooldown DURATION            Refuse to install or upgrade any package
                                 version published more recently than this
                                 duration, as a mitigation against supply-chain
                                 attacks. Accepts a friendly duration ('7 days',
                                 '1 week', '12h'), an ISO 8601 duration ('P7D',
                                 'PT12H'), or an RFC 3339 absolute timestamp
                                 ('2024-05-01T00:00:00Z'). Only honored by
                                 managers with native release-age support (npm,
                                 pip, pipx, pnpm, uv, uvx, yay); the others are
                                 skipped unless --allow-unsupported-managers is
                                 set.  [default: (disabled)]
  --require-cooldown-support / --allow-unsupported-managers
                                 When --cooldown is set, whether to require each
                                 manager to natively enforce it. The default
                                 (--require-cooldown-support) skips managers
                                 that cannot, so nothing slips in unguarded
                                 (fail-closed). --allow-unsupported-managers
                                 runs install and upgrade on them anyway,
                                 trading the supply-chain safeguard for broader
                                 manager coverage.  [default: require-cooldown-
                                 support]
  -j, --jobs [auto|max|INTEGER]  Maximum number of managers to run concurrently.
                                 Defaults to one less than the CPU count; set 1
                                 to run sequentially. Applies to read-only
                                 queries (installed, outdated, search),
                                 maintenance commands (sync, cleanup, upgrade
                                 --all), and the state changers (install,
                                 remove, upgrade, restore), which fan out across
                                 managers while running each manager's own
                                 packages one at a time. Installing a package
                                 left untied to a manager stays sequential.
                                 [default: auto]

Output options:
  --description             Show package description in results. Shorthand for
                            adding the 'description' column to 'mpm search'; an
                            explicit --columns selection wins.
  -s, --sort-by [manager_id|manager_name|package_id|package_name|version]
                            Sort results by this field. Repeat to add tie-
                            breakers in priority order, like '-s manager_id -s
                            package_id'.  [default: manager_id]
  --summary / --no-summary  Print an end-of-run summary on stderr: a count line
                            of per-manager totals plus any subcommand-specific
                            follow-up notes (like SBOM enrichment and merge
                            counts). Defaults on; use --no-summary to silence.
                            [default: summary]
  --network / --no-network  Opt into network calls during the run. Today this
                            only affects 'mpm sbom', which uses the flag to
                            query OSV.dev for vulnerability data and attach it
                            to the rendered document. Responses are cached on
                            disk so repeat runs are fast. Defaults off; the
                            offline path remains the default. Note: when
                            enabled, this transmits the package inventory to the
                            queried services.  [default: no-network]
  --suggest-contribs / --no-suggest-contribs
                            Print a contribution invitation when a user override
                            targets a field that likely indicates an upstream
                            detection bug (cli_names, cli_search_path,
                            requirement, version_cli_options, version_regexes).
                            [default: suggest-contribs]

Xbar/SwiftBar options:
  --bar-plugin-path  Print location of the Xbar/SwiftBar plugin.

Other options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --config CONFIG_PATH         Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/mpm/{*.toml,*.yaml,*.yml,*.js
                               on,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.
                               toml}]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config FILE       Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.
  --accessible                 Accessibility mode: disable colors and render
                               tables in a plain, screen-reader-friendly format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [dark|dracula|light|manpage|monokai|nord|solarized_dark]
                               Color theme used for help screens.  [default:
                               dark]
  --show-params                Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
                               Rendering style of tables.  [default: rounded-
                               outline]
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --man                        Show the command's man page (roff) and exit.
  --version                    Show the version and exit.
  -0, --zero-exit              Always exit with a status code of 0, even when
                               problems are found.
  -h, --help                   Show this message and exit.

Explore subcommands:
  managers            List every registered package manager and check its
                      presence on the system.
  installed (list)    List installed packages.
  outdated            List outdated packages.
  search              Search packages.
  which (locate)      Locate CLIs on system.
  config-template     Print per-manager overrides as a TOML config template.

Maintenance subcommands:
  install             Install a package.
  upgrade (update)    Upgrade packages.
  remove (uninstall)  Remove a package.
  sync                Sync local package info.
  cleanup             Cleanup local data.

Package snapshots subcommands:
  dump (backup, lock, freeze, snapshot)
                      Snapshot installed packages to a TOML manifest or a
                      Brewfile.
  restore             Install packages referenced in TOML files.

SBOM subcommands:
  sbom                Export installed packages to a SBOM document.

Other commands:
  help                Show help for a command.

`mpm cleanup`¶

$ mpm cleanup --help
Usage: mpm cleanup [OPTIONS]

  Cleanup local data, temporary artifacts and removes orphaned dependencies.

Options:
  -h, --help  Show this message and exit.

`mpm config-template`¶

$ mpm config-template --help
Usage: mpm config-template [OPTIONS] [apk|apm|apt|apt-cyg|apt-mint|asdf|brew|car
                           go|cask|cave|choco|chromebrew|composer|conda|cpan|deb
                           -get|dnf|dnf5|emerge|eopkg|fink|flatpak|fwupd|gem|gh-e
                           xt|guix|macports|mas|mise|nix|npm|opkg|pacaur|pacman|
                           pacstall|paru|pip|pipx|pkcon|pkg|pkg-
                           tools|pkgin|pnpm|ports|pwsh-
                           gallery|scoop|sdkman|sfsu|slapt-
                           get|snap|soar|sorcery|steamcmd|stew|sun-tools|swupd|t
                           azpkg|tlmgr|topgrade|urpmi|uv|uvx|vscode|vscodium|win
                           get|xbps|yarn|yarn-berry|yay|yum|zerobrew|zypper]...

  Print the overridable attributes of one or more managers as a TOML config
  template.

  Each block is a valid ``[mpm.managers.<id>]`` section ready to paste into a
  standalone config file or a ``[tool.mpm]`` ``pyproject.toml`` block. The
  output lists every overridable field with its current value so it doubles as
  the canonical reference for what each manager exposes: prune the rows that
  don't apply and customize the rest.

  With no positional arguments, every maintained (non-deprecated) manager is
  dumped. Pass one or more manager IDs to restrict the output.

Options:
  -h, --help  Show this message and exit.

`mpm dump`¶

$ mpm dump --help
Usage: mpm dump [OPTIONS] [OUTPUT_PATH]
Aliases: backup, lock, freeze, snapshot

  Dump installed packages to a TOML manifest or a Brewfile.

  By default emits TOML, one section per manager (one entry per package, keyed
  by package ID, with the installed version as the value). Pass ``--brewfile``
  to emit a Brewfile compatible with ``brew bundle install``.

  With no [OUTPUT_PATH] argument, writes to stdout. TOML files are readable by
  ``mpm restore``.

  With ``--query``, restrict the snapshot to installed packages whose ID or name
  matches it (fuzzy by default, verbatim with ``--exact``).

  ``--merge`` and ``--update-version`` operate on an existing TOML file; both
  require the [OUTPUT_PATH] argument and neither is valid with ``--brewfile``.

Options:
  --toml                  Emit a TOML manifest with one section per manager.
                          Default.  [default: toml]
  --brewfile              Emit a Brewfile that `brew bundle install` can
                          consume. Only managers natively supported by brew
                          bundle are included (brew, cask, mas, vscode, npm,
                          cargo, uv, winget, flatpak). Other managers are
                          tallied in the header and excluded from the output.
  --overwrite, --force, --replace
                          Allow the output file to be silently wiped out if it
                          already exists.
  --header / --no-header  Include a metadata + warning comment block at the top
                          of the output.  [default: header]
  --merge                 TOML only. Read the provided file and add each new
                          entry to it. Requires the [OUTPUT_PATH] argument.
  --update-version        TOML only. Read the provided file and update each
                          existing entry with the version currently installed on
                          the system. Requires the [OUTPUT_PATH] argument.
  --query QUERY           Only snapshot installed packages whose ID or name
                          matches QUERY. Fuzzy by default (case-insensitive,
                          tokenized); see --exact.
  --exact / --fuzzy       With --query, require a verbatim match on the package
                          ID or name instead of the default fuzzy match. No
                          effect without --query.  [default: fuzzy]
  -h, --help              Show this message and exit.

`mpm help`¶

$ mpm help --help
Usage: mpm help [OPTIONS] [COMMAND_PATH]...

  Show help for a command.

Options:
  --search TEXT  Search all subcommands for matching options or descriptions.
  -h, --help     Show this message and exit.

`mpm install`¶

$ mpm install --help
Usage: mpm install [OPTIONS] PACKAGES_SPECS...

  Install one or more packages.

  This subcommand is sensible to the order of the package managers selected by
  the user.

  Installation will first proceed for all the packages found to be tied to a
  specific manager. Which is the case for packages provided with precise package
  specifiers (like purl). This will also happens in situations in which a
  tighter selection of managers is provided by the user.

  For packages whose manager is not known, or if multiple managers are
  candidates for the installation, mpm will try to find the best manager to
  install it with.

  Installation will be attempted with each manager, in the order they were
  selected. If a search for the package ID returns no result from the highest-
  priority manager, we will skip the installation and try the next available
  managers in the order of their priority.

Positional arguments:
  PACKAGES_SPECS...  A mix of plain <package_id>, simple <package_id@version>
                     specifiers or full <pkg:npm/left-pad> purls.

Options:
  -h, --help  Show this message and exit.

`mpm installed`¶

$ mpm installed --help
Usage: mpm installed [OPTIONS] [QUERY]
Aliases: list

  List all packages installed on the system by each manager.

  With an optional ``QUERY``, restrict the listing to installed packages whose
  ID or name matches it. The match is fuzzy by default (case-insensitive,
  tokenized); ``--exact`` requires a verbatim match on the package ID or name.

Options:
  --exact / --fuzzy  With a QUERY, only keep packages whose ID or name matches
                     it exactly, instead of the default case-insensitive,
                     tokenized (fuzzy) match. No effect without a QUERY.
                     [default: fuzzy]
  -d, --duplicates   Only list installed packages sharing the same ID. Implies
                     `--sort-by package_id` to make duplicates easier to compare
                     between themselves.
  --columns [package_id,package_name,manager_id,installed_version]
                     Restrict and reorder table columns, SQL SELECT-style.
                     Comma-separated list of column IDs. Default: all columns in
                     canonical order.
  -h, --help         Show this message and exit.

`mpm managers`¶

$ mpm managers --help
Usage: mpm managers [OPTIONS]

  List every package manager detected on the system.

  Only reports by default all managers supported on the current platform. To
  include unsupported and deprecated managers in the report, use the ``--all-
  managers`` flag.

  User's own selection configuration are intentionally ignored, so a manager
  dropped from regular operations is still visible here for troubleshooting. To
  narrow down the report to a subset of managers, pass the same selectors as for
  other subcommands (e.g. ``--pip`` or ``--no-apt``).

Options:
  --columns [manager_id,manager_name,supported,cli,executable,version]
              Restrict and reorder table columns, SQL SELECT-style. Comma-
              separated list of column IDs. Default: all columns in canonical
              order.
  -h, --help  Show this message and exit.

`mpm outdated`¶

$ mpm outdated --help
Usage: mpm outdated [OPTIONS] [QUERY]

  List available package upgrades and their versions for each manager.

  With an optional ``QUERY``, restrict the listing to outdated packages whose ID
  or name matches it. The match is fuzzy by default (case-insensitive,
  tokenized); ``--exact`` requires a verbatim match on the package ID or name.

Options:
  --exact / --fuzzy  With a QUERY, only keep packages whose ID or name matches
                     it exactly, instead of the default case-insensitive,
                     tokenized (fuzzy) match. No effect without a QUERY.
                     [default: fuzzy]
  --plugin-output    Output results for direct consumption by an Xbar/SwiftBar-
                     compatible plugin. The layout is dynamic and depends on
                     environment variables set by either Xbar or SwiftBar.
  --columns [package_id,package_name,manager_id,installed_version,latest_version]
                     Restrict and reorder table columns, SQL SELECT-style.
                     Comma-separated list of column IDs. Default: all columns in
                     canonical order.
  -h, --help         Show this message and exit.

`mpm remove`¶

$ mpm remove --help
Usage: mpm remove [OPTIONS] PACKAGES_SPECS...
Aliases: uninstall

  Remove one or more packages.

  Packages recognized by multiple managers will be remove with each of them. You
  can fine-tune this behavior with more precise package specifiers (like purl)
  and/or tighter selection of managers.

  Packages unrecognized by any selected manager will be skipped.

Positional arguments:
  PACKAGES_SPECS...  A mix of plain <package_id>, simple <package_id@version>
                     specifiers or full <pkg:npm/left-pad> purls.

Options:
  -h, --help  Show this message and exit.

`mpm restore`¶

$ mpm restore --help
Usage: mpm restore [OPTIONS] TOML_FILES...

  Read TOML files then install or upgrade each package referenced in them.

Options:
  -h, --help  Show this message and exit.

`mpm sbom`¶

$ mpm sbom --help
Usage: mpm sbom [OPTIONS] [EXPORT_PATH]

  Export list of installed packages to a SPDX or CycloneDX file.

  With ``--query``, restrict the export to installed packages whose ID or name
  matches it (fuzzy by default, verbatim with ``--exact``).

Options:
  --spdx / --cyclonedx   SBOM standard to export to.  [default: spdx]
  --format [json|xml|yaml|tag|rdf]
                         File format of the export. Defaults to JSON for
                         <stdout>. If not provided, will be autodetected from
                         file extension.
  --overwrite, --force, --replace
                         Allow the target file to be silently wiped out if it
                         already exists.
  --bundled / --minimal  Bundled mode (the default) queries each manager for
                         richer metadata (license, supplier, homepage,
                         checksums, declared dependencies) and merges per-
                         package upstream SBOM documents into the aggregate when
                         the manager publishes them (like Homebrew's
                         HOMEBREW_SBOM=1 per-formula files). Minimal mode lists
                         installed packages with the bare inventory data (name,
                         version, purl) and skips the metadata extractors
                         entirely. Bundled mode is slower because it may shell
                         out or read on-disk SBOM files per package; pick
                         --minimal for fast inventory snapshots.  [default:
                         bundled]
  --query QUERY          Only export installed packages whose ID or name matches
                         QUERY. Fuzzy by default (case-insensitive, tokenized);
                         see --exact.
  --exact / --fuzzy      With --query, require a verbatim match on the package
                         ID or name instead of the default fuzzy match. No
                         effect without --query.  [default: fuzzy]
  -h, --help             Show this message and exit.

`mpm search`¶

$ mpm search --help
Usage: mpm search [OPTIONS] QUERY

  Search each manager for a package ID, name or description matching the query.

Options:
  --extended / --id-name-only  Extend search to description, instead of
                               restricting it to package ID and name. Implies
                               --description.  [default: id-name-only]
  --exact / --fuzzy            Only returns exact matches on package ID or name.
                               [default: fuzzy]
  --refilter / --no-refilter   Let mpm refilters managers' search results.
                               [default: refilter]
  --columns [package_id,package_name,manager_id,latest_version,description]
                               Restrict and reorder table columns, SQL SELECT-
                               style. Comma-separated list of column IDs.
                               Default: all columns in canonical order.
  -h, --help                   Show this message and exit.

`mpm sync`¶

$ mpm sync --help
Usage: mpm sync [OPTIONS]

  Sync local package metadata and info from external sources.

Options:
  -h, --help  Show this message and exit.

`mpm upgrade`¶

$ mpm upgrade --help
Usage: mpm upgrade [OPTIONS] [PACKAGES_SPECS]...
Aliases: update

  Upgrade one or more outdated packages.

  All outdated package will be upgraded by default if no specifiers are provided
  as arguments. I.e. assumes -A/--all option if no [PACKAGES_SPECS]....

  Packages recognized by multiple managers will be upgraded with each of them.
  You can fine-tune this behavior with more precise package specifiers (like
  purl) and/or tighter selection of managers.

  Packages unrecognized by any selected manager will be skipped.

Positional arguments:
  [PACKAGES_SPECS]...  A mix of plain <package_id>, simple <package_id@version>
                       specifiers or full <pkg:npm/left-pad> purls.

Options:
  -A, --all   Upgrade all outdated packages. Will make the command ignore
              package IDs provided as parameters.
  -h, --help  Show this message and exit.

`mpm which`¶

$ mpm which --help
Usage: mpm which [OPTIONS] CLI_NAMES...
Aliases: locate

  Search from the user's environment all CLIs matching the query.

  This is mpm's own version of the `which -a` UNIX command, used internally to
  locate binaries for each manager. It is exposed as a subcommand for
  convenience and to help troubleshoot CLI resolution logic.

  Compared to the venerable `which` command, this will respect the additional
  path configured for each package manager. It will ignore files that are empty
  (0 size). On Windows, it additionally suppress the default lookup in the
  current directory, which takes precedence on other paths.

Options:
  --columns [manager_id,priority,cli_path,symlink]
              Restrict and reorder table columns, SQL SELECT-style. Comma-
              separated list of column IDs. Default: all columns in canonical
              order.
  -h, --help  Show this message and exit.

Command	Description
`mpm`	CLI options shared by all subcommands
`mpm cleanup`	Cleanup local data
`mpm config-template`	Print per-manager overrides as a TOML config template
`mpm dump`	Snapshot installed packages to a TOML manifest or a Brewfile
`mpm help`	Show help for a command
`mpm install`	Install a package
`mpm installed`	List installed packages
`mpm managers`	List every registered package manager and check its presence on the system
`mpm outdated`	List outdated packages
`mpm remove`	Remove a package
`mpm restore`	Install packages referenced in TOML files
`mpm sbom`	Export installed packages to a SBOM document
`mpm search`	Search packages
`mpm sync`	Sync local package info
`mpm upgrade`	Upgrade packages
`mpm which`	Locate CLIs on system

Man pages¶

The directive below renders a live index of every man page emitted by click_extra.sphinx from the click_extra_manpages config in conf.py. Each entry links to the browser-viewable HTML sibling produced when mandoc (preferred) or groff is on PATH during the docs build. The raw .1 files sit next to the HTML siblings in /man/ and are also bundled as mpm-manpages.tar.gz on every GitHub release.

mpm(1) — CLI options shared by all subcommands.
mpm-cleanup(1) — Cleanup local data.
mpm-config-template(1) — Print per-manager overrides as a TOML config template.
mpm-dump(1) — Snapshot installed packages to a TOML manifest or a Brewfile.
mpm-help(1) — Show help for a command.
mpm-install(1) — Install a package.
mpm-installed(1) — List installed packages.
mpm-managers(1) — List every registered package manager and check its presence on the system.
mpm-outdated(1) — List outdated packages.
mpm-remove(1) — Remove a package.
mpm-restore(1) — Install packages referenced in TOML files.
mpm-sbom(1) — Export installed packages to a SBOM document.
mpm-search(1) — Search packages.
mpm-sync(1) — Sync local package info.
mpm-upgrade(1) — Upgrade packages.
mpm-which(1) — Locate CLIs on system.

`meta_package_manager.cli` API¶

The mpm command-line interface.

Defines the Click command group and its subcommands. Each operation subcommand (installed, outdated, install, upgrade, remove, …) selects the managers from meta_package_manager.pool that implement the matching meta_package_manager.capabilities.Operations action, runs it across all of them, and renders the aggregated, multi-manager result.

meta_package_manager.cli.XKCD_MANAGER_ORDER = ('pip', 'brew', 'npm', 'dnf', 'apt', 'steamcmd')¶

Sequence of package managers as defined by XKCD #1654: Universal Install Script.

See the corresponding implementation rationale in issue #10.

meta_package_manager.cli.COOLDOWN_SUPPORTED_MANAGERS = ('npm', 'pip', 'pipx', 'pnpm', 'uv', 'uvx', 'yay')¶

IDs of the managers that natively enforce a release-age mpm --cooldown.

Derived from the pool so the --cooldown help text never drifts from the set of managers that actually carry a cooldown_env_var: adding cooldown support to a manager surfaces it here automatically.

meta_package_manager.cli.MANAGERS_COLUMNS: tuple[tuple[ColumnSpec, str | None], ...] = ((ColumnSpec(id='manager_id', label='Manager ID', description="Manager's identifier."), SortableField.MANAGER_ID), (ColumnSpec(id='manager_name', label='Name', description="Manager's common name."), SortableField.MANAGER_NAME), (ColumnSpec(id='supported', label='Supported', description='Support status on the current platform.'), None), (ColumnSpec(id='cli', label='CLI', description="Location of the manager's binary on the system."), None), (ColumnSpec(id='executable', label='Executable', description='Whether the binary is executable.'), None), (ColumnSpec(id='version', label='Version', description="Manager's self-reported version, and the unsatisfied requirement when stale."), SortableField.VERSION))¶: Columns of the mpm managers table.

meta_package_manager.cli.INSTALLED_COLUMNS: tuple[tuple[ColumnSpec, str | None], ...] = ((ColumnSpec(id='package_id', label='Package ID', description="Package's identifier."), SortableField.PACKAGE_ID), (ColumnSpec(id='package_name', label='Name', description="Package's common name."), SortableField.PACKAGE_NAME), (ColumnSpec(id='manager_id', label='Manager', description='Manager reporting the package.'), SortableField.MANAGER_ID), (ColumnSpec(id='installed_version', label='Installed version', description='Version currently installed.'), SortableField.VERSION))¶: Columns of the mpm installed table.

meta_package_manager.cli.OUTDATED_COLUMNS: tuple[tuple[ColumnSpec, str | None], ...] = ((ColumnSpec(id='package_id', label='Package ID', description="Package's identifier."), SortableField.PACKAGE_ID), (ColumnSpec(id='package_name', label='Name', description="Package's common name."), SortableField.PACKAGE_NAME), (ColumnSpec(id='manager_id', label='Manager', description='Manager reporting the package.'), SortableField.MANAGER_ID), (ColumnSpec(id='installed_version', label='Installed version', description='Version currently installed.'), SortableField.VERSION), (ColumnSpec(id='latest_version', label='Latest version', description='Version available for upgrade.'), None))¶: Columns of the mpm outdated table.

meta_package_manager.cli.SEARCH_COLUMNS: tuple[tuple[ColumnSpec, str | None], ...] = ((ColumnSpec(id='package_id', label='Package ID', description="Package's identifier."), SortableField.PACKAGE_ID), (ColumnSpec(id='package_name', label='Name', description="Package's common name."), SortableField.PACKAGE_NAME), (ColumnSpec(id='manager_id', label='Manager', description='Manager reporting the match.'), SortableField.MANAGER_ID), (ColumnSpec(id='latest_version', label='Latest version', description='Latest version available.'), SortableField.VERSION), (ColumnSpec(id='description', label='Description', description='Package description, for managers that provide one. Out of the default selection: select it explicitly or pass --description.'), None))¶

Columns of the mpm search table.

The description column exists in the registry (so --columns can select it) but stays out of the default selection unless --description (or --extended, which searches descriptions) is passed.

meta_package_manager.cli.WHICH_COLUMNS: tuple[tuple[ColumnSpec, str | None], ...] = ((ColumnSpec(id='manager_id', label='Manager ID', description='Manager whose search path found the binary.'), SortableField.MANAGER_ID), (ColumnSpec(id='priority', label='Priority', description="Rank of the match in the manager's search path."), None), (ColumnSpec(id='cli_path', label='CLI path', description='Location of the matched binary.'), None), (ColumnSpec(id='symlink', label='Symlink destination', description='Resolved target when the match is a symlink.'), None))¶: Columns of the mpm which table.

meta_package_manager.cli.column_specs(columns)[source]¶

Extract the bare ColumnSpec tuple from a column registry.

Return type:: tuple[ColumnSpec, ...]

meta_package_manager.cli.print_projected_table(ctx, columns, rows, sort_by, default_ids=None)[source]¶

Render dict rows as a table projected through --columns.

The --columns selection restricts and reorders the rendering, SQL-SELECT-style; click-extra’s ColumnsOption already validated it against the same columns registry, so unknown IDs never reach this point. default_ids is the selection applied when the user passed none (search uses it to hide the description column unless --description); None keeps every column in canonical order.

Sorting stays on mpm’s global --sort-by: a sort field whose column is projected out is simply skipped by print_sorted_table().

Return type:: None

meta_package_manager.cli.is_stdout(filepath)[source]¶

Check if a file path is set to stdout.

Prevents the creation of a - file in the current directory.

Return type:: bool

meta_package_manager.cli.prep_path(filepath)[source]¶

Prepare the output file parameter for Click’s echo function.

Return type:: IO | None

meta_package_manager.cli.print_serialized_and_exit(ctx, data)[source]¶

Render data in the active serialization format, then exit.

When the global --table-format resolves to one of the structured serialization formats (JSON, YAML, TOML, XML, …), serialize data under the shared mpm root element and stop the program. Otherwise return, so the caller falls through to its human-friendly table rendering.

Return type:: None

meta_package_manager.cli.guard_existing_output(ctx, output_path, *, overwrite)[source]¶

Block clobbering an existing output file unless overwrite is set.

Warns and exits with code 2 when output_path already exists and the user did not pass --overwrite/--force/--replace. No-op when the file is absent. Callers handle the stdout case separately.

Return type:: None

meta_package_manager.cli.update_manager_selection(ctx, param, value)[source]¶

Update global selection list of managers in the context.

Accumulate and merge all manager selectors to form the initial population enforced by the user.

Return type:: None

meta_package_manager.cli.single_manager_selectors()[source]¶: Dynamiccaly creates a dedicated flag selector alias for each manager.

meta_package_manager.cli.bar_plugin_path(ctx, param, value)[source]¶

Print the location of the Xbar/SwiftBar plugin.

Returns the normalized path of the standalone bar_plugin.py script that is distributed with this Python module. This is made available under the mpm --bar-plugin-path option.

Notice that the fully-qualified home directory get replaced by its shorthand (~) if applicable:

the full /home/user/.python/site-packages/mpm/bar_plugin.py path is simplified to ~/.python/site-packages/mpm/bar_plugin.py,
but /usr/bin/python3.10/mpm/bar_plugin.py is returned as-is.

meta_package_manager.cli.cooldown_permits(manager)[source]¶

Decide whether a release-introducing operation may run on manager.

Returns True when no cooldown is active, when the manager can enforce it natively, or when the user opted out of the requirement with --allow-unsupported-managers. Returns False (after logging the skip) when an active cooldown cannot be enforced and the requirement still holds, so the caller leaves the manager alone rather than letting a freshly-published version slip in.

Return type:: bool

meta_package_manager.cli.package_label(spec)[source]¶

Render a spec as package_id or package_id@version for trail output.

Return type:: str

meta_package_manager.cli.exit_on_failures(ctx)[source]¶

Exit with code 1 to report the per-package failures collected this run.

Follows the linter convention where findings gate automation, unless the user opted out with -0/--zero-exit: the run then keeps its 0 exit code, and the critical: summary already printed stays the durable record. Usage and configuration errors are unaffected: they exit 2 regardless, as genuine execution failures.

Return type:: None

CLI parameters¶

Help screen¶

mpm cleanup¶

mpm config-template¶

mpm dump¶

mpm help¶

mpm install¶

mpm installed¶

mpm managers¶

mpm outdated¶

mpm remove¶

mpm restore¶

mpm sbom¶

mpm search¶

mpm sync¶

mpm upgrade¶

mpm which¶