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.
| Flag | Short | Value | Description |
|---|---|---|---|
--config | -c | PATH | Path to the configuration file (default /etc/xpm.conf) |
--verbose | -v | count | Increase verbosity (-v, -vv, -vvv) |
--no-confirm | Skip confirmation prompts | ||
--root | PATH | Alternative installation root directory | |
--dbpath | PATH | Alternative database directory | |
--cachedir | PATH | Alternative cache directory | |
--no-color | Disable colored output |
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]
| Flag | Short | Description |
|---|---|---|
--force | -f | Force a full database refresh even if databases look up to date |
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]
| Flag | Short | Description |
|---|---|---|
--download-only | -w | Download packages without installing |
--as-deps | Mark the package as installed as a dependency | |
--as-explicit | Mark the package as explicitly installed | |
--no-optional | Skip optional dependencies |
Behavior (from main.rs): the package is located by exact name across the configured
repositories in order (first repository that provides it wins), downloaded to the cache
directory, checked against a remote .sig file according to the effective sig_level, and
checked against sha256sum when the database entry carries one. The download then becomes an
install operation on a Transaction. With --download-only the run stops after downloading.
Otherwise xpm asks for confirmation (unless --no-confirm) and then prepares and commits the
transaction, which extracts the files and registers the package in the local database.
Note: despite the "Resolving dependencies..." message, the current CLI install path does not run the SAT resolver; it selects the package by name from the synced 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]
| Flag | Short | Description |
|---|---|---|
--recursive | -s | Also remove unneeded dependencies |
--no-deps | -d | Skip dependency checks |
--nosave | -n | Remove configuration files as well (purge) |
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]
| Flag | Short | Description |
|---|---|---|
--force | Force reinstallation of up-to-date packages | |
--ignore | Skip specific packages (repeatable, --ignore <PKG>) |
upgrade always refreshes the databases first (equivalent to pacman -Syu), compares installed
versions against the remote latest entries using the ALPM-compatible version comparison, and
plans remove+install operations per package that changed. With no packages installed it reports
"Nothing to do".
query — Query the local database
Alias: Q. Lists installed packages from the local database.
xpm query [FILTER] [OPTIONS]
xpm Q [FILTER] [OPTIONS]
| Argument / Flag | Short | Description |
|---|---|---|
FILTER | Optional package name filter | |
--explicit | -e | Only explicitly installed packages |
--deps | -d | Only packages installed as dependencies |
--orphans | -t | Orphan packages (no longer required) |
--upgrades | -u | Packages with available updates |
Implementation note: the flags and filter are parsed, but the handler is currently a stub that only prints the intended filter type.
search — Search packages
Alias: Ss. Searches for packages by name, description, or provides.
xpm search <QUERY> [OPTIONS]
xpm Ss <QUERY> [OPTIONS]
| Flag | Short | Description |
|---|---|---|
--local | -l | Search in the local database instead of the sync databases |
Implementation note: currently a stub.
info — Package information
Alias: Si. Displays detailed information about a package.
xpm info <PACKAGE> [OPTIONS]
xpm Si <PACKAGE> [OPTIONS]
| Flag | Short | Description |
|---|---|---|
--local | -l | Query the local database instead of the sync databases |
Implementation note: currently a stub.
files — List package files
Alias: Ql. Lists all files owned by an installed package.
xpm files <PACKAGE>
xpm Ql <PACKAGE>
Implementation note: currently a stub.
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
| Alias | Maps to | Pacman equivalent |
|---|---|---|
Sy | sync | pacman -Sy |
S | install | pacman -S |
R | remove | pacman -R |
Su | upgrade | pacman -Su |
Q | query | pacman -Q |
Ss | search | pacman -Ss |
Si | info | pacman -Si |
Ql | files | pacman -Ql |
Typical workflow
xpm sync # refresh package databases
xpm install <package> # install a package
xpm upgrade # upgrade installed packages (syncs first)
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, 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