Basalt¶

ID: basalt
Home page: https://github.com/hyperupcall/basalt
Upstream stars: ⭐ 83
Last commit: 2026-06-27
Version requirement: >= 0.10
Platforms: 🐧 Linux · 🍎 macOS
Operations: installed · install · remove
purl types: pkg:basalt
CLI name: basalt
Issues and PRs: 📦 manager: bash-based
Source: meta_package_manager/managers/basalt.toml

basalt is a package manager for Bash, installing libraries and executables from their Git repositories.

Parsing notes, verified against basalt v0.10.0 on macOS:

Every operation goes through the global subcommand tree. basalt’s bare subcommands (add, remove, install, list) act on the basalt.toml of the current directory’s project, which is out of mpm’s system scope; the global ones act on the machine-wide tree.
global list prints one <url>@<commit> line per package. The pattern drops the scheme and host so the id is the owner/repo slug that global add and global remove accept back, which is the only form all three agree on.
Versions are commit hashes, not releases: basalt pins each package to the commit it resolved. That is what it records, so it is what mpm reports.
No outdated and no search: basalt offers neither a staleness query nor a catalogue of any kind.
remove forces --force, without which basalt prompts and would hang mpm’s non-interactive subprocess.

Two host requirements are basalt’s own, and both fail loudly rather than silently, so they are left to fail rather than worked around:

A GitHub token file at $XDG_CONFIG_HOME/basalt/token. Without it every command refuses, the read-only listing included.
BASALT_GLOBAL_REPO and BASALT_GLOBAL_DATA_DIR in the environment, which the user exports by evaluating basalt global init <shell> in their shell configuration. mpm inherits them from the shell it is launched from.

What `mpm` adds to `basalt`¶

mpm reaches across every manager at once, not basalt alone: mpm installed and mpm outdated cover basalt 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 `basalt` commands, in `mpm`¶

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

To…	With `basalt`	With `mpm`
List what’s installed	`basalt global list`	`mpm --basalt installed`
Install a package	`basalt global add <package_id>`	`mpm install pkg:basalt/<package_id>`
Remove a package	`basalt global remove --force <package_id>`	`mpm remove pkg:basalt/<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
`installed`	✓
`outdated`
`orphans`
`search`
`install`	✓
`upgrade`
`upgrade_all`
`remove`	✓
`sync`
`cleanup`
`doctor`

Selecting and configuring `basalt`¶

Deselect basalt for a single run with --no-basalt, or persist the choice in your configuration:

[mpm]
basalt = false

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.overrides.basalt]
timeout = 900

mpm config-template basalt prints every overridable attribute as a ready-to-paste block.

Recipes¶

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

Snapshot and clone a machine: mpm --basalt dump basalt.toml, then mpm restore basalt.toml on the next one.
Export a compliance SBOM: mpm --basalt 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 needs root.

See privilege escalation for the full policy.

Cooldown¶

State of Basalt’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: Git repositories (bash)
Retraction: Upstream deletion: bpkg clones the owner/repo it is given straight from the forge, so there is no index standing between the name and the code and no retraction surface either; a package is withdrawn by its repository being deleted, renamed or made private
Publish date: ❌ nothing dates a release: the fetch resolves a branch or tag on the repository rather than a published artefact, so the only timestamp available is a commit date, which is client-set

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.

Version probe¶

The version is probed by running:

$ basalt --version
Version: v0.10.0

and extracted with:

r"Version:[ \t]+v?(?P<version>\S+)"

Reference traces¶

Raw native outputs captured in the bundled definition: the reference mpm’s parsers were written against. If you know Basalt well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ basalt global list
https://github.com/hyperupcall/bash-args@8fa6ff556d9c4fca5ce8431ddc571139abcf69a7

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --basalt installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Upstream project¶

Metrics	`hyperupcall/basalt`
Activity
Popularity
Metadata

Changelog¶

8.0.0.dev0 (unreleased)
- Add Basalt package manager as a bundled definition, with installed, install and remove support. Every operation goes through its global subcommand tree, the bare ones acting on the current directory’s project instead. Versions are the commit hashes basalt pins each package to.
- Label basalt and bpkg issues and pull requests with a shared bash-based group rather than a manager label each, so the Bash plugin managers group by their host shell like the fish-based and zsh-based ones already do.