Project Configuration

A Zoi project is defined by a single scriptable zoi.lua file covering project metadata, package dependencies, registries, task automation, environment setups, shell configuration, and package checks.

1. Project Configuration (zoi.lua)Copy Anchor Link

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

SchemaCopy Anchor Link

-- 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"},
        -- Pre-select dependency choices (non-interactive)
        options = {"zoi:@main/fzf-shell-integration"},
        -- Automatically enable specific optional dependencies
        optionals = {"zoi:@main/fzf-tmux"},
        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",
        },
    },
})

-- Ephemeral shell environment variables (merged by `zoi dev`)
shell({
    env = {
        RUST_BACKTRACE = "1",
    },
})

-- Declarative system checks (verified by `zoi env`)
checks({
    { name = "Git", check = "git --version" },
})

Field ReferenceCopy Anchor Link

• 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.
  • options: (list of string) List of dependencies to select for interactive choices (e.g. zoi:@core/sudo).
  • optionals: (list of string) List of optional dependencies to enable.
  • dependencies: (object) Overrides for package dependencies.
• tasks: An array of task objects (runnable via zoi run <cmd>).
  • cmd: (string) Task alias.
  • 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 environment setup objects (runnable via zoi env <alias>).
  • 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.
• shell: Ephemeral shell configuration merged by zoi dev.
  • env: (object or platform map) Environment variables for the dev shell.
• checks: An array of declarative system checks verified by zoi env.
  • name: (string) Display name (e.g. "Git").
  • check: (string) Command that must exit successfully (e.g. "git --version").

The zoi.lock File (Spec v2)Copy Anchor Link

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 StructureCopy Anchor Link

{
  "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 UsageCopy Anchor Link

• 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 PracticesCopy Anchor Link

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.