Pearl¶

ID: pearl
Link: Repository
Upstream stars: ⭐ 237
Last commit: 2023-08-18
Platforms: 🐧 Linux · 🍎 macOS
Operations: installed · search · install · upgrade · remove
purl types: pkg:pearl/
CLI name: pearl
Every call: pearl --no-confirm <command>
Issues and PRs: 📦 manager: pearl
Source: pearl.toml

Pearl installs “packages” that wire dotfiles, shell and editor configuration into a machine (https://github.com/pearl-core/pearl).

A package is repo/name, the repository prefix being part of the identity because several repositories can be configured at once. That is the form the listings print and every verb accepts.

Parsing notes, verified against Pearl 2.3.12 on macOS:

--no-confirm is forced: Pearl asks “Are you sure?” before acting, and that flag is the documented way past it.
Both listings are two-line records, the identifier then an indented description, so the patterns key on the identifier’s own shape and the four-space indent keeps the description out.
The inventory marks each entry [installed], which is what separates it from the catalog list prints without --installed-only.
It carries no version anywhere, only an identifier and a description. That is a supported shape rather than a gap, installed_version being optional, and the same reading rustup and pyenv settled.
No upgrade_all. Bare pearl update updates Pearl itself, its help reading “Update Pearl or the packages if specified”, so only the single-package form is declared.

Caution

Pearl needs Bash 4.1 or newer and says so on every invocation when it does not have it. macOS ships Bash 3.2, where installing fails inside the package’s own hook functions while the read-only listings still work. A newer Bash anywhere on PATH is enough: the whole round-trip was driven that way.

Note

An install runs the package’s own hook functions, which may take over the terminal and may fail: a failing post_install rolls the package back rather than leaving it half-installed.

What `mpm` adds to `pearl`¶

Through mpm, pearl 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 pearl 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 `pearl` commands, in `mpm`¶

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

To…	With `pearl`	With `mpm`
List what’s installed	`pearl list --installed-only`	`mpm --pearl installed`
Search for a package	`pearl search <query>`	`mpm --pearl search <query>`
Install a package	`pearl install <package_id>`	`mpm install pkg:pearl/<package_id>`
Upgrade one package	`pearl update <package_id>`	`mpm --pearl upgrade <package_id>`
Remove a package	`pearl remove <package_id>`	`mpm remove pkg:pearl/<package_id>`

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`
`orphans`
`search`	✅	Exact and extended search backfilled by `mpm`.
`install`	✅
`upgrade`	✅
`upgrade_all`
`remove`	✅
`sync`
`cleanup`
`doctor`

Configuration¶

Ignore pearl on the mpm CLI by passing the --no-pearl option.
Ignore it for every run in your configuration:
```
[mpm]
pearl = false
```
Raise the timeout of all pearl calls:
```
[mpm.overrides.pearl]
timeout = 900
```

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

[mpm.overrides.pearl]
cli_names = [
    "pearl",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = [
    "--no-confirm",
]
pre_cmds = []
stop_on_error = false
unmaintained = false
version_cli_options = [
    "--version",
]
version_regexes = [
    "pearl\\s+(?P<version>\\S+)",
]

The arguments and environment variables listed in the box atop this page are forced on every pearl call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Recipes¶

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

Snapshot and clone a machine: mpm --pearl dump pearl.toml, then mpm restore pearl.toml on the next one.
Export a compliance SBOM: mpm --pearl 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 Pearl’s release-age gating, from the cooldown support table:

Status: ❌ None (a package is a git checkout, carrying no version or date)

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: Pearl package repositories
Retraction: Repository edit: a package is an entry in a repository of recipes that clone from upstream, so it is withdrawn by that repository dropping the entry
Publish date: ❌ neither the listing nor a recipe records a version, so there is nothing to date

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 bundled definition. If you know Pearl well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ pearl list --installed-only
pearl/airline [installed]
    Status/tabline for vim

$ pearl search {query}
pearl/bufexplorer
    BufExplorer Plugin for Vim
pearl/dot-vim
    Awesome vim dotfiles

Version check¶

The version is probed by running:

$ pearl --version
pearl 2.3.12

and extracted with:

r"pearl\s+(?P<version>\S+)"

Upstream project¶

Metrics	`pearl-core/pearl`
Activity
Popularity
Metadata

Changelog¶

8.0.0 (2026-09-20)
- Add the Pearl package manager with inventory, search, install, remove and single-package upgrade.