Basalt¶

ID: basalt
Links: Documentation · Repository
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: 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`

Configuration¶

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

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

[mpm.overrides.basalt]
cli_names = [
    "basalt",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = []
pre_cmds = []
requirement = ">=0.10.0"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "--version",
]
version_regexes = [
    "Version:[ \\t]+v?(?P<version>\\S+)",
]

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 is privileged.

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.

Reference traces¶

A collection of raw native outputs captured from the manager’s own CLI and recorded in the bundled definition. 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

Version check¶

The version is probed by running:

$ basalt --version
Version: v0.10.0

and extracted with:

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

Upstream project¶

Metrics	`hyperupcall/basalt`
Activity
Popularity
Metadata

Changelog¶

8.0.0 (2026-09-20)
- Add the Basalt Bash package manager with installed, install and remove support, every operation going through its global subcommand tree.