Overview/xpm — package manager

xpm — Usage

Complete usage reference for the xpm binary, based on crates/xpm/src/cli.rs, crates/xpm/src/main.rs, and the project README.

Global flags

These flags are accepted by every subcommand.

The CLI is defined with clap and requires a subcommand (arg_required_else_help = true).

Commands

sync — Synchronize package databases

Alias: Sy. Downloads the latest .db (and best-effort .files) database files from every configured repository and parses them into local sync databases.

xpm sync [OPTIONS]
xpm Sy [OPTIONS]

Implementation note: cmd_sync in main.rs runs per-repository sync workers in parallel chunks, tries each configured mirror with retries, reports which mirror answered, and then parses the downloaded .db / .files so the local package count can be shown. Remote sync failures are warned and do not abort the whole run.

install — Install packages

Alias: S. Installs one or more packages by name from the synchronized databases.

xpm install <PACKAGES>... [OPTIONS]
xpm S <PACKAGES>... [OPTIONS]

Behavior (from main.rs): every configured sync database is loaded and the requested requirements (name or name=version) are solved with the SAT resolver, which picks candidates, honors depends/conflicts and unversioned provides, and returns the closure in dependency order. Each package is downloaded to the cache directory, checked against a remote .sig per the effective sig_level and against sha256sum when the database entry carries one, then committed as install operations on a Transaction (requested packages explicit, pulled dependencies as deps; --as-deps/--as-explicit override). With --download-only the run stops after downloading. Otherwise xpm asks for confirmation (unless --no-confirm) and the transaction extracts the files and registers each package in the local database.

remove — Remove packages

Alias: R. Removes installed packages, using the file manifest recorded in the local database.

xpm remove <PACKAGES>... [OPTIONS]
xpm R <PACKAGES>... [OPTIONS]

The package must be registered in the local database (otherwise xpm reports it is not installed). Confirmation is requested unless --no-confirm.

upgrade — System upgrade

Alias: Su. Upgrades all installed packages to the newest available versions.

xpm upgrade [OPTIONS]
xpm Su [OPTIONS]

upgrade always refreshes the databases first (equivalent to pacman -Syu), then resolves the transitive closure of the packages with newer versions so new or newly-required dependencies are installed in the same run. Upgraded packages keep their install reason; pulled dependencies are recorded as deps. With no packages installed it reports "Nothing to do".

history — Transaction journal

Show the recorded transactions, newest first. Every install, remove and upgrade writes a JSON entry under <db_path>/journal/<epoch>-<pid>.json (default /var/lib/xpm/journal/) before touching the filesystem, and finalizes it as ok/failed after the commit.

xpm history [OPTIONS]

xpm history                # Human summary (ISO-8601 timestamps)
xpm history --json         # One JSON line per transaction

Transactions left in running state after a crash stay in the journal as evidence; full recovery is still x gen rollback (generation layer), not an xpm command.

Around each transaction, xpm runs the executables in /usr/lib/xpm/hooks/pre-transaction.d/ and post-transaction.d/ in lexical order (override the root with XPM_HOOKS_DIR). The contract is a set of environment variables:

A failing pre hook aborts the transaction (no changes); a failing post hook only logs a warning. The runner ships with xpm; the hook scripts themselves are contributed by x-scripts when xpm becomes the active manager.

query — Query the local database

Alias: Q. Lists installed packages from the local database.

xpm query [FILTER] [OPTIONS]
xpm Q [FILTER] [OPTIONS]

Implementation note: implemented. query reads the local database (and the synced remote entries for --upgrades); --format tsv prints name<TAB>version for scripts. The --explicit/--deps filters use the install reason stored per package (<db_path>/local/<pkg>/reason); packages without a reason file, or installed before the feature, count as explicit. --explicit and --deps together are an error. --orphans still fails with a clear message because the local database does not record the reverse dependency graph yet.

search — Search packages

Alias: Ss. Searches for packages by name, description, or provides.

xpm search <QUERY> [OPTIONS]
xpm Ss <QUERY> [OPTIONS]

Implementation note: implemented — matches name, description and provides in the sync or local databases.

info — Package information

Alias: Si. Displays detailed information about a package.

xpm info <PACKAGE> [OPTIONS]
xpm Si <PACKAGE> [OPTIONS]

Implementation note: implemented. Shows name, version, install reason and origin repository; when the sync database is available it adds the repository description and dependencies (the highest-priority repository wins). For packages that are not installed, the sync entry alone is shown. Legacy installs without reason/origin files default to explicit and unknown instead of failing.

files — List package files

Alias: Ql. Lists all files owned by an installed package.

xpm files <PACKAGE>
xpm Ql <PACKAGE>

Implementation note: implemented. Reads <db_path>/local/<pkg>/files, a pacman-compatible manifest (%FILES% header, relative paths, directories with a trailing /) derived from the package's .MTREE; it is the same manifest consumed by x gen restore --pkg.

repo — Repository management

Manages user-added (temporary) repositories. Predefined repositories come from /etc/xpm.conf; user-added repositories are stored as TOML files under /etc/xpm.d/.

xpm repo list                 # predefined + user-added repositories
xpm repo add <NAME> <URL>     # add a temporary repository
xpm repo remove <NAME>        # remove a user-added repository

Examples (from the built-in help):

xpm repo add chaotic-aur https://cdn-mirror.chaotic.cx/$repo/$arch
xpm repo add my-repo https://username.github.io/my-repo/$arch
xpm repo add local file:///srv/packages/$arch

repo add refuses to overwrite an existing entry of the same name. After adding a repository, run xpm sync to fetch its database.

usage — Built-in help

Shows detailed usage help for the whole tool or for a topic/command.

xpm usage                    # general overview
xpm usage commands           # list all commands
xpm usage config             # configuration file format
xpm usage repos              # repository management
xpm usage <command>          # help for a specific command (sync, install, remove, upgrade, ...)

xpm <command> --help also works through clap.

Pacman-style aliases

Typical workflow

xpm sync                       # refresh package databases
xpm install <package>          # install a package
xpm upgrade                    # upgrade installed packages (syncs first)
xpm history                    # inspect recorded transactions
xpm query                      # list installed packages
xpm remove <package>           # remove a package

Non-interactive use (for scripts) needs --no-confirm. For isolated/rootless experiments use --config, --root, --dbpath, and --cachedir to point at temporary directories; when the installation root is not /, xpm enables shell integration and creates command shims in ~/.local/bin (with PATH export lines in ~/.bashrc and ~/.zshrc).

Environment variables and exit codes

RUST_LOG is honoured through tracing-subscriber's EnvFilter to control log verbosity. docs/CLI.md additionally documents XPM_CONFIG, XPM_CACHE_DIR, XPM_HOOKS_DIR (overrides the transaction-hook root, default /usr/lib/xpm/hooks), and NO_COLOR.

docs/CLI.md documents an exit-code matrix (0 success, 1 general error, 2 usage error, up to 7 database locked). Note that this matrix is documented intent rather than an enforced contract in the current code: in practice clap reports usage errors, anyhow reports runtime failures, and other documented codes are not yet emitted by main.rs. Verify against the code before relying on a specific code.

References

• Existing CLI reference: ../CLI.md
• Fetch targets and mirror layout: ../FETCH_TARGETS.md
• Install/upgrade quick guide: ../INSTALL_AND_UPGRADE.md
• Example configuration: ../../etc/xpm.conf.example
• Command definition: ../../crates/xpm/src/cli.rs, dispatch: ../../crates/xpm/src/main.rs

Edit this page on GitHub