▤01 / INVENTORY
Inventory
What is installed, per provider, with identities that keep architecture and scope.
xpac list --provider apt --json
Every package.
Every reason.
Know what is installed and why.
Change packages and dotfiles only through a plan you have read.
ONE INVENTORY / FIVE PACKAGE MANAGERS
Read the system.
Then decide.
Identities keep their provider, architecture and scope: apt:curl:amd64 is not just “curl”.
- Native, not guessed.
- Consultation is implemented for APT, Pacman, RPM/DNF, Flatpak (default user and system), Homebrew formulae and casks, apk and Portage. There is no implicit fallback from one provider to another.
- Plans that expire.
- A saved plan expires, and must match a fresh native plan before it runs — so you never apply a plan the system has moved past.
- Declarative, additive.
- TOML manifests with profiles and platform layers that compose deterministically, for packages and home configuration files. Unknown fields fail before execution; additive mode keeps software you didn’t declare.
COMMANDS / INSPECT FIRST
Most of it
only reads.
Inventory, provenance, dependencies and audit are read-only. Package changes and cache/orphan cleanup require an explicit preview and confirmation.
?02 / PROVENANCE
Why it’s there
The installation reason behind a package: explicit, dependency, or unknown.
xpac why apt:curl:amd64
⑂03 / DEPS
Dependencies
Installed native expressions for APT, Pacman, RPM and Homebrew formulae, alternatives and constraints kept. Metadata, not a cross-provider graph.
xpac deps apt:curl:amd64
⇥04 / EXPORT
Export & diff
Write the inventory as TOML, atomically, and compare a machine to a manifest. An exported inventory is not a lockfile.
xpac diff -f examples/profiles.toml --profile dev
◇05 / PLAN
Plans
What applying a manifest or an install would change — saved, reviewed, and set to expire.
xpac plan -f system.toml
▶06 / APPLY
Apply
APT, Pacman, DNF5 and DNF4, Flatpak apps, Homebrew formulae, apk and Portage, after a preview and an interactive yes or an explicit --yes. Non-interactive without --yes is refused.
xpac apply --plan preview.json --dry-run
⌕07 / AUDIT
Audit & clean
Audit and dry-runs classify caches and orphans. Explicit cache cleanup and reviewed orphan removal are available for APT and Pacman; xpac never deletes configuration, home data or unmanaged paths itself.
xpac audit --provider apt
▥08 / TUI
Terminal UI
Two panes after atfq, confidence cues after Omniscient. Read-only by default; --allow-apply enables experimental APT operations.
xpac tui --provider apt
◎09 / FILES · EXPERIMENTAL
Configuration files
Declare dotfiles under your home next to your packages. An existing file is never overwritten until you adopt it, with a private backup; local edits are reported as drift and refused. xpac never deletes them.
xpac file adopt ~/.tmux.conf --dry-run
FROM A MANIFEST TO A MACHINE
Nothing changes
without a plan.
Reconciling a machine with a TOML manifest is a sequence of checks, each of which can stop it.
IN THE TERMINAL
Inspect.
Then reconcile.
The commands as the README gives them. JSON goes to stdout with schema_version 1; previews and prompts go to stderr.
● ● ●
xpac · read-onlyLINUX$ xpac providers $ xpac list --provider apt --json $ xpac search curl --provider dnf --installed $ xpac info apt:curl $ xpac why apt:curl:amd64 $ xpac deps apt:curl:amd64
Inventory, search, information, provenance and dependencies — no root needed, no repository refresh.
Shown as commands only: the README doesn’t publish their output, and this page doesn’t invent it.
WHERE IT STANDS
Proof of concept,
validation ongoing.
xpac changes packages, so it is explicit about what has been checked and what hasn’t.
Seven native executors.
Reviewed execution is implemented for APT, Pacman, DNF5 and DNF4, Flatpak apps, Homebrew formulae, apk and Portage. Provider-specific previews and revalidation remain explicit.
Tested in isolated roots.
APT, Pacman, DNF5 and DNF4 (Rocky 8 and 9) transactions have run in disposable roots. Flatpak and Linux Homebrew also have isolated native evidence. Configuration files are tested only against temporary home directories. Host package transactions remain untested; configured CI runs and native macOS validation are pending.
sudo is explicit.
Inspection never elevates. --sudo delegates only the reviewed APT or Pacman transaction; xpac never reads a password from stdin, and dry-runs never authenticate.
$ xpac install apt:hello --sudo --dry-run $ xpac install apt:hello --sudo
Failures stay visible.
Partial failures never imply rollback. The journal records what was intended and what was verified, so you can see exactly where it stopped.
IN PRACTICE / THE EVIDENCE
A problem.
What changed.
Choose a target to read what happened: the problem, the finding and the result. Each story names its evidence and the scope of its validation.
A familiar package name exposed an identity-parser bug.
- Problem
- Packages named apt, flatpak or dnf were misparsed or rejected by the APT identity parser.
- Finding
- Rootless Debian bookworm and Ubuntu noble runs exercised real package inventories and transactions in disposable roots, revealing the collision.
- Result
- The parser was corrected. The documented runs passed inspection, reviewed install/removal, idempotent reapply and stale-plan refusal checks.
One signed install broke the next inventory.
- Problem
- RPM inventories failed after the first signed package install because key headers appeared as gpg-pubkey entries.
- Finding
- The Fedora 44 sandbox exercised an install followed by inventory and reapply, exposing the unexpected header records.
- Result
- The inventory handling was corrected. The documented DNF5 run passed confirmed install, idempotent reapply, protected-package refusal and reviewed removal.
OPEN SOURCE / LINUX AND MACOS
Know your packages
before you touch them.
Download it, then start with the demo — no native package manager needed.
DOWNLOAD · STATIC LINUX X86_64 BINARY
v=v0.1.0 t=x86_64-unknown-linux-musl curl -fLO https://github.com/devutils-org/xpac/releases/download/$v/xpac-$v-$t.tar.gz gh attestation verify xpac-$v-$t.tar.gz --repo devutils-org/xpac tar xzf xpac-$v-$t.tar.gz && mkdir -p ~/.local/bin && install -m 755 xpac-$v-$t/xpac ~/.local/bin/ # then xpac demo xpac list --provider apt --json