Zillowe FoundationZillowe Documentation
ZDSZoi

Features & Usage

A comprehensive list of Zoi's features and command examples.

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.

  • 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

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

  • 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 and zoi env, 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.
    • File Conflict Detection: Prevents packages from accidentally overwriting existing files by prompting for confirmation.

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

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

  • 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 check: Verify that essential third-party tools (like git) are installed.
    • zoi clean: Clear the cache of downloaded package binaries.
    • 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 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 owner: Find which package owns a specific file on the system.
    • zoi pin: Lock a package to a specific version to prevent updates.
    • zoi rollback: Revert a package to its previously installed version or the entire last transaction.
    • 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.

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

zoi about

Shows detailed application information and credits.

zoi autoremove

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

zoi check

Checks for essential third-party command-line tools like git.

zoi clean

Clears the cache of downloaded package binaries.

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

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.

zoi list

(alias: ls)

Lists installed or all available packages.

Options:

  • -a, --all: List all packages from the database, not just installed ones.
  • --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 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 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:

  • --repo <REPO>: Filter by repository.
  • --type <TYPE>: Filter by package type.
  • -t, --tag <TAGS>: Filter by tags (comma-separated).

zoi shell <shell>

Installs completion scripts for a given shell and setup PATH for Zoi.

Arguments:

  • <shell>: The shell to install completions for (bash, zsh, fish, elvish, powershell).

Options:

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

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

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.

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.

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.

zoi version

(alias: v)

Prints concise version and build information.

zoi why <package_name>

Explains why a package is installed.

Arguments:

  • <package_name>: The name of the package to inspect.

zoi doctor

Checks for common issues and provides actionable suggestions.

Last updated on

Zoi

Universal Package Manager & Environment Setup Tool.

Comparisons

How Zoi compares to other popular package managers like Pacman, APT, and Nix.

On this page

Core Features
Advanced Capabilities
Command Reference
Global Options
zoi about
zoi autoremove
zoi check
zoi clean
zoi create <source> [app_name]
zoi env [env_alias]
zoi exec <SOURCE> [ARGS]...
zoi extension
zoi files <package>
zoi helper
zoi info
zoi install [SOURCES]...
zoi list
zoi man <package_name>
zoi owner <path>
zoi package
zoi pgp
zoi pin <package> <version>
zoi repo
zoi rollback [PACKAGE]
zoi run [cmd_alias] [args]...
zoi search <search_term>
zoi shell <shell>
zoi show <package_name>
zoi sync
zoi telemetry <action>
zoi uninstall <PACKAGES>...
zoi unpin <package>
zoi update [PACKAGES]...
zoi upgrade
zoi version
zoi why <package_name>
zoi doctor