Quick Start

This guide gets you from a fresh machine to a working Zoi setup. It covers the normal user path first, then the project and package-author paths.

1. Install Zoi

Choose the installer for your platform.

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"

2. Set Up Your Shell

Zoi links package binaries into ~/.zoi/pkgs/bin. If commands installed by Zoi are not found, configure your shell:

zoi shell zsh

Use your shell name: bash, zsh, fish, elvish, or powershell.

3. Sync the Package Registry

Zoi uses Git-backed package registries. Sync once before installing packages:

zoi sync

This downloads package definitions from Zoidberg, builds the local package index, and imports registry metadata.

4. Find and Install a Package

Search:

zoi search hello

Show package details:

zoi show @zillowe/hello

Install:

zoi install @zillowe/hello

Run the installed command:

hello

5. Use Zoi Without Installing a Package

For one-off commands, use zoi exec:

zoi exec @zillowe/hello

This is useful for trying a tool before adding it to your installed package set.

6. Update Safely

Preview updates first:

zoi update --all --dry-run

Apply updates:

zoi update --all

If an update causes problems, roll back:

zoi rollback <package>

For a failed or interrupted transaction:

zoi rollback --last-transaction

7. Create a Project Environment

Create zoi.yaml in your project root:

name: my-project
config:
  local: true
pkgs:
  - eza
  - fzf
commands:
  - cmd: build
    run: make build
  - cmd: test
    run: make test
shell:
  env:
    default:
      DEBUG: "true"

Install project-local packages:

zoi install --local

Enter the development shell:

zoi dev

Run project commands:

zoi run build
zoi run test

Commit both zoi.yaml and zoi.lock so other machines can reproduce the same environment.

For strict reproducibility in CI:

zoi install --local --frozen-lockfile --yes

8. Install From a Specific Source

Zoi source strings let you choose where a package comes from.

For more source formats, see Repositories & Registries.

9. Understand What Zoi Installs

Zoi has two kinds of dependencies:

• Zoi packages: Packages installed into Zoi's own versioned store.
• External dependencies: Dependencies installed through native or language package managers such as apt, brew, scoop, cargo, npm, pip, or go.

Use native:<name> in package definitions when the host operating system should choose the correct native package manager.

For the full dependency format, see Dependencies & Supported Package Managers.

10. Create Your First Package

A minimal .pkg.lua package looks like this:

metadata({
  name = "my-cli",
  repo = "community",
  version = "1.0.0",
  description = "My command line tool",
  maintainer = { name = "Your Name", email = "[email protected]" },
  license = "MIT",
  bins = { "my-cli" },
  types = { "pre-compiled" }
})

function prepare()
  UTILS.EXTRACT("https://example.com/my-cli-1.0.0-linux-amd64.tar.gz", "src")
end

function package()
  zcp("src/my-cli", "${pkgstore}/bin/my-cli")
end

function test()
  local _, _, code = cmd(STAGING_DIR .. "/data/pkgstore/bin/my-cli --version")
  return code == 0
end

Validate it:

zoi package doctor ./my-cli.pkg.lua

Test it:

zoi package test ./my-cli.pkg.lua

Build it:

zoi package build ./my-cli.pkg.lua --test

For the complete packaging guide, see Creating Packages.

11. Troubleshooting

Run:

zoi doctor

Common fixes:

Next Steps

• Read Features & Usage for the full command reference.
• Read Project Configuration for zoi.yaml.
• Read Creating Packages to write packages.
• Read Comparisons to understand when Zoi is the right tool.