CLI reference

Generated from the clap definition in crates/zp-cli/src/cli.rs. Don’t edit this file: ZP_BLESS=1 cargo test -p zp-cli regenerates it, and the tests fail if it’s stale. The guide with examples is docs/user/commands.md.

zenpac is also installed as zp. Both names behave the same.

Options for every command

Option	Description
`--root <DIR>`	Operate on another root directory instead of `/`. Default: `/`.
`-o, --option <KEY=VALUE>`	Override a setting for this run, e.g. `-o ui.color=never`. Repeatable.
`--color <WHEN>`	When to use colors (overrides `ui.color`). Values: `auto`, `always`, `never`.
`--json`	Write versioned JSON to stdout instead of text.

Commands

`zenpac search <TERMS>…`

Search packages by name and description.

Argument	Description
`<TERMS>…`	Every term must match (ignoring case).

`zenpac show <NAME>`

Show the details of a package.

Alias: info.

Argument	Description
`<NAME>`	The package name.

`zenpac list`

List the installed packages, or one kind of them.

Option	Description
`--upgradable`	Those a repo has a newer version of.
`--world`	Those the world names: installed on purpose.
`--auto`	Those installed only because something needs them.
`--foreign`	Those no enabled repo has: from package files, or from repos that are gone.
`--held`	Those held at their version.
`--repo <REPO>`	Only those installed from this repo, `namespace/repo`.

`zenpac policy <NAME>`

Show every repo’s version of a package, and which one is selected.

Argument	Description
`<NAME>`	The package name.

`zenpac depends <NAME>`

Show a package’s dependencies and what satisfies them.

Argument	Description
`<NAME>`	The package name.

`zenpac rdepends <NAME>`

Show the packages that depend on a package.

Argument	Description
`<NAME>`	The package name.

`zenpac update`

Download the repo DBs that changed and rebuild their indexes, and install the official repos’ AppStream catalogs.

`zenpac install <SPECS>…`

Install packages and what they need, and add them to the world.

Alias: add.

Argument	Description
`<SPECS>…`	What to install: `name`, `name>=1.2`, `name@namespace/repo`, or a package file (`./nano-9.3-1-x86_64.pkg.tar.zst`).

Option	Description
`--virtual <NAME>`	Put them into the virtual group NAME, as its members (replacing its members, if it exists), so they can later go together.
`--allow-partial`	Install even if installed packages have newer versions this doesn’t upgrade (a partial upgrade).
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac upgrade`

Upgrade every package to its newest version, and take what replaces a package in its place.

Alias: full-upgrade.

Option	Description
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac remove <NAMES>…`

Remove packages or virtual groups from the world, and with them every package nothing needs any more.

Alias: del.

Argument	Description
`<NAMES>…`	The packages or virtual groups, as the world names them.

Option	Description
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac reinstall <NAMES>…`

Install packages again in their installed version, e.g. to put back lost or damaged files. Changed config files and the world stay.

Argument	Description
`<NAMES>…`	The installed packages.

Option	Description
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac mark <HOW> <NAMES>…`

Mark packages as installed on purpose (manual: in the world) or as dependencies (auto: out of it), or hold them at their installed version. No package changes.

Argument	Description
`<HOW>`	How. Values: `manual`, `auto`, `hold`, `unhold`.
`<NAMES>…`	The packages.

`zenpac stats`

Show what the system holds: installed packages and their size, the history, the store, the cache, and the repos’ indexes.

`zenpac edit-sources <FILE>`

Edit a config file in your editor ($VISUAL, $EDITOR, else vi); it’s saved only if the configuration it makes is valid.

Argument	Description
`<FILE>`	The file under /etc/zenpac: `zenpac.toml`, `repos.d/<name>.toml` or `sources.d/<name>.toml` (default: `repos.d/99-zenpac.toml`).

`zenpac config show`

Print the configuration in effect as TOML: every value, with where it comes from (a file, a -o override, built in, or the default).

`zenpac world show`

Show the world: the packages installed on purpose, held ones, and virtual groups.

`zenpac world export`

Print the world as a world file, for world apply.

`zenpac world apply <FILE>`

Make a world file the world: install what it needs, remove what nothing needs any more.

Argument	Description
`<FILE>`	The world file.

Option	Description
`--allow-partial`	Install even if installed packages have newer versions this doesn’t upgrade (a partial upgrade).
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac fix <NAMES>…`

Repair the system: install what the world needs and misses, and reinstall the packages named, or without names, those whose files audit finds changed or gone.

Argument	Description
`<NAMES>…`	The packages to reinstall (default: the damaged ones).

Option	Description
`--allow-partial`	Install even if installed packages have newer versions this doesn’t upgrade (a partial upgrade).
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac audit <NAMES>…`

Check that the installed packages’ files are as they were installed: there, of the same kind, content, mode and owner, links leading where they did. Changed config files are listed, but they’re yours.

Alias: verify.

Argument	Description
`<NAMES>…`	The packages (default: every installed package).

`zenpac diff-config show`

Show each kept config file with the diff from your file to it.

`zenpac diff-config keep <FILES>…`

Keep your files: the kept versions (.zpnew, .zpsave) go.

Argument	Description
`<FILES>…`	The kept files, e.g. `/etc/nanorc.zpnew`.

`zenpac diff-config take <FILES>…`

Take the kept versions: each replaces your file (a .zpsave comes back).

Argument	Description
`<FILES>…`	The kept files, e.g. `/etc/nanorc.zpnew`.

`zenpac history list`

Every finished change, oldest first: its number, time, command and what it did.

`zenpac history show <ID>`

What one change did to each package and to the world.

Argument	Description
`<ID>`	Its number, as `history list` shows it.

`zenpac recover <HOW>`

Show the interrupted transaction, if one is pending, or finish it or roll it back.

Argument	Description
`<HOW>`	What to do with it (without: only show it). Values: `finish`, `rollback`.

`zenpac satisfy <DEPENDS>…`

Make dependency expressions true, e.g. a recipe’s build dependencies: install what meets the unmet ones.

Argument	Description
`<DEPENDS>…`	Dependency expressions, as packages write them: `cmake>=3.20`, `sh`.

Option	Description
`--virtual <NAME>`	Put them into the virtual group NAME, as its members (replacing its members, if it exists), so they can later go together.
`--allow-partial`	Install even if installed packages have newer versions this doesn’t upgrade (a partial upgrade).
`-y, --yes`	Don’t ask before changing anything.
`-s, --simulate`	Only show the plan.

`zenpac fetch <NAMES>…`

Download package files into a directory, checked like every download.

Alias: download.

Argument	Description
`<NAMES>…`	The packages.

Option	Description
`-O, --output <DIR>`	Where to put them (default: the current directory). Default: `.`.

`zenpac cache clean`

Remove every downloaded package.

`zenpac cache prune`

Remove the package versions the enabled repos no longer offer.

Option	Description
`--keep <N>`	Of each package, also keep this many of the newest other versions. Default: `0`.

`zenpac repo list`

Show every configured repo: enabled or not, priority, signatures, and how many packages its index holds.

`zenpac repo enable <REPO>`

Enable a repo (written to repos.d/99-zenpac.toml).

Argument	Description
`<REPO>`	The repo, `namespace/repo`.

`zenpac repo disable <REPO>`

Disable a repo (written to repos.d/99-zenpac.toml).

Argument	Description
`<REPO>`	The repo, `namespace/repo`.

`zenpac repo add <REPO>`

Add a repo the source publishes, to repos.d/<namespace>.toml: its details first, then, on a terminal, the question whether to trust its namespace’s key. Add zp update to download it.

Argument	Description
`<REPO>`	The repo, `namespace/repo`.

Option	Description
`--source <SOURCE>`	The source it’s on (default: the official one).
`--fingerprint <FINGERPRINT>`	Trust the namespace’s key with this fingerprint, checked with its owner (spaces allowed), without asking.
`--allow-unsigned`	Add a repo whose namespace doesn’t sign: only HTTPS protects it.

`zenpac repo remove <REPO>`

Remove a user repo: from the config files zenpac writes, with its index and, for its namespace’s last repo, the stored keys. Its installed packages stay, without a repo, unless they’re put back as without it (asked on a terminal, or —revert).

Argument	Description
`<REPO>`	The repo, `namespace/repo`.

Option	Description
`--revert`	Put its packages back as without the repo: those another repo has go to that repo’s version, the others go unless something needs them. Also for a repo removed before.
`-y, --yes`	Don’t ask before changing packages. (There’s no -s: removing the repo can’t be simulated.).

`zenpac repo search <WORDS>…`

Find repos to add: those whose name or description contains every word (all of them without words), from the source’s list of namespaces, cached and refreshed when it changed.

Argument	Description
`<WORDS>…`	The words.

Option	Description
`--source <SOURCE>`	The source to search (default: the official one).

`zenpac keys list`

Show every pinned key: its state, user IDs and the repos that pin it.

`zenpac keys trust <NAMESPACE> <FINGERPRINT>`

Show the keys a namespace publishes, or, with a fingerprint, trust that key for the namespace’s repos.

Argument	Description
`<NAMESPACE>`	The namespace, e.g. `masterfix`.
`<FINGERPRINT>`	The key’s fingerprint, checked with its owner (spaces allowed).

`zenpac keys refresh`

Download the pinned keys again, for new signatures and revocations.

`zenpac keys revoke <NAMESPACE>`

Stop trusting a namespace’s keys.

Argument	Description
`<NAMESPACE>`	The namespace.

`zenpac completion <SHELL>`

Print the shell completion script, for the name zenpac was called by (zenpac or zp).

Argument	Description
`<SHELL>`	The shell. Values: `bash`, `elvish`, `fish`, `powershell`, `zsh`.

Exit codes

Code	Meaning
0	Success. An empty search, or a package nothing depends on, is a success too
1	The package wasn’t found
2	Wrong usage
3	Another error, e.g. the configuration, or a repo that `update` couldn’t refresh
4	Cancelled at the question before a change
5	`audit` found files changed or gone (changed config files aside)