Project Configuration

Zoi v1.20+ (Specification v2) uses a split configuration model to separate environment definitions from task automation.

• zoi.lua: The primary, scriptable configuration for defining project metadata, package dependencies, and registries.
• zoi.yaml: A restricted configuration file dedicated to task automation (run and env).

1. Project Configuration (zoi.lua)

The zoi.lua file is the heart of your project. It uses Zoi's Lua API to define the environment in a programmable way.

Schema

-- zoi.lua

-- Define project metadata
project({
    name = "my-awesome-project",
    -- Enable project-local isolation (default: true in Spec v2 if file exists)
    config = {
        ["local"] = true
    }
})

-- Define supplementary registries
registries({
custom = {
url = "<https://github.com/YourOrg/custom-registry.git>",
revision = "main" -- Can be a branch, tag, or commit hash
}
})

-- Define package dependencies
packages({
-- Simple list
"@core/eza",
"@community/bat",

    -- Advanced pinning and options
    ["@community/fzf"] = {
        version = "0.44.1",
        sub_packages = {"cli"},
        dependencies = {
            runtime = {"zoi:ncurses"}
        }
    }
})

-- Define named tasks (runnable via `zoi run <cmd>`)
tasks({
    {
        cmd = "test",
        run = "cargo test",
        depends_on = {"build"},
        cache_files = {"src/**", "Cargo.toml"},
    },
    {
        cmd = "build",
        run = "cargo build --release",
    },
})

-- Define environment setups (runnable via `zoi env <alias>`)
environments({
    {
        name = "Prepare Workspace",
        cmd = "prep",
        run = {
            "zoi run build",
            "cargo clippy",
        },
        env = {
            RUST_BACKTRACE = "1",
        },
    },
})

Field Reference

• project:
  • name: (string) Required project name.
  • config.local: (boolean) If true, dependencies and registries are stored in the project root (./.zoi/pkgs).
• registries: A map of handles to registry definitions (url, revision, type).
  • type: (string) "set" (default), bare package names search this registry's repos; "added", requires explicit #handle prefix.
• packages: A map or list of @repo/package identifiers.
  • version: (string) SemVer requirement, supports ranges (^1.0, >=2.0, ~1.2.3) and channels (@nightly).
  • sub_packages: (list of string) Specific sub-packages to install.
  • dependencies: (object) Overrides for package dependencies.
• tasks: An array of CommandSpec objects (same schema as commands in zoi.yaml).
  • cmd: (string) Task alias for zoi run <cmd>.
  • run: (string or platform map) Command to execute.
  • depends_on: (list of string) Task aliases that must run first.
  • cache_files: (list of string) Glob patterns for cache invalidation.
  • env: (object or platform map) Environment variables for the task.
• environments: An array of EnvironmentSpec objects (same schema as environments in zoi.yaml).
  • name: (string) Display name.
  • cmd: (string) Alias for zoi env <cmd>.
  • run: (list of string or platform map) Commands to execute.
  • env: (object or platform map) Environment variables.

2. Task Configuration (zoi.yaml)

The zoi.yaml file is used to define named tasks and environments. It no longer supports package or registry definitions.

Schema

# zoi.yaml

# Short, named commands runnable via `zoi run <cmd>`
commands:
  - cmd: test
    run: cargo test
    depends_on: ["build"]

  - cmd: build
    run: cargo build --release
    cache_files: ["src/**", "Cargo.toml"]

# Full environment setups runnable via `zoi env <alias>`
environments:
  - name: Prepare Workspace
    cmd: prep
    run:
      - zoi run build
      - cargo clippy
    env:
      RUST_BACKTRACE: "1"

The zoi.lock File (Spec v2)

Zoi Specification v2 lockfiles are designed for absolute reproducibility. They pin not only package versions but also the exact Git revisions of your registries and the cryptographic hashes of your local state.

Lockfile Structure

{
  "version": "2",
  "packages_hash": "sha512-...", // Hash of all package files
  "registries_hash": "sha512-...", // Hash of the local database
  "registries": {
    "zoidberg": {
      "url": "https://github.com/zillowe/zoidberg.git",
      "revision": "a1b2c3d4..." // Exact commit hash
    }
  },
  "installed_packages": {
    "@core/curl": {
      "version": "8.4.0",
      "hash": "sha512-...",
      "platform": "linux-amd64",
      "why": "direct"
    }
  }
}

CLI Usage

• Enter a dev shell: zoi dev. If the repository is remote, use zoi dev --repo <url>.
• Run a task: zoi run <alias>.
• Set up environment: zoi env <alias>.
• Sync local registries: zoi sync --local (pins revisions from zoi.lua).
• Sync from lockfile: zoi sync --local --frozen (pins revisions from zoi.lock).
• Install project dependencies: zoi install --local.

Best Practices

1. Commit your lockfile: Always commit zoi.lock to ensure your team uses the exact same environment.
2. Use @repo/package: Always use scoped identifiers in zoi.lua to avoid ambiguity.
3. Pin Registry Revisions: For production projects, pin your registries in zoi.lua to a specific commit hash for maximum security.