Whalebrew¶

ID: whalebrew
Link: Repository
Version requirement: >= 0.4.1
Platforms: 🐧 Linux · 🍎 macOS
Operations: installed · search · install · remove
purl types: pkg:whalebrew/
CLI name: whalebrew
Issues and PRs: 📦 manager: whalebrew
Source: whalebrew.py

Whalebrew, installing Docker images as commands.

A package is a Docker image, identified as the listing prints it: whalebrew/wget, or hello-world:linux where a tag was given. Whalebrew writes one small YAML file per image into its install directory, named after the command the image provides, and runs the image through docker run each time that command is called. The command is reported as the package name.

install needs a running Docker daemon the user can reach, and refuses an image that declares no ENTRYPOINT. mpm install looks the image up through search first, which only reaches the registries Whalebrew searches: install an image from anywhere else with whalebrew install itself, and the listing reports it like any other.

Packages go to /usr/local/bin by default, which a regular user cannot write to on Linux. Point WHALEBREW_INSTALL_PATH, or install_path in ~/.whalebrew/config.yaml, at a directory of your own, like ~/.whalebrew/bin.

What `mpm` adds to `whalebrew`¶

Through mpm, whalebrew gains --exact and --extended search, to narrow to exact names or match descriptions.

Bigger still, mpm reaches across every manager at once: mpm installed and mpm outdated cover whalebrew alongside every other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Your `whalebrew` commands, in `mpm`¶

You already know whalebrew: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…	With `whalebrew`	With `mpm`
List what’s installed	`whalebrew list --no-headers`	`mpm --whalebrew installed`
Search for a package	`whalebrew search wget`	`mpm --whalebrew search wget`
Install a package	`whalebrew install --assume-yes whalebrew/wget`	`mpm install pkg:whalebrew/whalebrew/wget`
Remove a package	`whalebrew uninstall --assume-yes wget`	`mpm remove pkg:whalebrew/wget`

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations¶

Operation	Supported	Notes
`installed`	✅
`outdated`	❌	Nothing reports a newer image without pulling it.
`orphans`
`search`	✅	Exact and extended search backfilled by `mpm`.
`install`	✅
`upgrade`	❌	Upgrading is pulling the image with Docker, not a Whalebrew verb.
`upgrade_all`	❌	Upgrading is pulling each image with Docker.
`remove`	✅
`sync`
`cleanup`
`doctor`

Configuration¶

Ignore whalebrew on the mpm CLI by passing the --no-whalebrew option.
Ignore it for every run in your configuration:
```
[mpm]
whalebrew = false
```

Raise the timeout of all whalebrew calls:

[mpm.overrides.whalebrew]
timeout = 900

Run mpm config-template whalebrew to print all overridable settings for your configuration file:

[mpm.overrides.whalebrew]
cli_names = [
    "whalebrew",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = []
pre_cmds = []
requirement = ">=0.4.1"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "version",
]
version_regexes = [
    "^Whalebrew[ \\t]+(?P<version>\\d+\\.\\d+\\.\\d+)",
]

Recipes¶

A few jobs you would otherwise script around whalebrew, one mpm command each:

Snapshot and clone a machine: mpm --whalebrew dump whalebrew.toml, then mpm restore whalebrew.toml on the next one.
Export a compliance SBOM: mpm --whalebrew sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation¶

mpm runs this manager as the current user and never prepends sudo by default. Flip the policy for its privileged operations with --sudo or the per-manager sudo override.

None of its operations is privileged.

See privilege escalation for the full policy.

Cooldown¶

State of Whalebrew’s release-age gating, from the cooldown support table:

Status: ❌ None

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

Registry: Docker Hub
Retraction: Author deletion: an image is pushed to the publisher’s own repository and withdrawn there, by deleting its tag or pushing another image under it, while any copy already pulled stays in the local store
Publish date: ✅ last_updated on each tag, stamped by Docker Hub when the tag is pushed (Hub API)

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --cooldown best-effort opts back in.

Reference traces¶

A collection of raw native outputs captured from the manager’s own CLI and recorded in the manager source. If you know Whalebrew well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ whalebrew list --no-headers
hello-world  hello-world:linux

Version check¶

The version is probed by running:

$ whalebrew version
Whalebrew 0.4.1-38-g79b8605-dirty+2024-08-02.79b860575946278fd3215e68677d7439424d1cd1

and extracted with:

r"^Whalebrew[ \t]+(?P<version>\d+\.\d+\.\d+)"

Changelog¶

8.1.0.dev0 (unreleased)
- Add Whalebrew, which installs Docker images as commands, with installed, search, install and remove support. Packages are keyed on their image.