'\" t
.\"     Title: zoi
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-10-16
.\"    Manual: Zoi Manual
.\"    Source: zoi
.\"  Language: English
.\"
.TH "ZOI" "1" "2026-10-16" "zoi" "Zoi Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
zoi \- the advanced package manager and environment orchestrator
.SH "SYNOPSIS"
.sp
\fBzoi\fP [\fIGLOBAL\-OPTIONS\fP] \fICOMMAND\fP [\fIARGS\fP.\|.\|.]
.sp
\fBzoi\fP [\fIGLOBAL\-OPTIONS\fP] \fICOMMAND\fP \fB\-\-help\fP
.SH "DESCRIPTION"
.sp
Zoi is part of the Zillowe Development Suite (ZDS). It streamlines
development workflows by managing tools, packages, and project environments
across operating systems. Packages come from registries of cryptographically
signed archives; both pre\-compiled binary archives (.zpa) and source bundles
(.zsa) are supported. Zoi also manages declarative user environments and the
underlying ZoiOS system.
.sp
Key capabilities include SAT\-based dependency resolution with a two\-phase
transactional installer, bandwidth\-efficient delta upgrades, PGP signature
verification, project environments with lockfiles, background service
management, and a Lua\-based packaging format (see \fBzoi\-lua\fP(5)). The same
engine is available as a Rust library (see \fBzoi\-rs\fP(3)).
.sp
This page documents every built\-in command and its options. For the full
online documentation, including guides and the registry specification, see
.URL "https://zillowe.qzz.io/docs/zds/zoi" "" "."
Run \fBzoi COMMAND \-\-help\fP for the
authoritative per\-command help.
.SH "CONCEPTS"
.sp
\fBPackage sources\fP
.RS 4
Most commands accept a package source: a registry name such as
\f(CR@core/ripgrep\fP, a git source such as \f(CR#git@repo/name\fP, a local path to a
\f(CR.pkg.lua\fP file or \f(CR.zpa\fP/\f(CR.zsa\fP archive, or a URL. A repository \f(CRzoi.lua\fP
may import pinned repositories with \f(CRimports()\fP and expose named package
exports such as \f(CRbase:tools\fP. Some commands also accept PURL identifiers.
.RE
.sp
\fBInstallation scopes\fP
.RS 4
Packages install into one of three scopes: \fBuser\fP (the current user,
the default), \fBsystem\fP (machine\-wide, requires elevation), or \fBproject\fP
(the current project directory). Use \fB\-\-scope\fP, \fB\-\-local\fP (project), or
\fB\-\-global\fP (user) to select one.
.RE
.sp
\fBTransactions\fP
.RS 4
Installations run in two phases (prepare, then execute) and are recorded.
Use \fBzoi transaction\fP to inspect them and \fBzoi history\fP to review past
operations.
.RE
.sp
\fBDelta upgrades\fP
.RS 4
When a previous version of an archive is cached, upgrades try to fetch
and apply \f(CR.zdelta\fP patches instead of re\-downloading the full archive.
If the cached version is several releases behind, each intermediate delta
is applied in sequence, up to the \fBmax_delta_steps\fP configuration value
(default 3). Any failure falls back silently to a full download.
.RE
.SH "GLOBAL OPTIONS"
.sp
These options may appear before any command.
.sp
\fB\-y\fP, \fB\-\-yes\fP
.RS 4
Automatically answer yes to all prompts.
.RE
.sp
\fB\-\-root\fP=\fIDIR\fP
.RS 4
Operate on a different root directory.
.RE
.sp
\fB\-\-offline\fP
.RS 4
Do not attempt to connect to the network. Only local metadata and caches
are used.
.RE
.sp
\fB\-\-pkg\-dir\fP=\fIDIR\fP
.RS 4
Additional directory to search for .zpa archives. Repeatable.
.RE
.sp
\fB\-v\fP, \fB\-\-version\fP
.RS 4
Print detailed version and build information.
.RE
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
Print help. Run \fBzoi COMMAND \-\-help\fP for help on a specific command.
.RE
.SH "PACKAGE MANAGEMENT"
.sp
\fBinstall\fP, \fBi\fP, \fBin\fP, \fBadd\fP [\fISOURCES\fP.\|.\|.] [\fIOPTIONS\fP]
.RS 4
Install one or more packages from registry names, local files, URLs, or
git repositories.
.RE
.sp
\fB\-\-repo\fP=\fIREPO\fP
.RS 4
Clone a repository and install a package exported by its
root \f(CRzoi.lua\fP (conflicts with sources). Select a named export with
\f(CRowner/repo:name\fP; URL sources use a \f(CR#name\fP fragment.
.RE
.sp
\fB\-\-force\fP
.RS 4
Re\-install even if already installed.
.RE
.sp
\fB\-\-all\-optional\fP
.RS 4
Accept all optional dependencies.
.RE
.sp
\fB\-\-scope\fP=\fIuser|system|project\fP
.RS 4
Installation scope.
.RE
.sp
\fB\-\-local\fP
.RS 4
Alias for \fB\-\-scope\fP=project. \fB\-\-global\fP:: Alias for
\fB\-\-scope\fP=user.
.RE
.sp
\fB\-\-save\fP
.RS 4
Record the installed packages in zoi.lua, so a later bare
\f(CRzoi install\fP recreates the same environment. Only the requested packages
are recorded, not transitive dependencies. Applies to project\-scope installs
only, and requires a zoi.lua in the current directory.
.RE
.sp
\fB\-\-deps\-only\fP
.RS 4
Install only dependencies, not the packages themselves.
.RE
.sp
\fB\-\-build\-deps\-only\fP
.RS 4
Install only build dependencies.
.RE
.sp
\fB\-\-type\fP=\fITYPE\fP
.RS 4
Build type when building from source.
.RE
.sp
\fB\-\-dry\-run\fP
.RS 4
Show what would be done without changing anything.
.RE
.sp
\fB\-b\fP, \fB\-\-build\fP
.RS 4
Force building from source.
.RE
.sp
\fB\-\-frozen\fP
.RS 4
Enforce zoi.lock exactly (project scope only).
.RE
.sp
\fB\-\-explain\fP
.RS 4
Explain package selection decisions.
.RE
.sp
\fB\-\-plan\-json\fP
.RS 4
Print a machine\-readable plan (requires \fB\-\-dry\-run\fP).
.RE
.sp
\fB\-\-retry\fP=\fIN\fP
.RS 4
Failed download retries, minimum 1 (default 3).
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Show origins and preflight details.
.RE
.sp
\fB\-\-purl\fP
.RS 4
Resolve sources using the PURL specification.
.RE
.sp
\fBuninstall\fP, \fBun\fP, \fBrm\fP, \fBremove\fP \fIPACKAGES\fP.\|.\|. [\fIOPTIONS\fP]
.RS 4
Uninstall one or more previously installed packages, removing their files
from the store and their binary shims.
.sp
With no scope flag, the scope is resolved as in \fBinstall\fP: a directory
containing a \fIzoi.lua\fP uses the project scope, otherwise the user scope.
.RE
.sp
\fB\-\-scope\fP=\fIuser|system|project\fP
.RS 4
Installation scope. \fB\-\-local\fP and
\fB\-\-global\fP are aliases as in \fBinstall\fP.
.RE
.sp
\fB\-\-save\fP
.RS 4
Also remove the package from zoi.lua. Project scope only. Handles
plain and keyed entries alike; removing a base package also removes its
sub\-package entries, while removing \fIpackage:sub\fP removes only that one.
.RE
.sp
\fB\-r\fP, \fB\-\-recursive\fP
.RS 4
Recursively remove dependencies that are no longer
needed.
.RE
.sp
\fB\-\-dry\-run\fP
.RS 4
Show what would be done. \fB\-\-explain\fP:: Explain dependency
.RE
.sp
impact and safety blocks. \fB\-\-plan\-json\fP
.RS 4
Machine\-readable plan (requires
\fB\-\-dry\-run\fP).
.RE
.sp
\fBupdate\fP, \fBup\fP [\fIPACKAGES\fP.\|.\|. | \fB\-\-all\fP] [\fIOPTIONS\fP]
.RS 4
Update one or more packages to their latest versions. With no packages
and no \fB\-\-all\fP, behavior follows the command defaults; use \fB\-\-all\fP to
update everything.
.RE
.sp
\fB\-\-all\fP
.RS 4
Update all installed packages (conflicts with package list).
.RE
.sp
\fB\-\-dry\-run\fP
.RS 4
Show what would be done. \fB\-\-explain\fP:: Explain decisions.
.RE
.sp
\fB\-\-plan\-json\fP
.RS 4
Machine\-readable plan (requires \fB\-\-dry\-run\fP).
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Verbose output. \fB\-\-interactive\fP:: Interactively pick
updates (requires \fB\-\-all\fP).
.RE
.sp
\fBdowngrade\fP, \fBdg\fP \fIPACKAGE\fP
.RS 4
Install an older version of a package from the local store or archive
cache. With no version given, offers an interactive selection.
.RE
.sp
\fBrollback\fP \fIPACKAGE\fP
.RS 4
Roll a package back to the previously installed version.
.RE
.sp
\fBpin\fP \fIPACKAGE\fP \fIVERSION\fP
.RS 4
Pin a package to a specific version so updates skip it, and record that
version as the preferred global version for the binaries it provides.
.RE
.sp
\fBunpin\fP \fIPACKAGE\fP
.RS 4
Remove a version pin so the package can be updated again. Clears both the
upgrade guard and the shim version preference.
.RE
.sp
\fBmark\fP, \fBm\fP \fIPACKAGES\fP.\|.\|. (\fB\-\-as\-dependency\fP | \fB\-\-asexplicit\fP)
.RS 4
Change the installation reason of a package. \fB\-\-as\-dependency\fP
(\fB\-\-asdeps\fP) marks packages as dependencies; \fB\-\-asexplicit\fP
(\fB\-\-asexpl\fP) marks them as explicitly installed.
.RE
.sp
\fBautoremove\fP [\fB\-\-dry\-run\fP]
.RS 4
Remove packages that were installed as dependencies and are no longer
needed.
.RE
.sp
\fBdownload\fP, \fBdl\fP \fIPACKAGE\fP [\fIOPTIONS\fP]
.RS 4
Download a package archive or source bundle without installing it.
.RE
.sp
\fB\-\-archive\fP
.RS 4
Download the .zpa archive (default). \fB\-\-source\fP:: Download
.RE
.sp
the .zsa source bundle instead. \fB\-o\fP, \fB\-\-output\-dir\fP=\fIDIR\fP
.RS 4
Directory to
write the download to.
.RE
.sp
\fBclone\fP \fIPACKAGE\fP [\fILOCATION\fP]
.RS 4
Clone the upstream git repository of a package, optionally into
\fILOCATION\fP.
.RE
.sp
\fBexec\fP, \fBx\fP \fISOURCE\fP [\fIARGS\fP.\|.\|.] [\fIOPTIONS\fP]
.RS 4
Execute a package binary directly with its dependencies resolved,
without a permanent install.
.RE
.sp
\fB\-\-bin\fP=\fIBIN\fP
.RS 4
Select the binary for multi\-binary packages.
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Verbose output. Remaining arguments are passed to the
binary.
.RE
.SH "INSPECTION AND QUERY"
.sp
\fBlist\fP, \fBls\fP [\fIOPTIONS\fP]
.RS 4
List installed packages, or all known packages with \fB\-a\fP.
.RE
.sp
\fB\-a\fP, \fB\-\-all\fP
.RS 4
List packages from the database, not just installed ones.
.RE
.sp
\fB\-o\fP, \fB\-\-outdated\fP
.RS 4
Only show packages that can be upgraded.
.RE
.sp
\fB\-\-registry\fP=\fIHANDLE\fP
.RS 4
Filter by registry. \fB\-\-repo\fP=\fIREPO\fP:: Filter by
.RE
.sp
repository tier. \fB\-t\fP, \fB\-\-type\fP=\fITYPE\fP
.RS 4
Filter by package type.
.RE
.sp
\fB\-m\fP, \fB\-\-foreign\fP
.RS 4
Show packages not present in any registry.
.RE
.sp
\fBshow\fP \fIPACKAGE\fP [\fIOPTIONS\fP]
.RS 4
Show detailed information about a package.
.RE
.sp
\fB\-\-raw\fP
.RS 4
Print the unformatted package definition. \fB\-\-purl\fP:: Resolve
using the PURL specification.
.RE
.sp
\fBsearch\fP, \fBs\fP \fITERM\fP [\fIOPTIONS\fP]
.RS 4
Search for packages by name or description.
.RE
.sp
\fB\-\-registry\fP=\fIHANDLE\fP, \fB\-\-repo\fP=\fIREPO\fP, \fB\-\-type\fP=\fITYPE\fP
.RS 4
Filters.
.RE
.sp
\fB\-t\fP, \fB\-\-tag\fP=\fITAGS\fP
.RS 4
Filter by tags (comma\-delimited, repeatable).
.RE
.sp
\fB\-\-sort\fP=\fIFIELD\fP
.RS 4
Sort field (default name).
.RE
.sp
\fB\-f\fP, \fB\-\-files\fP
.RS 4
Search within provided files.
.RE
.sp
\fB\-i\fP, \fB\-\-interactive\fP
.RS 4
Interactive TUI picker.
.RE
.sp
\fBinfo\fP
.RS 4
Display detected operating system and architecture information.
.RE
.sp
\fBinit\fP [\fB\-f\fP, \fB\-\-force\fP]
.RS 4
Create a \fIzoi.lua\fP project file in the current directory, declaring the
project and an empty \f(CRpackages({.\|.\|.})\fP block for \f(CRzoi install \-\-save\fP to
record into. The project name defaults to the current directory name, with
characters unsafe in a Lua string literal replaced.
.RE
.sp
\fB\-f\fP, \fB\-\-force\fP
.RS 4
Overwrite an existing zoi.lua. Without it, \f(CRinit\fP refuses
rather than risk clobbering an existing project.
.RE
.sp
\fBfiles\fP \fIPACKAGE\fP
.RS 4
List all files owned by an installed package.
.RE
.sp
\fBalt\fP [list|get|set|auto|remove]
.RS 4
Manage alternative implementations of interchangeable commands, such as awk,
vi or editor. A package registers an implementation by declaring an
\fBalternatives\fP block in its \fB.pkg.lua\fP, and Zoi keeps the canonical path
pointing at the one with the highest priority.
.sp
.if n .RS 4
.nf
.fam C
Only symlinks are written, so implementations coexist without a file conflict
and switching is instant. See the *Alternatives* guide for the full model.
.fam
.fi
.if n .RE
.RE
.sp
\fBalt list\fP [\-\-verbose]
.RS 4
List every registered alternative, showing the canonical link, the current
selection, whether it was chosen manually, and every registered implementation
with its priority.
.RE
.sp
\fBalt get\fP \fINAME\fP
.RS 4
Show one alternative group in detail, listing each implementation with its
priority, owning package, and which one is current.
.RE
.sp
\fBalt set\fP \fINAME\fP \fIPATH\fP
.RS 4
Select a specific implementation. Other implementations stay installed and can
be selected later. The choice is sticky: installing a higher\-priority package
afterwards will not silently undo it.
.RE
.sp
\fBalt auto\fP \fINAME\fP
.RS 4
Drop a manual selection and return to choosing the highest\-priority
implementation.
.RE
.sp
\fBalt remove\fP \fINAME\fP \fIPATH\fP
.RS 4
Remove one implementation from a group, for correcting a registration by hand.
.RE
.sp
\fBowner\fP, \fBowns\fP \fIPATH\fP
.RS 4
Find which installed package owns a file.
.RE
.sp
\fBprovides\fP \fITERM\fP
.RS 4
Find which package provides a specific command or file.
.RE
.sp
\fBtree\fP \fIPACKAGES\fP.\|.\|.
.RS 4
Visualize the dependency tree of one or more packages.
.RE
.sp
\fBwhy\fP \fIPACKAGE\fP
.RS 4
Explain why a package is installed (direct request or dependency chain).
.RE
.sp
\fBman\fP \fIPACKAGE\fP [\fIOPTIONS\fP]
.RS 4
Show a package\(cqs manual page with the system \fBman\fP viewer (falling back
to \fBinfo\fP). Without \fB\-\-page\fP, the page matching the package name in
section 1 is shown.
.RE
.sp
\fB\-\-upstream\fP
.RS 4
Prefer upstream manuals. \fB\-\-raw\fP:: Print the raw page
.RE
.sp
without formatting (pipeable into \fBman\fP). \fB\-\-page\fP=\fIPAGE\fP
.RS 4
Show a
specific page, e.g. \fBzbsdiff.3\fP.
.RE
.sp
\fBhistory\fP [\fIOPTIONS\fP]
.RS 4
Show the history of package operations.
.RE
.sp
\fB\-\-verify\fP
.RS 4
Verify history integrity. \fB\-\-export\fP=\fIFILE\fP:: Export history
.RE
.sp
to a file. \fB\-\-ndjson\fP
.RS 4
Export in NDJSON format (requires \fB\-\-export\fP).
.RE
.sp
\fBtransaction\fP, \fBtx\fP \fISUBCOMMAND\fP
.RS 4
Inspect recorded transactions.
.RE
.sp
\fBlist\fP, \fBls\fP
.RS 4
List known transaction logs. \fBshow\fP \fIID\fP:: Show transaction
.RE
.sp
details. \fBfiles\fP \fIID\fP
.RS 4
List files modified by a transaction. \fBundo\fP,
.RE
.sp
\fBrollback\fP [\fIID\fP] [\fB\-\-yes\fP]
.RS 4
Undo a transaction (default: the last one).
.RE
.SH "MAINTENANCE AND HEALTH"
.sp
\fBsync\fP, \fBsy\fP [\fISUBCOMMAND\fP] [\fIOPTIONS\fP]
.RS 4
  Download or update the package database from the remote repository.
Registry content is fetched from a zstd\-compressed \f(CR.zrepo\fP snapshot when the
registry publishes one in its \f(CRrepo.yaml\fP, updating it with a \f(CR.zdelta\fP patch
when available, and from a Git clone otherwise.
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Show underlying git output. \fB\-\-fallback\fP:: Use
.RE
.sp
fallback behavior. \fB\-\-no\-pm\fP
.RS 4
Skip the native package\-manager check.
.RE
.sp
\fB\-\-force\fP
.RS 4
Force a fresh clone. \fB\-\-local\fP:: Sync into ./.zoi/pkgs/db
.RE
.sp
from zoi.lua. \fB\-\-frozen\fP
.RS 4
With \fB\-\-local\fP, use zoi.lock.
.RE
.sp
\fB\-\-scope\fP=\fIuser|system\fP
.RS 4
Sync scope (conflicts with \fB\-\-local\fP).
.RE
.sp
Registry management subcommands: \fBadd\fP \fIURL\fP
.RS 4
Add a registry. A URL to a
\f(CRrepo.yaml\fP document is resolved immediately to its handle and metadata;
.RE
.sp
built\-in handles are also accepted. \fBremove\fP \fIHANDLE\fP
.RS 4
Remove a registry.
.RE
.sp
\fBlist\fP, \fBls\fP
.RS 4
List configured registries. \fBset\fP \fIURL\fP:: Set the default
registry URL (accepts \f(CRdefault\fP, \f(CRgithub\fP, \f(CRgitlab\fP, \f(CRcodeberg\fP, or a URL).
.RE
.sp
\fBupgrade\fP, \fBug\fP [\fIOPTIONS\fP]
.RS 4
Upgrade the Zoi binary itself to the latest release, using a delta
patch when possible.
.RE
.sp
\fB\-\-force\fP
.RS 4
Skip the delta patch and download the full binary.
.RE
.sp
\fB\-\-tag\fP=\fITAG\fP
.RS 4
Upgrade to a specific release tag.
.RE
.sp
\fB\-\-branch\fP=\fIBRANCH\fP
.RS 4
Upgrade from a release branch such as Prod or Pub.
.RE
.sp
\fBdoctor\fP
.RS 4
Check the installation for common issues and print actionable
suggestions.
.RE
.sp
\fBaudit\fP [\fIOPTIONS\fP]
.RS 4
Audit installed packages for known security vulnerabilities.
.RE
.sp
\fB\-a\fP, \fB\-\-all\fP
.RS 4
Audit all packages in the database, not just installed
.RE
.sp
ones. \fB\-\-registry\fP=\fIHANDLE\fP, \fB\-\-repo\fP=\fIREPO\fP
.RS 4
Scope the audit.
.RE
.sp
\fBcache\fP \fISUBCOMMAND\fP
.RS 4
Manage Zoi\(cqs local cache of package archives.
.RE
.sp
\fBadd\fP \fIFILES\fP.\|.\|.
.RS 4
Add .zpa archives to the cache. \fBclear\fP, \fBclean\fP
.RE
.sp
[\fB\-\-dry\-run\fP]
.RS 4
Clear the entire cache. \fBlist\fP, \fBls\fP:: List cached
archives. \fBmirror add\fP \fIURL\fP, \fBmirror remove\fP \fIURL\fP, \fBmirror list\fP
.RE
.sp
(\fBls\fP)
.RS 4
Manage fallback cache\-mirror base URLs.
.RE
.sp
\fBrepo\fP, \fBrepositories\fP \fISUBCOMMAND\fP
.RS 4
Manage package repositories.
.RE
.sp
\fBadd\fP, \fBa\fP [\fIREPO\-OR\-URL\fP]
.RS 4
Enable an official repository or clone a git
.RE
.sp
URL. \fBremove\fP, \fBrm\fP \fIREPO\fP
.RS 4
Remove a repository from the active
.RE
.sp
configuration. \fBlist\fP, \fBls\fP [\fBall\fP]
.RS 4
List active repositories (\f(CRall\fP
.RE
.sp
also shows discovered ones). \fBgit list\fP (\fBls\fP)
.RS 4
Show cloned git
.RE
.sp
repositories. \fBgit rm\fP \fIREPO\fP
.RS 4
Remove a cloned git repository.
.RE
.sp
\fBpgp\fP \fISUBCOMMAND\fP
.RS 4
Manage PGP keys used for package signature verification.
.RE
.sp
\fBadd\fP
.RS 4
Import a key from \fB\-\-path\fP=\fIASC\fP, \fB\-\-fingerprint\fP=\fIFP\fP (via
keys.openpgp.org), or \fB\-\-url\fP=\fIURL\fP. \fB\-\-name\fP=\fINAME\fP defaults to the
filename stem and is required with \fB\-\-fingerprint\fP.
.RE
.sp
\fBremove\fP, \fBrm\fP [\fINAME\fP] [\fB\-\-fingerprint\fP=\fIFP\fP]
.RS 4
Remove a key.
.RE
.sp
\fBlist\fP, \fBls\fP
.RS 4
List imported keys. \fBsearch\fP \fITERM\fP:: Search keys by user
.RE
.sp
ID or fingerprint. \fBshow\fP \fINAME\fP
.RS 4
Print a public key. \fBverify\fP:: Verify
a detached signature (\fB\-\-file\fP, \fB\-\-sig\fP, and \fB\-\-key\fP are required).
.RE
.sp
\fBtelemetry\fP \fIACTION\fP
.RS 4
Manage opt\-in anonymous telemetry (disabled by default). \fIACTION\fP is
one of \fBstatus\fP, \fBenable\fP, or \fBdisable\fP. Crash reports are managed
under \fBtelemetry crash\fP: \fBlist\fP (\fBls\fP) shows locally stored
\f(CR.zoicrash\fP files in \f(CR$XDG_STATE_HOME/zoi/crash\fP, \fBshow\fP \fIFILE\fP
prints one, \fBsend\fP \fIFILE\fP uploads it to Sentry (requires opt\-in),
and \fBclear\fP deletes all stored reports.
.RE
.SH "PACKAGE AUTHORING"
.sp
\fBpackage\fP, \fBpkg\fP \fISUBCOMMAND\fP
.RS 4
Build, create, test, and manage Zoi packages. Package definitions are
\f(CR.pkg.lua\fP scripts; see \fBzoi\-lua\fP(5).
.RE
.sp
\fBbuild\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Build a distributable archive from a \f(CR.pkg.lua\fP definition.
.RE
.sp
\fB\-\-type\fP=\fITYPE\fP
.RS 4
Build type. \fB\-p\fP, \fB\-\-platform\fP=\fIP\fP:: Target platforms,
repeatable (default: current; accepts values such as \f(CRlinux\-amd64\fP or
.RE
.sp
\f(CRall\fP). \fB\-\-sub\fP=\fISUBS\fP
.RS 4
Sub\-packages to build, repeatable.
.RE
.sp
\fB\-\-sign\fP=\fIKEY\fP
.RS 4
Sign with a PGP key from the keyring (name or
fingerprint). \fB\-\-sign\-mode\fP=\fIembed|file\fP (default embed).
.RE
.sp
\fB\-\-test\fP
.RS 4
Run the package test phase. \fB\-o\fP, \fB\-\-output\-dir\fP=\fIDIR\fP::
.RE
.sp
Output directory. \fB\-\-install\-deps\fP
.RS 4
Install build dependencies first.
.RE
.sp
\fB\-\-version\-override\fP=\fIV\fP
.RS 4
Override the package version.
.RE
.sp
\fB\-\-method\fP=\fIM\fP
.RS 4
Build method: \f(CRnative\fP (default), \f(CRbwrap\fP, or \f(CRdocker\fP.
.RE
.sp
\fB\-\-image\fP=\fIIMG\fP
.RS 4
Container image for docker builds. \fB\-\-fakeroot\fP:: Fake
.RE
.sp
UID/GID 0 during the build. \fB\-\-pure\fP
.RS 4
Build in a clean sysroot (forces
.RE
.sp
bwrap). \fB\-\-root\-package\fP=\fIPKG\fP
.RS 4
Root package for the build environment.
.RE
.sp
\fB\-\-no\-zsa\fP
.RS 4
Skip writing the .zsa source bundle.
.RE
.sp
\fBbundle\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Bundle a package definition and its local assets into a .zsa source
archive. Accepts \fB\-o\fP, \fB\-\-output\-dir\fP, \fB\-\-sign\fP, \fB\-\-sign\-mode\fP,
\fB\-\-version\-override\fP, and \fB\-t\fP/\fB\-\-build\-type\fP as in \fBbuild\fP.
.RE
.sp
\fBtest\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Run the \f(CRprepare\fP, \f(CRpackage\fP, and \f(CRtest\fP phases of a \f(CR.pkg.lua\fP
definition (same options as \fBbuild\fP).
.RE
.sp
\fBinstall\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Install a local .zpa archive.
.RE
.sp
\fB\-s\fP, \fB\-\-sub\fP=\fISUBS\fP
.RS 4
Sub\-packages, repeatable.
.RE
.sp
\fB\-\-scope\fP=\fIuser|system\fP (default user). \fB\-\-yes\fP
.RS 4
Skip confirmation.
.RE
.sp
\fBdelta\fP \fIOLD\fP \fINEW\fP [\fIOPTIONS\fP]
.RS 4
Generate a \f(CR.zdelta\fP patch transforming the \fIOLD\fP archive into the
\fINEW\fP archive, plus \f(CR.hash\fP and \f(CR.size\fP sidecars.
.RE
.sp
\fB\-o\fP, \fB\-\-output\fP=\fIFILE\fP
.RS 4
Output path (default: \fINEW\fP with a \f(CR.zdelta\fP
.RE
.sp
extension). \fB\-\-sign\fP=\fIKEY\fP
.RS 4
Also write a detached \f(CR.sig\fP sidecar.
.RE
.sp
\fBverify\fP [\fITARGET\fP] [\fIOPTIONS\fP]
.RS 4
Verify installed packages (like \f(CRrpm \-V\fP) or a single archive.
.sp
\fITARGET\fP is \f(CRinstalled\fP (default) or \f(CRarchive\fP. For \f(CRinstalled\fP:
\fIPACKAGES\fP.\|.\|. (default: all), \fB\-\-scope\fP=\fIuser|system\fP, \fB\-\-json\fP. For
\f(CRarchive\fP: \fB\-\-file\fP=\fIZPA\fP (required) and \fB\-\-json\fP.
.RE
.sp
\fBdoctor\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Lint and validate a package definition.
.sp
\fB\-\-platform\fP=\fIP\fP (default current). \fB\-\-version\-override\fP=\fIV\fP.
.RE
.sp
\fBinit\-lsp\fP [\fIPATH\fP]
.RS 4
Initialize Lua language\-server support (\f(CR.luarc.json\fP plus type
definitions) for authoring \f(CR.pkg.lua\fP files. Defaults to the current
directory.
.RE
.sp
\fBinspect\fP \fIFILE\fP [\fIOPTIONS\fP]
.RS 4
Inspect a package definition and its output metadata.
.RE
.sp
\fB\-\-json\fP
.RS 4
Machine\-readable output. \fB\-\-platform\fP=\fIP\fP.
\fB\-\-version\-override\fP=\fIV\fP.
.RE
.sp
\fBmigrate scoop\fP \fIINPUT\fP [\fIOPTIONS\fP]
.RS 4
Convert a Scoop manifest into a \f(CR.pkg.lua\fP definition.
.sp
\fB\-o\fP, \fB\-\-output\fP=\fIFILE\fP (default: \fI<name>\fP.pkg.lua).
\fB\-\-repo\fP=\fITIER\fP (default community). \fB\-\-name\fP=\fINAME\fP,
\fB\-\-version\fP=\fIVER\fP, \fB\-\-maintainer\-name\fP=\fIN\fP,
.RE
.sp
\fB\-\-maintainer\-email\fP=\fIE\fP
.RS 4
Metadata overrides. \fB\-\-dry\-run\fP:: Print
instead of writing.
.RE
.sp
\fBcreate\fP \fISOURCE\fP [\fIAPP\-NAME\fP]
.RS 4
Create a new application from a package template source.
.RE
.SH "REGISTRY AUTHORING"
.sp
\fBregistry\fP, \fBreg\fP \fISUBCOMMAND\fP
.RS 4
Manage and author Zoi registries. See the registry specification in the
online documentation.
.RE
.sp
\fBinit\fP [\fIPATH\fP]
.RS 4
Initialize a new registry layout (default: current directory).
.RE
.sp
\fBgenerate\-metadata\fP, \fBgen\-meta\fP
.RS 4
Generate \f(CRpackages.json\fP and \f(CRadvisories.json\fP for a registry.
.RE
.sp
\fBcheck\fP, \fBlint\fP, \fBaudit\fP
.RS 4
Validate registry integrity and package definitions.
.RE
.sp
\fBadd\-package\fP, \fBadd\-pkg\fP [\fINAME\fP] [\fB\-r\fP, \fB\-\-repo\fP=\fITIER\fP]
.RS 4
Add a package to the registry.
.RE
.sp
\fBadd\-advisory\fP, \fBsec\fP [\fIPACKAGE\fP] [\fB\-r\fP, \fB\-\-repo\fP=\fITIER\fP]
.RS 4
Add a security advisory for a package.
.RE
.sp
\fBzrepo\fP, \fBsnapshot\fP [\fIPATH\fP] [\fB\-o\fP, \fB\-\-output\fP=\fIFILE\fP] [\fB\-\-sign\fP=\fIKEY\fP]
.RS 4
Build a zstd\-compressed \f(CR.zrepo\fP snapshot of the registry (default path:
current directory). Writes \f(CR.hash\fP and \f(CR.size\fP sidecars alongside it, and
\f(CR.sig\fP when \fB\-\-sign\fP is given. The output is reproducible, so an unchanged
registry always yields identical bytes.
.RE
.sp
\fBzdelta\fP, \fBsnapshot\-delta\fP \fIOLD\fP [\fIPATH\fP] [\fB\-o\fP, \fB\-\-output\fP=\fIFILE\fP] [\fB\-\-sign\fP=\fIKEY\fP]
.RS 4
Build a \f(CR.zdelta\fP update patch taking clients from the \f(CR.zrepo\fP snapshot
\fIOLD\fP to the current state of the registry. Publish it at the \f(CRdelta\fP URL in
the \f(CRzrepo\fP section, or at \f(CR<zrepo url>.zdelta\fP if none is declared.
.RE
.SH "ENVIRONMENTS AND PROJECTS"
.sp
\fBdev\fP, \fBdevelop\fP [\fIOPTIONS\fP]
.RS 4
Enter a development shell for the current project.
.RE
.sp
\fB\-r\fP, \fB\-\-run\fP=\fICMD\fP
.RS 4
Run a command instead of opening an interactive
.RE
.sp
shell. \fB\-\-repo\fP=\fIREPO\fP
.RS 4
Use a temporary clone.
.RE
.sp
\fBrun\fP [\fIALIAS\fP] [\fIARGS\fP.\|.\|.]
.RS 4
Execute a command defined in the local zoi.lua task runner. With no
alias, offers interactive selection.
.RE
.sp
\fBenv\fP [\fIALIAS\fP] [\fIOPTIONS\fP]
.RS 4
Manage and set up project environments defined in zoi.lua.
\fB\-\-export\-shell\fP is internal.
.RE
.sp
\fBshell\fP [\fISHELL\fP] [\fIOPTIONS\fP]
.RS 4
Set up shell completions, print the shell hook, or enter an ephemeral
environment with extra packages.
.RE
.sp
\fB\-\-hook\fP
.RS 4
Print the shell hook script. \fB\-\-scope\fP=\fIuser|system\fP (default
.RE
.sp
user). \fB\-p\fP, \fB\-\-package\fP=\fIPKG\fP
.RS 4
Extra packages for the ephemeral
.RE
.sp
environment, repeatable. \fB\-r\fP, \fB\-\-run\fP=\fICMD\fP
.RS 4
Run a command.
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
Verbose output. With a \fISHELL\fP argument, installs
completions for that shell.
.RE
.SH "SERVICES AND THE SYSTEM"
.sp
\fBservice\fP, \fBsvc\fP \fISUBCOMMAND\fP
.RS 4
Manage background services declared by installed packages.
.RE
.sp
\fBstart\fP \fIPACKAGE\fP
.RS 4
Start a service. \fBstop\fP \fIPACKAGE\fP:: Stop a service.
.RE
.sp
\fBrestart\fP \fIPACKAGE\fP
.RS 4
Restart a service. \fBstatus\fP \fIPACKAGE\fP:: Show service
.RE
.sp
status. \fBenable\fP \fIPACKAGE\fP
.RS 4
Start the service at boot.
.RE
.sp
\fBdisable\fP \fIPACKAGE\fP
.RS 4
Do not start the service at boot. \fBlist\fP, \fBls\fP::
List packages that define a service and their status.
.RE
.sp
\fBhome\fP \fISUBCOMMAND\fP (ZoiOS only)
.RS 4
Manage declarative user environments.
.RE
.sp
\fBapply\fP [\fB\-f\fP, \fB\-\-file\fP=\fIFILE\fP]
.RS 4
Apply the declarative user configuration (default:
~/.config/zoi/home.lua).
.RE
.sp
\fBsystem\fP \fISUBCOMMAND\fP (ZoiOS only, except \fBsecret\fP and \fBdistro\fP)
.RS 4
Manage the underlying ZoiOS system.
.RE
.sp
\fBapply\fP [\fIFILE\fP]
.RS 4
Apply a system configuration (default: /etc/zoi/system.lua).
.RE
.sp
\fBlist\fP
.RS 4
List system generations. \fBstatus\fP:: Show the active generation.
.RE
.sp
\fBrollback\fP \fIID\fP
.RS 4
Roll back to generation \fIID\fP. \fBpin\fP \fIID\fP:: Protect a
.RE
.sp
generation from pruning. \fBunpin\fP \fIID\fP
.RS 4
Allow pruning again.
.RE
.sp
\fBsecret hash\fP \fIPASSWORD\fP
.RS 4
One\-way hash for system.lua.
.RE
.sp
\fBsecret encrypt\fP \fIVALUE\fP
.RS 4
Encrypt a string for this machine.
.RE
.sp
\fBsecret decrypt\fP \fISECRET\fP
.RS 4
Decrypt a machine\-local secret.
.RE
.sp
\fBsecret export\-key\fP
.RS 4
Export the master key (base64).
.RE
.sp
\fBsecret import\-key\fP \fIKEY\fP
.RS 4
Import a master key.
\fBdistro build\fP (\fB\-t\fP, \fB\-\-target\fP=\fIDEV|IMG\fP and \fB\-c\fP, \fB\-\-config\fP=\fILUA\fP
.RE
.sp
required) [\fB\-\-dry\-run\fP]
.RS 4
Build a ZoiOS image or install to disk.
.RE
.sp
\fBdistro chroot\fP \fITARGET\fP [\fB\-r\fP, \fB\-\-run\fP=\fICMD\fP] [\fB\-v\fP, \fB\-\-verbose\fP]
.RS 4
Enter
a sysroot chroot with automatic mounts.
.RE
.SH "MISCELLANEOUS"
.sp
\fBabout\fP
.RS 4
Show detailed application information and credits.
.RE
.sp
\fBversion\fP, \fBv\fP
.RS 4
Print concise version and build information.
.RE
.sp
\fBextension\fP, \fBext\fP (\fBadd\fP | \fBremove\fP) \fINAME\fP
.RS 4
Add or remove a Zoi extension.
.RE
.sp
\fBhelper\fP \fISUBCOMMAND\fP, Small utilities. \fBget\-hash\fP \fISOURCE\fP [\fB\-\-hash\fP=\fIsha512|sha256\fP]
.RS 4
Hash
.RE
.sp
a local file or URL. \fBvalidate\fP (\fBval\fP) \fIFILE\fP
.RS 4
Validate a
\f(CRrepo.yaml\fP, registry, hook, or advisories file. The \f(CRelevate\-*\fP
subcommands are internal helpers used for privilege escalation and are
not meant to be run directly.
.RE
.sp
External subcommands (plugins)
.RS 4
Any unknown subcommand is forwarded to an installed plugin, so \fBzoi
myplugin args.\|.\|.\fP runs the \f(CRzoi\-myplugin\fP extension.
.RE
.SH "CONFIGURATION"
.sp
Zoi merges configuration from three layers; a project file overrides the
user file, which overrides the system file unless a system \fBpolicy\fP locks
a setting. See the online configuration reference for every key.
.sp
\fBSystem\fP (/etc/zoi/config.yaml)
.RS 4
Machine\-wide defaults and administrator policy locks.
.RE
.sp
\fBUser\fP (~/.config/zoi/config.yaml)
.RS 4
Per\-user preferences. The most commonly adjusted keys include the
default registry, \fBjobs\fP, \fBmax_delta_steps\fP (sequential delta\-upgrade
limit, default 3), \fBoffline_mode\fP, \fBcache_mirrors\fP, \fBpkg_dirs\fP, and
\fBsystem_generations_limit\fP.
.RE
.sp
\fBProject\fP (./.zoi/pkgs/config.yaml)
.RS 4
Per\-project overrides for the current directory.
.RE
.SH "FILES"
.sp
\fB/etc/zoi/config.yaml\fP
.RS 4
System\-wide configuration file.
.RE
.sp
\fB~/.config/zoi/config.yaml\fP
.RS 4
User configuration file.
.RE
.sp
\fB$XDG_DATA_HOME/zoi/\fP
.RS 4
User data directory (database, store, and caches). Falls back to
\fB~/.local/share/zoi/\fP on most systems.
.RE
.sp
\fB./zoi.lua\fP
.RS 4
Unified project and repository configuration: metadata, packages, tasks,
environments, pinned imports, and selectable package exports.
.RE
.sp
\fB./zoi.lock\fP
.RS 4
Complete reproducibility state: manifest/config hashes, registry and import
commits, root requirements, package sources, selections, and content hashes.
.RE
.sp
\fB./.zoi/\fP
.RS 4
Per\-project lockfile, imported repository clones, registry database, and
local package store.
.RE
.SH "ENVIRONMENT"
.sp
\fBXDG_CONFIG_HOME\fP, \fBXDG_DATA_HOME\fP, \fBXDG_CACHE_HOME\fP
.RS 4
Respect the base\-directory specification for configuration, data, and
cache locations.
.RE
.sp
\fBHOME\fP
.RS 4
Home directory, used to locate the user configuration and data when the
XDG variables are unset.
.RE
.sp
\fBNO_COLOR\fP
.RS 4
When set, colorized terminal output is disabled.
.RE
.SH "EXIT STATUS"
.sp
\fB0\fP
.RS 4
Success.
.RE
.sp
\fB1\fP
.RS 4
An error occurred during the operation.
.RE
.SH "EXAMPLES"
.sp
Install a package from the default registry, answering yes to prompts:
.sp
.if n .RS 4
.nf
.fam C
zoi \-y install @core/ripgrep
.fam
.fi
.if n .RE
.sp
Preview an upgrade plan without changing anything:
.sp
.if n .RS 4
.nf
.fam C
zoi update \-\-all \-\-dry\-run
.fam
.fi
.if n .RE
.sp
Update everything and explain the decisions:
.sp
.if n .RS 4
.nf
.fam C
zoi update \-\-all \-\-explain
.fam
.fi
.if n .RE
.sp
Build a package for the current platform and sign it:
.sp
.if n .RS 4
.nf
.fam C
zoi package build ./mypkg.pkg.lua \-\-sign mykey
.fam
.fi
.if n .RE
.sp
Generate a delta patch between two archives:
.sp
.if n .RS 4
.nf
.fam C
zoi package delta old.zpa new.zpa \-o new.zdelta
.fam
.fi
.if n .RE
.sp
Enter a development shell for the current project:
.sp
.if n .RS 4
.nf
.fam C
zoi dev
.fam
.fi
.if n .RE
.sp
Execute a binary without installing it:
.sp
.if n .RS 4
.nf
.fam C
zoi exec @core/ripgrep \-\- \-\-version
.fam
.fi
.if n .RE
.SH "BUGS"
.sp
Report bugs and request features in the project tracker at
.URL "https://gitlab.com/zillowe/zillwen/zusty/zoi" "" "."
.SH "SEE ALSO"
.sp
\fBzoi\-rs\fP(3), \fBzoi\-lua\fP(5), \fBzoid\fP(8)
.sp
Full online documentation: \c
.URL "https://zillowe.qzz.io/docs/zds/zoi" "" ""
.sp
Project repository and issue tracker:
.URL "https://gitlab.com/zillowe/zillwen/zusty/zoi" "" ""
.SH "COPYING"
.sp
Copyright \(co Zillowe Foundation. Licensed under Apache\-2.0.