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.

Advanced Capabilities

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

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

  • Shell Integration:

    • zoi setup: Automatically configures your shell's PATH for Zoi.
    • zoi shell: Installs shell completion scripts for Bash, Zsh, Fish, and more.

  • 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 from a name, local file, URL, or git repository.

Arguments:

  • [SOURCES]...: Package names, 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).
    • --sign <KEY>: Sign the package with the given PGP key.
  • install <package_file>: Install a package from a local archive.
    • --scope <user|system>: The scope to install the package to (default: user).

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 setup

Configures the shell environment for Zoi.

Options:

  • --scope <user|system>: The scope to apply the setup to (default: user).

zoi shell <shell>

Installs completion scripts for a given shell.

Arguments:

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

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 previously installed by Zoi.

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.

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, skipping the patch-based upgrade.
  • --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.

Last updated on

Zoi

Universal Package Manager & Environment Setup Tool.

Comparisons

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