### Zoi Package Installation with Additional Files (Lua)

Source: https://zillowe.qzz.io/docs/zds/zoi/creating-packages

This example illustrates how to specify additional files or directories to be copied during the installation of a Zoi package, particularly for 'source' or 'com_binary' installation types. It defines a 'files' field within an installation method to manage file transfers.

```lua
install {
  type = "source",
  source = "https://example.com/my_package-1.0.0.tar.gz",
  files = {
    {
      platforms = {"linux"},
      files = {
        { source = "docs/README.md", destination = "~/share/my_package/" },
        { source = "completions/bash/my_package", destination = "~/share/bash_completion/" },
      }
    }
  }
}
```

--------------------------------

### Specify Package for Direct Git Installation (zoi.yaml)

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

Example 'zoi.yaml' file placed in the root of a Git repository. This file instructs Zoi which package to install directly from that repository when using 'zoi install --repo'.

```yaml
package: "@my-repo/my-package"
```

--------------------------------

### Zoi zoi.yaml Schema Example

Source: https://zillowe.qzz.io/docs/zds/zoi/project-config

An example demonstrating the structure of a `zoi.yaml` file, including package checks, platform-specific commands with environment variables, and environments with command lists.

```yaml
name: "my-project"
packages:
  - name: "node"
    check: "node --version"
commands:
  - cmd: "build"
    run: "echo 'Building...'"
  - cmd: "test"
    run:
      default: "npm test"
      "linux-amd64": "npm test -- --coverage"
      "macos-arm64": "npm test -- --ci"
    env:
      global_var: "global_value"
      platform: "linux-amd64"
        platform_var: "linux_value"
environments:
  - name: "setup"
    cmd: "setup"
    run:
      - "npm install"
      - "echo 'Setup complete'"
    env:
      NODE_ENV: "development"
```

--------------------------------

### Zoi CLI Usage Examples

Source: https://zillowe.qzz.io/docs/zds/zoi/project-config

Illustrates common command-line interface commands for Zoi, such as running a command by alias, passing arguments, and setting up environments.

```bash
# Run a command by alias
zoi build

# Pass arguments to the underlying script
zoi test -- --filter=user

# Interactively choose a command
zoi

# Set up an environment by alias
zoi setup

# Interactively choose an environment
zoi env
```

--------------------------------

### Install Package Directly from Git Repository

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

Command to install a package directly from a Git repository. Zoi reads the 'zoi.yaml' file in the repository to determine which package to install.

```bash
zoi install --repo git@github.com:user/my-repo.git
```

--------------------------------

### Install Package from Specific Git Repository

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Installs a package directly from a remote Git repository using the `--repo` flag with `zoi install`. This method does not require permanently adding the repository to the local configuration and supports various provider prefixes like `gh:`, `gitlab:`, and `cb:`.

```shell
zoi install --repo <provider-prefix><repository-name>/<package-name>
```

--------------------------------

### Define Zoi Package with Lua

Source: https://zillowe.qzz.io/docs/zds/zoi/creating-packages

This snippet demonstrates the basic structure of a Zoi package definition file (.pkg.lua) using Lua. It shows how to define a package, specify installation methods, and declare dependencies. This file is the core of any Zoi package.

```lua
package {
  name = "my_package",
  version = "1.0.0",
  maintainer = "Your Name <your.email@example.com>",
  description = "A brief description of your package."
}

install {
  type = "binary",
  url = "https://example.com/my_package-1.0.0.tar.gz",
  checksum = "sha256:abcdef123456..."
}

dependencies {
  "dependency1 >= 1.0",
  "dependency2 < 2.0"
}
```

--------------------------------

### Install Package from Custom Git Repository with Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Installs a package from a custom Git repository by prefixing the repository name with `@git/`. This allows specifying packages from user-defined or non-official Git sources.

```shell
zoi install @git/<repository-name>/<package-name>
```

--------------------------------

### Manage Dotfiles Configuration Package - Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/guides/omamix

This Zoi config package is designed to manage personal configuration files (dotfiles). It defines installation steps to clone a dotfiles repository and create symlinks, and includes uninstall commands for cleanup. It depends on tools like starship and neovim, which are expected to be installed separately.

```lua
return {
  "type: config",

  dependencies = {
    runtime = {
      required = {
        "@user/starship/starship",
        "@user/nvim/neovim"
      }
    }
  },

  config = {
    install = {
      -- Clone your dotfiles repository
      "git clone https://github.com/your-username/dotfiles.git $HOME/.dotfiles",
      -- Create symlinks for your configuration files
      "ln -s $HOME/.dotfiles/bashrc $HOME/.bashrc",
      "ln -s $HOME/.dotfiles/vimrc $HOME/.vimrc",
      "ln -s $HOME/.dotfiles/config/nvim $HOME/.config/nvim"
    },
    uninstall = {
      -- Remove symlinks
      "rm $HOME/.bashrc",
      "rm $HOME/.vimrc",
      "rm -rf $HOME/.config/nvim",
      -- Remove the cloned dotfiles repository
      "rm -rf $HOME/.dotfiles"
    }
  }
}
```

--------------------------------

### Zoi Package with Advanced Features (Lua)

Source: https://zillowe.qzz.io/docs/zds/zoi/creating-packages

This Lua snippet showcases advanced features available within the Zoi package definition. It includes an example of an 'alt' redirect, forces a specific update method using 'updater', disables rollback backups, and defines 'updates' messages for users.

```lua
package {
  name = "advanced_package",
  version = "1.1.0",
  alt = "https://example.com/another_package",
  updater = "source",
  rollback = false,
  updates = {
    { version = "1.1.0", message = "This release includes important security fixes." },
    { version = "1.0.0", message = "Breaking changes in this version. Please review the changelog." }
  }
}

install {
  type = "binary",
  url = "https://example.com/advanced_package-1.1.0.tar.gz",
  checksum = "sha256:fedcba654321..."
}
```

--------------------------------

### Adding a Git Repository as a Zoi Package Source

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

This command adds a remote Git repository as a local Zoi package source. Zoi will clone the specified repository into `~/.zoi/pkgs/git/`, making its packages available for installation. Use either the HTTPS or SSH URL of your Git repository.

```bash
# Example using HTTPS URL
zoi repo add https://gitlab.com/your-username/your-repo.git

# Example using SSH URL
zoi repo add git@github.com:your-username/your-repo.git
```

--------------------------------

### Link Dotfiles Config to Collection - Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/guides/omamix

This code snippet shows how to update a Zoi collection package (`dev-environment.pkg.lua`) to include a configuration package (`my-dotfiles.pkg.lua`) as a dependency. This ensures that the dotfiles configuration is installed automatically when the collection is installed.

```lua
return {
  "type: collection",

  dependencies = {
    runtime = {
      required = {
        "native:git",
        "@user/nvim/neovim",
        "@user/nvim/astronvim",
        -- Link your dotfiles config package
        "@user/personal/my-dotfiles"
      }
    }
  },

  options = {
    "browser = {
      description = "Select a web browser to install",
      choices = {
        "firefox",
        "chrome",
        "brave"
      },
      default = "firefox"
    }"
  },

  optional = {
    "ghostty"
  }
}
```

--------------------------------

### Install Package from Nested Git Repository Path with Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Installs a package from a specific path within a Git repository, potentially including platform-specific subdirectories. This is useful for complex repository structures or specialized package distributions.

```shell
zoi install @git/<repository-name>/<nested-path>/<package-name>
```

--------------------------------

### Define Development Environment Collection - Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/guides/omamix

This Zoi collection package defines the core software dependencies for a development environment. It includes required runtime packages like git and optional/conditional packages for editors, browsers, and other tools, allowing for a customizable setup.

```lua
return {
  "type: collection",

  dependencies = {
    runtime = {
      required = {
        -- Zoi will use the best way to install git on any OS
        "native:git", 
        -- Install neovim and astronvim from Zoi repositories
        "@user/nvim/neovim",
        "@user/nvim/astronvim"
      }
    }
  },

  options = {
    -- This block lets you choose which browser to install.
    -- Zoi will use the correct package manager for your OS.
    "browser = {
      description = "Select a web browser to install",
      choices = {
        "firefox",
        "chrome",
        "brave"
      },
      default = "firefox"
    }"
  },

  optional = {
    -- These packages are for tools you don't always need.
    -- Zoi will prompt you to ask if you want to install them.
    "ghostty"
  }
}
```

--------------------------------

### Zoi Extension: Add Git Repository Source

Source: https://zillowe.qzz.io/docs/zds/zoi/extensions

Defines a Zoi extension that adds a Git repository to Zoi's local package sources. This allows users to install packages from custom or third-party repositories. On removal, the cloned repository is deleted.

```lua
package {
  type = "extension",
  extension = {
    changes = {
      repo-git {
        add = "https://github.com/user/my-zoi-repo.git"
      }
    }
  }
}
```

--------------------------------

### Zoi Extension: Create Project Starter zoi.yaml

Source: https://zillowe.qzz.io/docs/zds/zoi/extensions

Defines a Zoi extension that creates a `zoi.yaml` file in the current directory, serving as a project starter. The `add` value contains the raw content of the `zoi.yaml` file. The command fails if `zoi.yaml` already exists. On removal, the `zoi.yaml` file is deleted.

```lua
package {
  type = "extension",
  extension = {
    changes = {
      project {
        add = "name: my-rust-project\nversion: 0.1.0\npackages: { rust: "1.75" }"
      }
    }
  }
}
```

--------------------------------

### Building Pre-Built Zoi Packages

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

These commands outline the workflow for creating pre-built Zoi package archives. First, generate metadata from your package definition file using `zoi package meta`. Then, build the distributable `.pkg.tar.zst` archive using `zoi package build`, which downloads or builds assets for the current platform.

```bash
# Generate metadata
zoi package meta ./my-package.pkg.lua

# Build the archive
zoi package build ./
```

--------------------------------

### Create a Zoi Extension to Set Registry (extension.pkg.lua)

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

Lua code for a Zoi extension package that automatically configures the Zoi client to use a specific registry. This provides a user-friendly way to manage registry switching.

```lua
local registry = "@git/my-repo-name my-registry-name"

function zoi.onLoad()
  zoi.sync.set(registry)
end
```

--------------------------------

### Configure Zoi to Use a Custom Registry (zoi sync set)

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

Command to configure the Zoi client to use a custom Git repository as its package registry. This updates Zoi's configuration, and subsequent 'zoi sync' commands will pull from the specified repository.

```bash
zoi sync set @git/my-repo-name my-registry-name
```

--------------------------------

### List Cloned Git Repositories for Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Shows a list of Git repositories that have been cloned locally under the `~/.zoi/pkgs/git` directory. This is useful for managing local copies of package sources.

```shell
zoi repo git ls
```

--------------------------------

### Zoi CLI: Add Extension Command

Source: https://zillowe.qzz.io/docs/zds/zoi/extensions

Demonstrates the command-line usage for adding a Zoi extension. This command resolves the package definition, verifies it's an extension, applies its configuration changes, and records a manifest.

```bash
zoi extension add <extension-name>
```

--------------------------------

### Zoi Library API - Core Functions

Source: https://zillowe.qzz.io/docs/zds/zoi/lib

Documentation for the core package management functions provided by the Zoi library.

```APIDOC
## `install` function

### Description

This function handles the entire installation process for a given package.

### Method

(Assumed: POST, as it creates a resource)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

#### Path Parameters

- **source** (string) - Required - The identifier for the package to install. This can be a package name (e.g. `"hello"`), a path to a local `.pkg.lua` file, or a URL to a package definition.
- **mode** (InstallMode enum) - Required - An enum that specifies the preferred installation method.
- **force** (boolean) - Required - If `true`, Zoi will reinstall the package even if it is already present.
- **reason** (InstallReason enum) - Required - An enum indicating why the package is being installed. This is typically `Direct` for user-initiated installs.
- **non_interactive** (boolean) - Required - If `true`, Zoi will automatically answer "yes" to any confirmation prompts, making the installation non-interactive.

### Request Example

(Not provided)

### Response

(Not provided)

## `uninstall` function

### Description

Removes a package that was previously installed by Zoi.

### Method

(Assumed: DELETE, as it removes a resource)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `update` function

### Description

This function checks if a package has a new version available and updates it.

### Method

(Assumed: PUT or POST, as it updates or modifies state)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `upgrade` function

### Description

Upgrades the Zoi binary itself to the latest version available on GitLab.

### Method

(Assumed: POST, as it initiates an upgrade process)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `sync` function

### Description

Downloads or updates the package database from the remote repository.

### Method

(Assumed: POST, as it initiates a synchronization process)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `autoremove` function

### Description

Removes packages that were installed as dependencies but are no longer needed.

### Method

(Assumed: DELETE, as it removes resources)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)
```

--------------------------------

### List Active Zoi Repositories

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Displays the currently active Zoi repositories configured in the system. An alias 'ls' is available. Use 'zoi repo list all' to see all available repositories.

```shell
zoi repo list
```

```shell
zoi repo ls
```

```shell
zoi repo list all
```

--------------------------------

### Zoi Library API - Information & Querying Functions

Source: https://zillowe.qzz.io/docs/zds/zoi/lib

Functions for querying the state and availability of packages using the Zoi library.

```APIDOC
## `resolve_package` function

### Description

Finds a package and returns its metadata without installing it.

### Method

(Assumed: GET, as it retrieves information)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `is_package_installed` function

### Description

Checks if a package is installed in a given scope.

### Method

(Assumed: GET, as it retrieves information)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `get_installed_packages` function

### Description

Returns a list of all packages installed by Zoi.

### Method

(Assumed: GET, as it retrieves a list)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `get_all_available_packages` function

### Description

Returns a list of all packages available in the active repositories.

### Method

(Assumed: GET, as it retrieves a list)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)
```

--------------------------------

### Zoi Sync with Fallback to Mirrors

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Enables Zoi to automatically attempt syncing from mirrors defined in `mirrors-git` if the primary registry is unavailable. This enhances reliability, especially for critical operations like updates.

```shell
zoi sync --fallback
```

--------------------------------

### Zoi Library API - Pinning Functions

Source: https://zillowe.qzz.io/docs/zds/zoi/lib

This section details the functions related to managing pinned packages within the Zoi library.

```APIDOC
## `pin` function

### Description

Pins a package to a specific version, preventing it from being updated.

### Method

(Assumed: POST or PUT, as it modifies state)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `unpin` function

### Description

Unpins a package, allowing it to be updated again.

### Method

(Assumed: POST or PUT, as it modifies state)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)

## `get_pinned_packages` function

### Description

Returns a list of all currently pinned packages.

### Method

(Assumed: GET, as it retrieves information)

### Endpoint

(Library function, not a REST endpoint)

### Parameters

(Details not provided in the input text)

### Request Example

(Not provided)

### Response

(Not provided)
```

--------------------------------

### Display Current Zoi Registry URL

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Shows the currently configured URL for the Zoi package database registry. This command helps in verifying the active registry source.

```shell
zoi sync show
```

--------------------------------

### Commiting a New Package to Git

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

This command demonstrates how to commit a new package file to a Git repository. It's used when adding a new package definition to your fork of the Zoi package repository. Ensure you are in the correct directory within your cloned repository before executing.

```git
git add community/my-package/my-package.pkg.lua
git commit -m "feat(community): add my-package"
```

--------------------------------

### Define Zoi Package Registry Properties (repo.yaml)

Source: https://zillowe.qzz.io/docs/zds/zoi/publishing-packages

This snippet shows a minimal 'repo.yaml' file used to define properties for a custom Zoi package registry. It's placed in the root of the Git repository.

```yaml
name: "My Custom Registry"
version: "1.0.0"
description: "A custom registry for Zoi packages."
```

--------------------------------

### Add Official or Git Zoi Repository

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Manages active Zoi repositories. This command can add official repositories by name or custom Git repositories by URL. It's interactive if no arguments are provided.

```shell
zoi repo add
```

--------------------------------

### Set Zoi Package Database Registry URL

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Allows changing the URL of the Zoi package database registry. This is useful for using mirrors or custom package databases. Keywords like 'default', 'gitlab', 'github', and 'codeberg' can be used for predefined URLs.

```shell
zoi sync set <url-or-keyword>
```

--------------------------------

### Zoi Extension: Change Registry Repository URL

Source: https://zillowe.qzz.io/docs/zds/zoi/extensions

Defines a Zoi extension that modifies the URL of the main Zoi package database. This is useful for pointing Zoi to a corporate mirror or a personal fork. On removal, the registry URL reverts to the default.

```lua
package {
  type = "extension",
  extension = {
    changes = {
      registry-repo {
        add = "https://gitlab.com/my-corp/zoi-registry.git"
      }
    }
  }
}
```

--------------------------------

### Zoi Extension: Add Official Repository Tier

Source: https://zillowe.qzz.io/docs/zds/zoi/extensions

Defines a Zoi extension to add an official Zoi repository tier to the active list. This is useful for enabling repositories not active by default, like 'test'. On removal, the repository is removed from the active list.

```lua
package {
  type = "extension",
  extension = {
    changes = {
      repo-add {
        add = "test"
      }
    }
  }
}
```

--------------------------------

### Remove Cloned Git Repository Directory for Zoi

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Deletes a cloned Git repository directory from the `~/.zoi/pkgs/git` location. This helps in cleaning up local storage used by Zoi.

```shell
zoi repo git rm <repo>
```

--------------------------------

### Remove Zoi Repository

Source: https://zillowe.qzz.io/docs/zds/zoi/repositories

Removes a specified repository from the active Zoi repository list. This operation affects which repositories are searched during package operations.

```shell
zoi repo rm <name>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.