Zoi

This guide will provide you with everything you need to know to get started, from installation to advanced usage.

Nel Package Registry

Zoi provides an online package registry, the Nel Registry, to help you discover and search for packages. It provides a user-friendly web interface to browse all the packages available in the official Zoi repositories.

Repository

Introduction

Zoi is a universal package manager and environment setup tool, designed to simplify package management and environment configuration across multiple operating systems. It's part of the Zillowe Development Suite (ZDS) and aims to streamline your development workflow by managing tools and project environments with ease.

Features

• Cross-Platform: Works seamlessly on Linux, macOS, and Windows.
• Dynamic Package Definitions: Define packages with dynamic Lua scripts (.pkg.lua) for maximum flexibility.
• Universal Package Support: Install from binaries, compressed archives, source, or installer scripts.
• Extensive Dependency Management: Integrates with over 40 package managers (apt, brew, cargo, npm, pip, etc.).
• Rich Dependencies: Define runtime and build dependencies with required, optional, and selectable options.
• Project Environments: Manage project-specific commands and environments with zoi.yaml.
• Repository-Based: Use official, community, or your own private/public Git-based repositories.
• Secure & Verifiable: Verifies package integrity and authenticity with checksums and GPG signatures. Manage keys with zoi pgp.
• Versatile Package Types: Supports standard packages, collections, services, configs, app templates, extensions, libraries, and inline scripts.
• Local Package Development: A dedicated zoi package command set (meta, build, install) to streamline creating and testing packages locally.
• Advanced CLI Tools:
  • zoi man: Read package manuals in the terminal.
  • zoi why: Understand why a package is installed.
  • zoi rollback: Revert a package to its previous version.
  • zoi pin: Pin a package to a specific version.
  • zoi exec: Run a package without installing it.
• Library Support: Use as a Rust library and get compiler/linker flags via zoi pkg-config.

Getting Started

Getting started with Zoi is simple. Just follow these three steps:

1. Install Zoi: Choose one of the installation methods below.

2. Sync Repositories: Before you can install packages, you need to sync the package repositories.

   zoi sync

3. Install a Package: Now you can install any package you want. For example, to install hello:

   zoi install hello

Installation

You can install Zoi using a package manager, an installer script, or by building it from source.

Package Managers

Arch Linux (AUR)

Install zoi-bin (Pre-compiled binary) or zoi (built from source) from the AUR:

yay -S zoi-bin

macOS (Homebrew)

brew install Zillowe/tap/zoi

Windows (Scoop)

scoop bucket add zillowe https://github.com/Zillowe/scoop.git
scoop install zoi

From Crates.io

You can install zoi directly from crates.io using cargo

cargo install zoi-rs

From NPM

You can install @zillowe/zoi from npm also.

npx @zillowe/zoi

bunx @zillowe/zoi

pnpm dlx @zillowe/zoi

yarn dlx @zillowe/zoi

Scripts

Linux / macOS:

curl -fsSL https://zillowe.pages.dev/scripts/zoi/install.sh | bash

Windows:

powershell -c "irm zillowe.pages.dev/scripts/zoi/install.ps1|iex"

Build from Source

You'll need Rust installed.

# Build the release binary
# For Linux/macOS
./build/build-release.sh
# For Windows
./build/build-release.ps1

# Install it locally
./configure
make
sudo make install
# Install CLI completions (bash, zsh, fish, elvish, powershell)
make install-completion

Platforms

What platforms we currently support.

We're planning to add support for more platforms.

Usage & Commands

Zoi provides a wide range of commands to manage your packages and environment. For a full list of commands and their options, you can always run zoi --help.

General Commands

Package Management

Project Environment

See the full schema and examples in Project Configuration (zoi.yaml).

Service Management

Package Development

Sync Management (sync)

Manages the package database registry URL.

Repository Management (repo)

Manages the list of package repositories that Zoi uses.

Example:

# Add a repository interactively
zoi repo add

# Add a repository by name
zoi repo add community

# Add a repository by git URL (auto-clone)
zoi repo add https://example.com/my-zoi-repo.git

# Remove a repository
zoi repo rm community

# List active repositories
zoi repo ls

For an overview of official repositories, mirrors, and repository tiers, see Repositories.

Zoi supports different types of packages, defined in the .pkg.lua file.

Creating Packages (.pkg.lua)

Packages for Zoi are defined using .pkg.lua files. These are Lua scripts that define package metadata and installation logic, allowing for highly dynamic and flexible package definitions.

• Dynamic & Flexible: Use Lua scripting to define dynamic URLs, platform-specific logic, and complex installation steps.
• Comprehensive Examples: For a deep dive into creating packages, see the Creating Packages guide and the Package Examples.

.pkg.lua Structure

A .pkg.lua file is a Lua script that calls global functions like package{}, install{}, and dependencies{} to define the package.

-- my-cli.pkg.lua
package({
  name = "my-cli",
  repo = "community",
  version = "1.2.3",
  description = "A simple command-line utility.",
  -- ... more metadata
})

install({
  {
    type = "binary",
    url = "https://example.com/my-cli-v" .. PKG.version .. "-" .. SYSTEM.OS .. "-" .. SYSTEM.ARCH,
    platforms = { "all" },
  }
})

This approach allows you to use Lua's full power to construct your package definition. You have access to global variables like PKG (the package table) and SYSTEM (with OS, ARCH, DISTRO).

Installation Methods

Zoi supports four types of installation methods within the installation list:

1. binary: Downloads a pre-compiled binary directly from a URL.
2. com_binary: Downloads a compressed archive (.zip, .tar.gz, etc.), extracts it, and finds the binary within. Supports bin_path to point to the executable inside the archive and a files field to copy additional files (e.g. manuals, licenses). On Windows targets, if bin_path lacks .exe, Zoi will also try with .exe appended.
3. source: Clones a git repository and runs your defined build_commands. Zoi then moves the final executable to the installation directory. By default, Zoi looks for an executable with the same name as the package. If the executable has a different name or is in a subdirectory, you must specify its location with the bin_path field. Also supports a files field to copy additional files from the build directory. Supports optional tag or branch (use only one). If none is provided, the default branch HEAD is used. For reproducible builds, you can specify a docker_image to run the build inside a container.
4. script: Downloads and executes an installation script (e.g. install.sh).

For the list of supported archive formats for com_binary, see Supported Archives for Compressed Binaries.

Dependencies

For the full list of supported dependency managers, usage semantics, and commands Zoi runs, see Dependencies & Supported Package Managers.

FAQ

Examples

• Install a package:

  zoi install <package_name>

• Install multiple packages:

  zoi install <package_1> <package_2>

• Update a package:

  zoi update <package_name>

• Update multiple packages:

  zoi update <package_1> <package_2>

• Update all packages:

  zoi update all

• Uninstall a package:

  zoi uninstall <package_name>

• Uninstall multiple packages:

  zoi uninstall <package_1> <package_2>

• Install from a specific repository:

  # Install from a top-level repository
  zoi install @community/htop
  
  # Install from a nested repository
  zoi install @core/linux/amd64/nvidia-driver

• List all available packages from active repos:

  zoi list --all

• Search for a package:

  zoi search <term>

• Search by tag directly:

  # The term matches tags too
  zoi search editor
  
  # Require specific tag(s)
  zoi search editor -t cli,devtools
  zoi search editor -t cli -t devtools

• Check why a package is installed:

  zoi why <package_name>

• Create an app from a template:

  zoi create <source> <appName>
  # e.g.
  zoi create rails-app MyBlog
  zoi create @community/rails-app MyBlog

  # The term matches tags too
  zoi search editor
  
  # Require specific tag(s)
  zoi search editor -t cli,devtools
  zoi search editor -t cli -t devtools

• Check why a package is installed:

  zoi why <package_name>

• Create an app from a template:

  zoi create <source> <appName>
  # e.g.
  zoi create rails-app MyBlog
  zoi create @community/rails-app MyBlog