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.
--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.
--mas Select Mac App Store.
--mise Select mise.
--nix Select Nix.
--npm Select Node npm.
--pacaur Select Arch Linux pacaur. (DEPRECATED)
--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.
--sun-tools Select Solaris SVR4 package tools.
--tazpkg Select TazPkg.
--uv Select Python uv.
--uvx Select Python uvx.
--volta Select Volta. (DEPRECATED)
--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.
--zypper Select openSUSE Zypper.
--apt-cyg Select apt-cyg. (DEPRECATED)
--cargo Select Rust cargo.
--cave Select cave.
--choco Select Chocolatey.
--chromebrew Select Chromebrew.
--cpan Select Perl CPAN.
--fink Select Fink.
--gh-ext Select GitHub CLI extensions.
--macports Select MacPorts.
--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.
--stew Select stew.
--swupd Select Clear Linux Software Updater. (DEPRECATED)
--tlmgr Select TeX Live Manager.
--topgrade Select Topgrade.
--urpmi Select urpmi.
--vscode Select Visual Studio Code.
--vscodium Select VSCodium.
--zerobrew Select zerobrew.
--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-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-mas Deselect Mac App Store.
--no-mise Deselect mise.
--no-nix Deselect Nix.
--no-npm Deselect Node npm.
--no-pacaur Deselect Arch Linux pacaur. (DEPRECATED)
--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-sun-tools Deselect Solaris SVR4 package tools.
--no-tazpkg Deselect TazPkg.
--no-uv Deselect Python uv.
--no-uvx Deselect Python uvx.
--no-volta Deselect Volta. (DEPRECATED)
--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-zypper Deselect openSUSE Zypper.
--no-apt-cyg Deselect apt-cyg. (DEPRECATED)
--no-cargo Deselect Rust cargo.
--no-cave Deselect cave.
--no-choco Deselect Chocolatey.
--no-chromebrew Deselect Chromebrew.
--no-cpan Deselect Perl CPAN.
--no-fink Deselect Fink.
--no-gh-ext Deselect GitHub CLI extensions.
--no-macports Deselect MacPorts.
--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-stew Deselect stew.
--no-swupd Deselect Clear Linux Software Updater. (DEPRECATED)
--no-tlmgr Deselect TeX Live Manager.
--no-topgrade Deselect Topgrade.
--no-urpmi Deselect urpmi.
--no-vscode Deselect Visual Studio Code.
--no-vscodium Deselect VSCodium.
--no-zerobrew Deselect zerobrew.
-a, --all-managers Force evaluation of all managers implemented by mpm,
including those not supported by the current platform or
unmaintained. 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.
-p, --plan Print the exact package-manager commands each
state-changing operation would run, without
running them. Read-only queries (installed,
outdated, search) still run, so install, remove
and upgrade --all resolve to the commands they
would actually execute against real system
state. The plan prints to stdout, one copy-
pasteable command per line.
-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.
--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]
-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]
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]
--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]
--tree Show the tree of nested subcommands and exit.
--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.
orphans List orphaned 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.
doctor (check, diagnose) Diagnose managers health.
SBOM subcommands:
sbom Export installed packages to a SBOM document.
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.
Other commands:
help Show help for a command.
mpm cleanup¶
$ mpm cleanup --help
Usage: mpm cleanup [OPTIONS]
Cleanup local data and temporary artifacts.
The work decomposes into cumulative categories, each with a two-sided flag
pair: `--orphans/--skip-orphans` (system-wide orphan sweep), `--cache/--skip-
cache` (caches, downloads and left-overs) and `--repair/--skip-repair` (local
state verification). Positive flags narrow the run to exactly the listed
categories; skip flags subtract from the default selection.
A plain `cleanup` runs the cache and repair categories and never removes a
package: the orphan sweep is the one destructive category, so it only runs on
an explicit `--orphans`, uniformly across managers, just as `remove` keeps its
dependency cascade behind the same flag. A manager with no native sweep verb
but a native orphan listing gets the sweep synthesized: list the orphans,
remove them one by one, and repeat until none are left. Managers supporting
none of the selected categories are skipped.
Options:
--orphans / --skip-orphans Remove orphaned packages (those nothing depends on
anymore) using each manager's system-wide sweep,
native or synthesized from its orphan listing. The
only category removing packages, so it never runs
unless requested. [default: skip-orphans]
--cache / --skip-cache Prune caches, downloads and other left-over
artifacts. The broadest category: for most
managers the whole cleanup amounts to it.
[default: cache]
--repair / --skip-repair Verify and repair the manager's local installation
state (like `flatpak repair`). [default: repair]
-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|volta|vscode|vscodi
um|winget|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 manager (those not flagged
unmaintained) is dumped. Pass one or more manager IDs to restrict the output.
Options:
-h, --help Show this message and exit.
mpm doctor¶
$ mpm doctor --help
Usage: mpm doctor [OPTIONS]
Aliases: check, diagnose
Run each manager's native self-diagnosis and relay its report.
Read-only: nothing is modified. Each manager runs its own diagnostic verb
(`brew doctor`, `pip check`, `pacman --database --check`, `npm doctor`, ...),
its health is read from that command's exit code, and its report — the
diagnosis being the product, not something `mpm` can parse — is relayed
verbatim to `<stdout>`, one section per manager with findings.
The trail marks each manager `✓` (healthy) or `✗` (problems found), and the
run exits non-zero when any manager reports problems, so the command can gate
a CI job. `-0`/`--zero-exit` keeps the exit code at `0`. Managers with no
diagnostic verb are skipped.
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 target 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 keep 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 unmaintained 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 orphans¶
$ mpm orphans --help
Usage: mpm orphans [OPTIONS] [QUERY]
List packages installed as dependencies that no package requires anymore.
Each manager reports its orphans through its own native read-only query
(`pacman --query --deps --unrequired`, `brew autoremove --dry-run`, `dnf
repoquery --unneeded`, ...): `mpm` builds no dependency graph of its own.
Review the list here, then act on it with `mpm cleanup --orphans`.
With an optional `QUERY`, restrict the listing to orphaned 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]
--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 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.
With `--orphans`, each package is removed together with the dependencies it
alone pulled in, mapped to the manager's native cascade verb (``apt remove
--auto-remove`, `pacman --remove --recursive`, `dnf autoremove``, ...).
Managers with no such verb remove the package only.
Positional arguments:
PACKAGES_SPECS... A mix of plain <package_id>, simple <package_id@version>
specifiers or full <pkg:npm/left-pad> purls.
Options:
--orphans Also remove the dependencies the package pulled in that no other
package needs, using each manager's native cascade verb. Managers
without one remove the package only.
-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 keep 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 keep packages whose ID or name matches the
query exactly, instead of the default case-
insensitive, tokenized (fuzzy) match. [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 |
|---|---|
CLI options shared by all subcommands |
|
Cleanup local data |
|
Print per-manager overrides as a TOML config template |
|
Diagnose managers health |
|
Snapshot installed packages to a TOML manifest or a Brewfile |
|
Show help for a command |
|
Install a package |
|
List installed packages |
|
List every registered package manager and check its presence on the system |
|
List orphaned packages |
|
List outdated packages |
|
Remove a package |
|
Install packages referenced in TOML files |
|
Export installed packages to a SBOM document |
|
Search packages |
|
Sync local package info |
|
Upgrade packages |
|
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-doctor(1)— Diagnose managers health.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-orphans(1)— List orphaned packages.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: the group and its shared plumbing.
Defines the Click command group (global options, manager selection, the
GlobalOptions state every subcommand reads) and the helpers several
subcommand modules share: the inventory snapshot, the per-package action
engine, the failure gates and the file-output guards.
The subcommands themselves live in one module per help section —
meta_package_manager.cli_explore (the read-only queries),
meta_package_manager.cli_maintenance (the state changers and
diagnostics), meta_package_manager.cli_snapshots (manifest export and
replay) and meta_package_manager.cli_sbom — imported at the bottom of
this module so their @mpm.command registrations run. Each subcommand
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.
- class meta_package_manager.cli.GlobalOptions(all_managers, user_selection, user_drops, selected_managers, description, summary, network, timeout)[source]¶
Bases:
objectGlobal options and selection state every subcommand reads from
ctx.obj.Built once by the
mpmgroup body, after the eager option callbacks have accumulated the manager selectors into the transientctx.objdict this instance replaces (seeupdate_manager_selection()).- user_selection: list[str] | None¶
Managers explicitly selected by the user, in priority order, or
None.
- selected_managers: Callable[[...], Iterator[PackageManager]]¶
Resolve the target managers, applying selection and manager-level options.
- 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
--cooldownhelp text never drifts from the set of managers that actually carry acooldown_env_var: adding cooldown support to a manager surfaces it here automatically.
- 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:
- meta_package_manager.cli.prep_path(filepath)[source]¶
Prepare the output file parameter for Click’s echo function.
- meta_package_manager.cli.guard_existing_output(ctx, output_path, *, overwrite)[source]¶
Block clobbering an existing output file unless
overwriteis set.Warns and exits with code 2 when
output_pathalready 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:
- 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:
- 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-pathoption.Notice that the fully-qualified home directory get replaced by its shorthand (
~) if applicable:the full
/home/user/.python/site-packages/mpm/bar_plugin.pypath is simplified to~/.python/site-packages/mpm/bar_plugin.py,but
/usr/bin/python3.10/mpm/bar_plugin.pyis returned as-is.
- meta_package_manager.cli.query_option(f)¶
--queryfilter of the inventory exporters (dump,sbom).
- meta_package_manager.cli.query_exact_option(f)¶
--exactrefinement ofquery_option.
- meta_package_manager.cli.overwrite_option(f)¶
Opt-in clobbering of an existing output file (
dump,sbom); seeguard_existing_output().
- meta_package_manager.cli.package_label(spec)[source]¶
Render a spec as
package_idorpackage_id@versionfor trail output.- Return type:
- meta_package_manager.cli.fail_unless_zero_exit(ctx, message)[source]¶
Print the durable
critical: :message:` record, then exit `1unless-0/--zero-exitopted out of the gate.The shared failure gate of the action commands (
exit_on_failures()) anddoctor: the summary always prints, following the linter convention where findings gate automation, and-0keeps the exit code at0with the printed summary staying the durable record. Usage and configuration errors are unaffected: they exit2regardless, as genuine execution failures.- Return type:
- meta_package_manager.cli.exit_on_failures(ctx, verb, failures)[source]¶
Report the per-package
failurescollected this run and exit non-zero.A no-op when
failuresis empty. Otherwise routes the deduplicated, sortedCould not {verb}: ...summary throughfail_unless_zero_exit(). Shared by every action command (install,remove,upgrade <packages>,restore).- Return type: