Zillowe Docs - Features & Usage

Zoi is packed with features designed to make package management and environment setup seamless and powerful across all your systems.

Core Features

Cross-Platform: Works natively on Linux, macOS, and Windows, supporting amd64 and arm64 architectures. Write one package definition and let Zoi handle the platform differences.
Sysroot Support (--root): Operates on a different root directory, allowing you to bootstrap entire OS images, containers, or embedded systems from the outside.
Metadata Caching: Uses an optimized SQLite database with FTS5 indexing for near-instant search and listing of thousands of packages, ensuring performance scales to enterprise levels.
Dependency Tree Visualization (zoi tree): View the exact Directed Acyclic Graph (DAG) resolved by the SAT solver, showing exactly why specific versions were chosen.
SAT-Powered Dependency Resolution: Uses the PubGrub algorithm (the same engine powering Cargo and uv) to mathematically solve complex version constraints, automatically handling backtracking and deep version clashing for 100% reliable system upgrades.
Strict Offline Mode: A global --offline flag that guarantees Zoi will not touch the network, relying exclusively on local metadata and archive caches for secure, air-gapped environments.
Global Transaction Hooks: Automate system maintenance tasks (like font cache updates) based on modified file paths. Hooks run once per transaction, preventing redundant script execution.
Development Shells (zoi dev): Enter a subshell where all project dependencies are locally installed and environment variables like LD_LIBRARY_PATH, CPATH, and PKG_CONFIG_PATH are automatically configured for seamless development.
Service Management (zoi service): Define background processes in .pkg.lua and manage them via Zoi using your system's native manager (systemd, launchd, or sc.exe).
Reverse Search (zoi provides): Instantly find which package provides a specific binary or file path across the entire registry.
Version Multiplexing via Intelligent Shims: Automatically switch between different versions of the same tool (e.g. Node.js 18 vs 20) based on your current project (zoi.yaml), global configuration, or legacy files (like .nvmrc and .python-version) via its extensible Lua plugin system. Replaces static symlinks with intelligent shims that resolve the correct version at runtime.
Ephemeral Environments: Enter a temporary subshell with specific packages available in PATH without installing them globally. Perfect for testing tools or running scripts with specific language versions.
Dynamic Package Definitions: Packages are defined using .pkg.lua scripts, offering unparalleled flexibility. Use Lua to dynamically determine download URLs, set up build steps, and handle platform-specific logic.
Universal Package Support: Install software from any source:
- Pre-compiled binaries
- Compressed archives (.tar.gz, .zip, .tar.xz, etc.)
- Build from source code
- Local archive search directories (--pkg-dir)
Extensive Dependency Management: Zoi integrates with over 40 external package managers. You can define dependencies from apt, brew, cargo, npm, pip, go, zig, and many more, and Zoi will install them using the native manager, learn more.
Rich Dependencies: Go beyond simple lists. Define runtime and build dependencies with:
- required: Dependencies that are always installed.
- optional: Dependencies that the user is prompted to install.
- options: Groups of dependencies where the user can select one or more.
Changing Install Reasons: Use zoi mark to change whether a package is considered an explicit installation or a dependency, enabling granular control over zoi autoremove.
Project-Level Environments: Use a zoi.yaml file in your project root to define custom commands and development environments. Manage project-specific tasks, tools, packages, and environment variables with zoi run, zoi env, and zoi dev, learn more.
Declarative System Configuration (Arch Linux): Manage your entire system state via a centralized /etc/zoi/zoi.lua file. Define packages, extensions, and services in one place and apply them with zoi system apply for a Nix-like reproducible setup on Arch Linux.
Repository-Based System: Zoi uses Git-based repositories to store package definitions. Use the official Zoidberg registry, add community repositories, or create your own private or public repositories with zoi repo add.
Secure and Verifiable: Ensure the integrity and authenticity of your packages:
- Checksums: Verify downloads against SHA512, SHA256, or MD5 hashes.
  - GPG Signatures: Verify package archives against maintainer PGP keys. Manage keys easily with the zoi pgp command set.
  - Built-in Keyring: Supports baking trusted public keys directly into the Zoi binary for out-of-the-box registry verification.
  - Enhanced File Conflict Detection: Prevents packages from accidentally overwriting existing files. Supports checking conflicts via remote metadata before downloading the package and automatically handles safe upgrades by ignoring existing files owned by the same package.
  - Configuration File Handling: Automatically handles updates to configuration files, creating .zoinew files for new versions and .zoisave files for user-modified configurations upon removal.

Advanced Capabilities

Virtual Packages (provides): Declare that a package provides a certain feature or virtual package, allowing other packages to depend on it.
Package Replacement (replaces): Explicitly declare that a package replaces another, prompting for the removal of the old package upon installation.
Smart Provider Selection: When multiple packages provide the same virtual dependency (e.g. mariadb and mysql both providing sql-server), Zoi presents an interactive comparison table showing licenses, sizes, and descriptions, allowing you to choose the best provider for your needs.
Versatile Package Types: Zoi supports more than just standard applications:
- Package: A standard software package.
- Collection: A metapackage that groups other packages together.
- App: A template for bootstrapping new projects (zoi create).
- Extension: A package that modifies Zoi's own configuration.
Package Testing: An integrated testing framework (zoi package test) allows authors to define and run tests for their packages directly from the .pkg.lua file, ensuring package quality and correctness before publishing.
Split Packages: Define a package that can be split into multiple, independently installable sub-packages. This is perfect for large projects like the Linux kernel, where you can separate the kernel, headers, and docs. Zoi manages these components granularly; uninstalling or rolling back one sub-package will not interfere with other installed components from the same base project.
Local Package Development: A dedicated zoi package command set streamlines the creation and testing of packages locally:
- zoi package build: Build a distributable package archive (.pkg.tar.zst).
- zoi package install: Install a package from a local archive for testing.
Powerful CLI Tools: Zoi offers a rich set of commands for package management and inspection:
- zoi about: Show application information, credits, and build details.
- zoi autoremove: Remove packages that were installed as dependencies but are no longer needed.
- zoi cache: Manage and populate the local package archive cache.
- zoi clean: Clear the cache of downloaded package binaries.
- zoi dev: Enter a development shell for the current project, with environment variables (PATH, LD_LIBRARY_PATH, CPATH, etc.) automatically set up based on dependencies.
- zoi downgrade: Interactively choose and install an older version of a package.
- zoi exec: Download and run a package's binary in a temporary cache without a full installation.
- zoi files: List all files owned by an installed package.
- zoi history: View the audit log of past package operations (install, uninstall, upgrade).
- zoi info: Display detected system information, including OS, architecture, and available package managers.
- zoi list: List all installed packages, or all available packages from active repositories.
- zoi man: Read package manuals directly in the terminal.
- zoi mark: Change the installation reason of a package (explicit vs dependency).
- zoi owner: Find which package owns a specific file on the system.
- zoi pin: Lock a package to a specific version to prevent updates.
- zoi provides: Find which package provides a specific command or file.
- zoi rollback: Revert a package to its previously installed version or the entire last transaction.
- zoi search: Searches for packages by name or description.
- zoi service: Manage background services for installed packages.
- zoi tree: Visualize the dependency tree of a package.
- zoi unpin: Unpin a package, allowing it to be updated again.
- zoi version: Print concise version and build information.
- zoi why: Understand why a specific package is installed (e.g. as a dependency).
- zoi doctor: Checks for common issues with your Zoi installation and provides actionable suggestions. It performs the following checks:
  - Broken Symlinks: Scans for broken symbolic links in Zoi's binary directories.
  - PATH Configuration: Verifies that the Zoi binary directory is included in your system's PATH.
  - Outdated Repositories: Checks if your local package database has been synced recently.
  - Orphaned Packages: Identifies packages installed as dependencies that are no longer needed by any other package.
  - Duplicate Package IDs: Identifies packages with the same name/path across different registries, which can cause ambiguity.
  - PGP Configuration: Verifies if trusted PGP keys specified in your configuration are present in the local keyring.
  - Package Record Integrity: Validates that all packages recorded in zoi.pkgs.json are actually present in the installation store.
Shell Integration:
- zoi shell: Automatically configures your shell's PATH for Zoi and installs shell completion scripts for Bash, Zsh, Fish, Elvish and Powershell.
Library Support: Use zoi as a Rust library in your own applications to programmatically manage packages. The zoi-rs crate is available on crates.io, learn more.

Command Reference

This section provides a detailed reference for all of Zoi's commands.

Global Options

These options can be used with any command:

-y, --yes: Automatically answer "yes" to all confirmation prompts.
-v, --version: Print detailed version information.
--root <DIR>: Operate on a different root directory (sysroot).
--offline: Do not attempt to connect to the network.
--pkg-dir <DIR>: Additional directory to search for .pkg.tar.zst archives.

`zoi about`

Shows detailed application information and credits.

`zoi autoremove`

Removes packages that were installed as dependencies but are no longer needed.

Options:

--dry-run: Do not actually remove packages, just show what would be done.

`zoi cache`

Manage Zoi's local package archive cache.

Subcommands:

add <FILES...>: Add .pkg.tar.zst archives to the local cache.
ls: List all archives currently in the cache.
clear: Clear the local archive cache.

`zoi clean`

Clears the cache of downloaded package binaries.

Options:

--dry-run: Do not actually clear the cache, just show what would be done.

Enter a development shell for the current project. This command reads zoi.yaml, ensures all packages in pkgs are installed, and sets up a subshell with PATH, LD_LIBRARY_PATH, CPATH, and PKG_CONFIG_PATH pointing to the project's dependencies.

Arguments:

[run]: Optional command to run in the dev shell instead of starting an interactive shell.

Options:

-r, --run <COMMAND>: Alias for the [run] argument.

`zoi downgrade <package>`

(alias: dg)

Interactively choose and install an older version of a package from the local store or archive cache.

Arguments:

<package>: The name of the package to downgrade.

`zoi create <source> [app_name]`

Create an application using a package template.

Arguments:

<source>: Package name, @repo/name, local .pkg.lua path, or URL.
[app_name]: The application name to substitute into template commands.

`zoi env [env_alias]`

Manage and set up project environments from a local zoi.yaml file.

Arguments:

[env_alias]: The alias of the environment to set up. If not provided, an interactive prompt is shown.

`zoi exec <SOURCE> [ARGS]...`

(alias: x)

Download and execute a binary package without installing it.

Arguments:

<SOURCE>: Package name, local path, or URL to execute.
[ARGS]...: Arguments to pass to the executed command.

Options:

--upstream: Force execution from a fresh download, bypassing any cache.
--cache: Force execution from the cache, failing if the package is not cached.
--local: Force execution from the local project installation.

`zoi extension`

(alias: ext)

Manage Zoi extensions.

Subcommands:

add <name>: Add an extension.
remove <name>: Remove an extension.

`zoi files <package>`

List all files owned by a package.

Arguments:

<package>: The name of the package.

`zoi history`

Shows the history of past package operations (install, uninstall, upgrade) from the audit log. Requires audit_log_enabled: true in configuration.

`zoi helper`

Helper commands for various tasks.

Subcommands:

get-hash <source>: Get a hash of a local file or a file from a URL.
- --hash <sha512|sha256>: The hash algorithm to use (default: sha512).

`zoi info`

Displays detected operating system and architecture information.

`zoi install [SOURCES]...`

(alias: i)

Installs one or more packages. For split packages, you can specify a sub-package using the package:sub-package syntax. If you specify a base package, Zoi will install the main_subs defined in the package.

Zoi resolves dependencies, checks for conflicts, and then sequentially downloads and installs each package, showing progress bars for both download and installation phases.

Arguments:

[SOURCES]...: Package names (e.g. my-pkg, my-pkg:sub), local paths, or URLs to .pkg.lua files.

Options:

--repo <REPO>: Install from a git repository (e.g. 'Zillowe/Hello', 'gl:Zillowe/Hello').
--force: Force re-installation even if the package is already installed.
--all-optional: Accept all optional dependencies.
--scope <user|system|project>: The scope to install the package to.
--local: Install packages to the current project (alias for --scope=project).
--global: Install packages globally for the current user (alias for --scope=user).
--save: Save the package to the project's zoi.yaml.
--type <TYPE>: The type of package to build if building from source. Specifying a type other than pre-compiled or pre-built will force a local build.
--build (alias: -b): Force building from source even if a pre-compiled archive is available in the registry.
--dry-run: Do not actually install, just show what would be done.

`zoi list`

(alias: ls)

Lists installed or all available packages.

Options:

-a, --all: List all packages from the database, not just installed ones.
-m, --foreign: List packages not found in any configured registry.
--registry <HANDLE>: Filter by specific registry handle.
--repo <REPO>: Filter by repository.
-t, --type <TYPE>: Filter by package type (package, app, collection, extension).

`zoi man <package_name>`

Shows a package's manual.

Arguments:

<package_name>: The name of the package to show the manual for.

Options:

--upstream: Always look at the upstream manual even if it's downloaded.
--raw: Print the manual to the terminal raw.

`zoi mark <PACKAGES>...`

Modify the installation reason of one or more packages.

Options:

--as-dependency (alias: --asdeps): Mark packages as dependencies.
--as-explicit (alias: --asexplicit): Mark packages as explicitly installed.

`zoi owner <path>`

(alias: owns)

Find which package owns a file.

Arguments:

<path>: Path to the file.

`zoi package`

(alias: pkg)

Build, create, and manage Zoi packages.

Subcommands:

build <package_file>: Build a package from a .pkg.lua file.
- --type <TYPE>: (Required) The type of package to build (e.g. 'source', 'pre-compiled').
- -p, --platform <PLATFORM>: The platform to build for (default: current).
- -o, --output-dir <DIR>: Directory to output the built package to.
- --sign <KEY>: Sign the package with the given PGP key.
- --sub <SUB_PACKAGES...>: For a split package, build only the specified sub-packages.
- --test: Run package tests before building.
test <package_file>: Run tests for a package. This command accepts the same arguments as build.
- --type <TYPE>: (Required) The build type to use for testing.
- -p, --platform <PLATFORM>: The platform to test on.
- --sub <SUB_PACKAGES...>: For a split package, test only the specified sub-packages.
install <package_file>: Install a package from a local archive.
- --scope <user|system>: The scope to install the package to (default: user).
- --sub <SUB_PACKAGES...>: For a split package, install only the specified sub-packages from the archive.

`zoi pgp`

Manage PGP keys for package signature verification.

Subcommands:

add: Add a PGP key from a file, URL, or a keyserver.
- --path <PATH>: Path to the PGP key file.
- --fingerprint <FINGERPRINT>: Fingerprint of the PGP key to fetch.
- --url <URL>: URL of the PGP key to import.
- --name <NAME>: Name to associate with the key.
remove (alias: rm): Remove a PGP key.
- <name>: Name of the key to remove.
- --fingerprint <FINGERPRINT>: Fingerprint of the key to remove.
list (alias: ls): List all imported PGP keys.
search <term>: Search for a PGP key by user ID or fingerprint.
show <name>: Show the public key of a stored PGP key.
verify: Verify a file's detached signature.
- --file <FILE>: Path to the file to verify.
- --sig <SIG>: Path to the detached signature file.
- --key <KEY>: Name of the key in the local store to use for verification.

`zoi pin <package> <version>`

Pin a package to a specific version.

Arguments:

<package>: The name of the package to pin.
<version>: The version to pin the package to.

`zoi repo`

(aliases: repositories)

Manage package repositories.

Subcommands:

add [repo_or_url]: Add an official repo by name or clone from a git URL.
remove <repo_name> (alias: rm): Remove a repository from the active configuration.
list [all] (alias: ls): List active repositories. Use list all to show all available.
git: Manage cloned git repositories.
- list (alias: ls): Show cloned git repositories.
- rm <repo_name>: Remove a cloned git repository.

`zoi provides <TERM>`

Find which package provides a specific command or file. This command searches through package names, explicitly defined binaries (bins), and the global file index (if populated via zoi sync --files).

Arguments:

<TERM>: The command name (e.g. magick) or a file path fragment (e.g. bin/magick).

`zoi rollback [PACKAGE]`

Rollback a package to the previously installed version.

Arguments:

[PACKAGE]: The name of the package to rollback.

Options:

--last-transaction: Rollback the last transaction.

`zoi run [cmd_alias] [args]...`

Execute a command defined in a local zoi.yaml file.

Arguments:

[cmd_alias]: The alias of the command to execute.
[args]...: Arguments to pass to the command.

`zoi search <search_term>`

(alias: s)

Searches for packages by name or description.

Arguments:

<search_term>: The term to search for.

Options:

--registry <HANDLE>: Filter by specific registry handle.
--repo <REPO>: Filter by repository.
--type <TYPE>: Filter by package type.
-t, --tag <TAGS>: Filter by tags (comma-separated).
-f, --files: Search for files provided by packages instead of package names.
-i, --interactive: Open results in an interactive TUI.

`zoi service <ACTION> [PACKAGE]`

(alias: svc)

Manage background services for installed packages. This command uses the native system manager (systemd on Linux, launchd on macOS, sc.exe on Windows).

Subcommands:

start <package>: Start the service defined by the package.
stop <package>: Stop the service.
restart <package>: Restart the service.
status <package>: Show the current status of the service.
list (alias ls): List all installed packages that define a service and their current status.

`zoi shell [shell]`

Installs completion scripts for a given shell and setup PATH for Zoi. If packages are provided, it enters an ephemeral environment.

Arguments:

[shell]: The shell to install completions for (bash, zsh, fish, elvish, powershell).

Options:

-p, --package <PACKAGE>: Package(s) to include in the ephemeral environment.
-r, --run <COMMAND>: Run a command in the ephemeral environment and exit.
--scope <user|system>: The scope to apply the shell setup to (default: user).

`zoi show <package_name>`

Shows detailed information about a package.

Arguments:

<package_name>: The name of the package to show.

Options:

--raw: Display the raw, unformatted package file.

`zoi sync`

(alias: sy)

Downloads or updates the package database from the remote repository.

Options:

-v, --verbose: Show the full git output.
--fallback: Fallback to other mirrors if the default one fails.
--no-pm: Do not check for installed package managers.
--no-shell-setup: Do not attempt to set up shell completions after syncing.
-f, --files: Download and index file lists for global search.

Subcommands:

add <url>: Add a new registry.
remove <handle>: Remove a configured registry by its handle.
list: List configured registries.
set <url>: Set the default registry URL (default, github, gitlab, codeberg, or a URL).

`zoi telemetry <action>`

Manage telemetry settings.

Arguments:

<action>: status, enable, or disable.

`zoi tree <PACKAGES>...`

Visualize the dependency tree of one or more packages. This command uses the PubGrub SAT solver to resolve all dependencies and sub-dependencies, then prints them in a hierarchical tree format.

Arguments:

<PACKAGES>...: One or more package names, paths, or URLs to visualize.

`zoi uninstall <PACKAGES>...`

(aliases: un, rm, remove)

Uninstalls one or more packages. To uninstall a sub-package, use the package:sub-package syntax. Uninstalling a base package will remove all its installed sub-packages.

Arguments: