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.
- macOS Integration: Automatically handles macOS .app bundles, stripping Gatekeeper quarantine flags and symlinking them to ~/Applications or /Applications.
Just-in-Time Privilege Escalation: Automatically prompts for sudo password only when system-wide operations (like extracting to /var/lib/zoi or linking to /usr/local/bin) are required. This ensures your local package database and caches remain in your user-space, avoiding the need to run the entire CLI as root.
ZoiOS Management (Exclusive): Manage an entire operating system state declaratively via /etc/zoi/system.lua.
- Generation-Based Architecture: Every system change creates a new, versioned "Generation" in the store. Revert any OS update instantly via symlink flip or bootloader selection.
- Transactional FHS View: Zoi generates a standard FHS symlink farm (/usr/bin, /usr/lib, etc.) pointing to versioned assets, ensuring 100% compatibility with standard Linux software while maintaining a hashed store.
- Universal Distro Builder: Bootstrap an entire ZoiOS distribution onto a new disk or directory with a single command (zoi system distro build). Handles formatting, subvolume creation, and base system installation.
Explicit Scope Control: Restrict package installation to specific scopes (user, system, or project) using the scopes metadata field. Zoi automatically enforces these constraints during installation and updates.
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.
Decentralized Security Advisories: Automated vulnerability tracking via .sec.yaml files co-located with packages in the registry. Zoi proactively warns you during installation or upgrades if a package has known security issues, requiring explicit confirmation to proceed.
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.
Native Linux Sandboxing: Run packages in a secure, "default-deny" isolated environment using Bubblewrap. Package maintainers explicitly define network, system, and file access permissions, protecting your host system from malicious or buggy software.
Automated Relocation Engine: Automatically rewrites ELF binary headers (RUNPATH/RPATH) to use $ORIGIN relative paths during build. This ensures Zoi packages are fully relocatable and can find their internal shared libraries regardless of where they are installed or symlinked.
Lua-Based Project Configuration (zoi.lua): Define project environments with a powerful, scriptable Lua API. Supports dynamic dependency selection, registry overrides, and complex environment setup.
Hermetic Project Environments: Strictly isolate project dependencies and registries within ./.zoi/pkgs/. Ensure that project-level syncs do not affect global state and remain reproducible across machines.
Pinned Registry Inputs: Lock registries to exact Git revisions (branch, tag, or commit hash) in zoi.lua. zoi.lock automatically pins these to SHA-1 hashes for absolute reproducibility.
Reproducible Project Installs (--frozen): Rebuild a project environment from zoi.lock without re-resolving versions, sub-packages, or recorded dependency choices. Zoi Specification v2 lockfiles include directory hashes to verify the integrity of the entire local state.
Automated Dev Repo Discovery (zoi dev --repo): Instantly enter a development shell for any Git repository. Zoi clones the repository to a temporary directory, sets up the environment defined in its zoi.lua, and cleans up automatically on exit.
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.
Transaction Inspection: Inspect recorded package operations and touched files with zoi transaction list, zoi transaction show, and zoi transaction files.
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.
Shell Completions via zshell(): Bundle shell completion scripts (Bash, Zsh, Fish, Elvish) with your packages using the zshell() lifecycle function. Zoi automatically symlinks completions into per-package directories under ~/.zoi/pkgs/shell/ and cleans them up on uninstall. Supports versioned completions since each package version's files are stored separately in the Zoi store.
Generic Project Handlers via Plugins: Extend zoi install to support any ecosystem (NPM, Pip, etc.) by implementing simple Lua hooks that detect project files and manage dependencies using native high-performance APIs.
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.
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 (.zpa).
- zoi package bundle: Bundle a package and its local assets into a source archive (.zsa).
- zoi package install: Install a package from a local archive for testing.
- zoi package doctor: Lint and validate .pkg.lua definitions before testing/building.
- zoi package inspect: Parse a package definition and output resolved metadata (supports JSON).
- zoi package init-lsp: Initialize LSP support with EmmyLua type definitions and .luarc.json.
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 audit: Scan installed packages for known security vulnerabilities.
- zoi autoremove: Remove packages that were installed as dependencies but are no longer needed.
- zoi download: Download a package archive (.zpa) or source bundle (.zsa) to local cache or output directory.
- zoi cache: Manage and populate the local package archive cache.
- zoi clean: Clear the cache of downloaded package binaries.
- zoi clone: Clone the git repository of a package to a local directory.
- 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 migrate scoop: Convert a Scoop manifest (.json) into a Zoi .pkg.lua.
- 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 roll back the newest remaining transaction log.
- 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 transaction: Inspect recorded transactions and the files they changed.
- 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 the lockfile are actually present in the installation store.
  - Ghost Dependents: Scans for broken dependent links where the parent package is missing, offering to prune them.
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.
Zoi Mini (Lightweight Service): A minimal version of Zoi that operates without a local database, resolving package metadata and vulnerabilities on the fly from the Zoidberg registry. Perfect for one-liner installations via zm.sh or zm.ps1. Supports install, update, uninstall, and list commands with aliases (i, up, un, ls).

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 .zpa archives.

`zoi about`

Shows detailed application information and credits.

`zoi audit`

Scans installed packages for known security vulnerabilities. It can also be used to inspect all advisories in the registry.

Options:

-a, --all: List all security advisories in the database, not just for installed packages.
--registry <HANDLE>: Filter advisories by specific registry handle.
--repo <REPO>: Filter advisories by specific repository.

`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 .zpa archives to the local cache.
ls: List all archives currently in the cache.
mirror add <URL>: Add a binary/cache mirror base URL.
mirror remove <URL>: Remove a configured binary/cache mirror.
mirror ls: List configured binary/cache mirrors.
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.

`zoi clone <package> [location]`

Clones the git repository of a package to a local directory. If no location is specified, it clones into a directory named after the package. Use . as the location to clone into the current directory.

Arguments:

<package>: Package name, @repo/name, local .pkg.lua path, or URL.
[location]: The directory to clone the repository into.

`zoi dev`

(alias: develop)

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.

Options:

-r, --run <COMMAND>: Run a command in the dev shell instead of starting an interactive shell.

`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.

Options:

--export-shell <shell>: (Hidden) Outputs environment variable exports for evaluation by a shell hook.

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

(alias: x)

Resolve a package and its dependencies into an ephemeral environment, then run the specified binary directly. Uses bwrap for sandboxed packages. Cleans up ephemeral packages after execution.

Arguments:

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

Options:

--bin <NAME>: Specific binary to run (required if the package provides multiple binaries).
-v, --verbose: Show execution details (resolution, installation, sandboxing).

`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.

Options:

--verify: Verify audit log chain integrity instead of printing entries.
--export <PATH>: Export audit history to a file.
--ndjson: Export as newline-delimited JSON instead of a JSON array. Requires --export.

`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).
validate <source>: Validate a .pkg.lua or Zoi spec file for correctness.

`zoi info`

Displays detected operating system and architecture information.

`zoi install [SOURCES]...`

(aliases: i, in, add)

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:

--purl <PURL>: Install a package by its Package URL (PURL), e.g. pkg:zoi/zoidberg/core/curl.
--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.
--frozen: Install exactly what is pinned in zoi.lock (project scope only, lockfile must already exist, no lockfile updates are allowed, and recorded sub-package/dependency selections are preserved).
--retry <N>: Retry failed downloads up to N attempts (minimum 1, default 3).
-v, --verbose: Show additional install details, including package origins and preflight information.
--explain: Print dependency-selection and install-decision explanation.
--plan-json: Emit machine-readable install plan JSON.
--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.
-o, --outdated: List only installed packages that have updates available in the registry.
-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.
--no-tui: Do not use the TUI, use the system pager instead.

`zoi mark <PACKAGES>...`

(alias: m)

Modify the installation reason of one or more packages.

Options:

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

`zoi migrate scoop <input>`

Convert a Scoop package manifest (.json/JSON5) into a Zoi .pkg.lua package file with broad field coverage.

Arguments:

<input>: Path to the Scoop manifest file.

Options:

-o, --output <PATH>: Output path for generated .pkg.lua.
--repo <REPO>: Value for metadata.repo in generated package.
--name <NAME>: Override output package name.
--version <VERSION>: Override package version.
--maintainer-name <NAME>: Maintainer name to set in metadata.
--maintainer-email <EMAIL>: Maintainer email to set in metadata.
--dry-run: Print generated .pkg.lua instead of writing a file.

`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>: The type of package to build (e.g. source, pre-compiled). If omitted, Zoi chooses pre-compiled, then source, then the first listed type.
- -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.
- --install-deps: Automatically install build-time dependencies defined in the package before building.
- --version-override <VERSION>: Override the package version.
- --method <native|docker>: The build method to use (default: native).
- --image <IMAGE>: The Docker image to use for the build (required for --method docker).
- --fakeroot: Force root ownership (UID/GID 0) in the built archive.
test <package_file>: Run tests for a package. This command accepts the same arguments as build.
- --type <TYPE>: The build type to use for testing. If omitted, Zoi chooses pre-compiled, then source, then the first listed type.
- -p, --platform <PLATFORM>: The platform to test on.
- --sub <SUB_PACKAGES...>: For a split package, test only the specified sub-packages.
- --version-override <VERSION>: Override the package version for testing.
- --fakeroot: Use fakeroot for the test build.
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.
- --yes: Automatically answer yes to prompts.
doctor <package_file>: Lint and validate a .pkg.lua package definition. Performs consistency checks, including verifying that the metadata repo field matches the file's location in the registry.
- --platform <PLATFORM>: Validate as a specific platform (defaults to current).
- --version-override <VERSION>: Override package version while validating.
inspect <package_file>: Parse a package definition and output its fully resolved metadata.
- --json: Output as pretty-printed JSON (ideal for CI/CD and automation).
- --platform <PLATFORM>: Resolve metadata for a specific platform.
- --version-override <VERSION>: Override package version while inspecting.
init-lsp: Initialize LSP support with EmmyLua type definitions and .luarc.json.

`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 (populated automatically during zoi sync).

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.

If multiple installed packages match the same name, Zoi will prompt you to choose the exact installed package. For non-interactive use, pass an explicit source such as #handle@repo/name[:sub]@version.

Options:

--last-transaction: Roll back the newest remaining transaction log.

`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).
--sort <name|repo|type>: Sort results by field (default: name).
-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 --hook is provided, it outputs shell-specific hook scripts for automatic environment activation (direnv-style). If packages are provided, it enters an ephemeral environment.

Arguments:

[shell]: The shell name (bash, zsh, fish, elvish, powershell).

Options:

--hook: Generate a shell hook script to be evaluated by your shell configuration (e.g. eval "$(zoi shell --hook bash)").
-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.
--purl: Display the Package URL (PURL) for the package.

If the package is installed more than once across scopes or registries, Zoi will prompt you to choose which installed package status to display.

`zoi sync`

(alias: sy)

Downloads or updates the package database from the remote repository.

Flags:

-v, --verbose: Show detailed git output and intermediate sync steps.
--fallback: Fallback to other mirrors if the default one fails.
--no-pm: Do not check for installed native package managers.
--force: Rebuild all registry databases from scratch by removing existing caches, git clones, and re-cloning. Installed packages and their records are preserved.
--local: Sync registries to the project's local .zoi/pkgs/db/ using revisions from zoi.lua.
--frozen: When used with --local, sync using revisions from zoi.lock instead of zoi.lua.

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:

<PACKAGES>...: One or more packages to uninstall.

Options:

--scope <user|system|project>: The scope to uninstall the package from.
--local: Uninstall packages from the current project.
--global: Uninstall packages globally for the current user.
--save: Remove the package from the project's zoi.yaml.
-s, --recursive: Recursively remove dependencies that are no longer needed.
--explain: Show uninstall reasoning and reverse-dependency impact.
--plan-json: Emit machine-readable uninstall plan JSON.

`zoi unpin <package>`

Unpin a package, allowing it to be updated.

Arguments:

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

`zoi update [PACKAGES]...`

(alias: up)

Updates one or more packages to their latest versions. When using --all, Zoi also prints explicit pinned/skipped summaries and advisory deltas for each upgrade candidate.

Arguments:

[PACKAGES]...: The name(s) of the package(s) to update. If none are provided, you must use --all.

Options:

--all: Update all installed packages.
--interactive: Interactively choose a subset of upgrade candidates (requires --all).
--explain: Explain why each package is selected or skipped.
--plan-json: Emit machine-readable update plan JSON.
--dry-run: Do not actually perform the update, just show what would be done.

`zoi use <PACKAGES>...`

(alias: u)

Adds a tool to the current project or global configuration and installs it in one step.

Arguments:

<PACKAGES>...: Package identifiers (e.g. node@20).

Options:

-g, --global: Add to global configuration (user versions map) instead of the local project (zoi.yaml).
-y, --yes: Automatically answer yes to prompts (including JIT installation prompts).

`zoi upgrade`

(alias: ug)

Upgrades the Zoi binary to the latest version.

Options:

--force: Force a full download.
--tag <TAG>: Upgrade to a specific git tag.
--branch <BRANCH>: Upgrade to the latest release of a specific branch.

Subcommands:

list (alias: ls): List available transaction logs with their start time and operation count.
show <id>: Show the ordered operations recorded in a transaction.
files <id>: List the unique files modified by a transaction.

`zoi doctor`

Checks for common issues and provides actionable suggestions.

Features & Usage

Zillowe Foundation

On this page