meta_package_manager.cli module

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, progress, timeout)

Bases: object

Global options and selection state every subcommand reads from ctx.obj.

Built once by the mpm group body, after the eager option callbacks have accumulated the manager selectors into the transient ctx.obj dict this instance replaces (see update_manager_selection()).

all_managers: bool

Include unsupported and unmaintained managers in the selection.

user_selection: list[str] | None

Managers explicitly selected by the user, in priority order, or None.

user_drops: set[str] | None

Managers explicitly excluded by the user, or None.

selected_managers: Callable[[...], Iterator[PackageManager]]

Resolve the target managers, applying selection and manager-level options.

description: bool

Show package description in results.

summary: bool

Print the end-of-run summary on stderr.

network: bool

Allow network calls during the run.

progress: bool

Whether progress indicators may render, after mpm’s output-mode gating.

The same value the group folds into each manager’s progress flag, exposed for the subcommands resolving their own managers instead of going through selected_managers (managers, whose only wait is the detection round the pool runs for it). The widget still auto-gates on an interactive stderr.

timeout: int | None

User-set maximum duration in seconds for each CLI call, or None.

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

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

Derived from the pool so the --cooldown help text never drifts from the set of managers that actually enforce the window, whether through a native cooldown_env_var or through the per-package release_date probe: adding cooldown support to a manager surfaces it here automatically.

meta_package_manager.cli.RELEASE_INTRODUCING_OPERATIONS = frozenset({'install', 'upgrade'})

Operation names that bring new package versions onto the system.

The per-package cooldown hold of cooldown_hold_reason only applies to these: remove introduces nothing, and read-only queries are never blocked. restore rides the install operation name, so it is covered.

meta_package_manager.cli.guard_existing_output(ctx, output_path, *, overwrite)

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)

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()

Dynamiccaly creates a dedicated flag selector alias for each manager.

meta_package_manager.cli.bar_plugin_path(ctx, param, value)

Print the location of the SwiftBar/Xbar 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.query_option(f)

--query filter of the inventory exporters (dump, sbom).

meta_package_manager.cli.query_exact_option(f)

--exact refinement of query_option.

meta_package_manager.cli.overwrite_option(f)

Opt-in clobbering of an existing output file (dump, sbom); see guard_existing_output().

meta_package_manager.cli.package_label(spec)

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

Return type:

str

meta_package_manager.cli.fail_unless_zero_exit(ctx, message)

Print the durable critical: :message:` record, then exit `1 unless -0/--zero-exit opted out of the gate.

The shared failure gate of the action commands (exit_on_failures()) and doctor: the summary always prints, following the linter convention where findings gate automation, and -0 keeps the exit code at 0 with the printed summary staying the durable record. Usage and configuration errors are unaffected: they exit 2 regardless, as genuine execution failures.

Return type:

None

meta_package_manager.cli.exit_on_failures(ctx, verb, failures)

Report the per-package failures collected this run and exit non-zero.

A no-op when failures is empty. Otherwise routes the deduplicated, sorted Could not {verb}: ... summary through fail_unless_zero_exit(). Shared by every action command (install, remove, upgrade <packages>, restore).

Return type:

None