Package management

peipkg is the command that installs, upgrades, removes, and queries software on a running Peios system. This page is the map — what a package is, where packages come from, why peipkg needs no special identity to do its job, and the command surface it exposes.

install puts packages on the system and remove takes them off. This page covers the plan-and-confirm flow both share, installing straight from a local .peipkg file, and what happens when you remove a package something else depends on.

refresh updates the metadata peipkg plans against; upgrade moves packages forward to their newest versions; downgrade and undo move them back. Together they are the routine update cycle and the way to walk a bad change off the system.

A repository is an HTTP location that serves signed packages. This page covers the repo commands, the trust ceremony that anchors a repository to a signing key, how key rotation propagates, what signature policy and priority control, and the freshness protection that stops a stale repository being passed off as current.

Every peipkg change is an atomic, reversible transaction. This page explains the three phases an operation moves through, the single instant that separates "nothing happened" from "it is done", how backups make rollback free, what an interrupted run leaves behind, and how recover and history work.

Before any change, peipkg resolves a request into a concrete plan — which versions of which packages, in what order. This page covers dependencies, conflicts, provides and replaces, how a version is chosen, and the elevated-authorisation prompt that guards the few actions a routine yes should not cover.

A claim is a shared filesystem name that many installed packages can answer but only one may hold at a time. This page explains how a claim materialises as a symlink, how installing and removing a provider takes and releases it, and the claim command for inspecting and reassigning the holder.

The read-only peipkg commands — list, info, files, and owns to see what is installed, search to find a package in the repositories, verify to check installed files are intact, and clean to tidy the metadata cache.

peipkg can install into more than one root at once. This page explains named roots, the per-root registry, dotted references, automatic target selection with default_root, the cascading upgrade, cross-root dependencies and their two-phase commit, and how undo and recover treat a cross-root change as a unit.

peipkg-compose builds a fresh, fully package-owned root directory from a declarative manifest, offline and deterministically. This page covers the two commands lock and build, the manifest and its field tables, the generated lock file, how named roots and claims settle in a composed image, what ends up in the tree, and what compose deliberately does not do.