### Define a Script Package for Setup Commands

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Creates a 'script' package to execute inline shell commands for setup or complex actions. This example defines 'install' commands to create a configuration directory and file, and 'uninstall' commands to remove them. It is designed for Linux and macOS platforms.

```lua
-- my-setup-script.pkg.lua
package({
  name = "my-setup-script",
  repo = "community",
  type = "script",
  version = "1.0",
  description = "A package that runs a series of setup commands.",
  tags = { "script", "setup" },
  maintainer = {
    name = "Your Name",
    email = "your.email@example.com"
  },
  -- The 'script' field contains the commands to run.
  script = {
    {
      platforms = { "linux", "macos" },
      install = {
        "echo 'Creating configuration directory...'",
        "mkdir -p ~/.config/my-app",
        "echo 'hello: world' > ~/.config/my-app/config.yml"
      },
      uninstall = {
        "echo 'Removing configuration...'",
        "rm -rf ~/.config/my-app"
      }
    }
  }
})
```

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

### Configure, Build, and Install Zoi with Makefile

Source: https://github.com/zillowe/zoi/blob/main/PACKAGING.md

Demonstrates the use of the project's Makefile for building and installing Zoi. It first configures build paths, then builds the release binary, and finally installs it to the specified location using sudo.

```sh
# Configure build paths (creates config.mk)
./configure

# Build the zoi binary in release mode
make build

# Install the binary to the configured location
sudo make install
```

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

### Define a Service Package for a Database

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Configures a 'service' package for background applications, enabling Zoi to manage their lifecycle. This example defines a database service with platform-specific start and stop commands and specifies a binary installation from a URL.

```lua
-- services/my-database.pkg.lua
package({
  name = "my-database",
  repo = "community",
  type = "service", -- Set the package type to 'service'.
  version = "5.7",
  description = "A lightweight database server.",
  tags = { "service", "database" },
  maintainer = {
    name = "Your Name",
    email = "your.email@example.com"
  },
  -- The 'service' block defines how to manage the service.
  service = {
    {
      platforms = { "linux-amd64", "macos-amd64" },
      start = { "my-database --config /etc/my-database.conf" },
      stop = { "pkill my-database" }
    }
  }
})

install({
  {
    type = "binary",
    url = "https://example.com/my-database-v" .. PKG.version .. "-" .. SYSTEM.OS .. "-" .. SYSTEM.ARCH,
    platforms = { "linux-amd64", "macos-amd64" }
  }
})
```

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

### Install Package with Zoi Rust Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/examples.mdx

Demonstrates how to install a package using the Zoi Rust library with default settings. It automatically confirms prompts and specifies installation preferences. Dependencies include the `zoi` crate.

```rust
use zoi::{install, InstallMode, types::InstallReason};

fn main() {
    let package_source = "hello";

    println!("Attempting to install '{}'...", package_source);

    // Call the install function with default preferences.
    let result = zoi::install(
        package_source,
        InstallMode::PreferBinary, // Try to get a binary, fall back to source.
        false,                     // Don't force re-installation.
        InstallReason::Direct,     // This is a direct request from the user.
        true,                      // `non_interactive`: Automatically say "yes" to any prompts.
    );

    // Check the result and print a message.
    match result {
        Ok(()) => println!("'{}' was installed successfully!", package_source),
        Err(e) => eprintln!("Error installing '{}': {}", package_source, e),
    }
}
```

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

### Install a Package with Zoi CLI

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This command installs a specified package, such as 'hello', using the Zoi package manager. It downloads and sets up the package and its dependencies.

```shell
zoi install hello
```

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

### Build ZOI from Source

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Instructions for building the ZOI project from its source code. This process requires Rust to be installed. It involves running build scripts for release binaries and then using make commands for local installation and setup.

```sh
# For Linux/macOS
./scripts/build-release.sh
```

```powershell
# For Windows
./scripts/build-release.ps1
```

```sh
./configure
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup
```

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

### List Installed Packages with Zoi Rust Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/examples.mdx

Shows how to retrieve and display a list of all packages currently installed by the Zoi library in Rust. It handles cases where no packages are installed. Requires the `zoi` crate.

```rust
use zoi::get_installed_packages;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Fetching installed packages...");
    let installed_packages = get_installed_packages()?;

    if installed_packages.is_empty() {
        println!("No packages are installed.");
    } else {
        println!("Installed packages:");
        for pkg in installed_packages {
            println!(
                "- {} (Version: {}, Repo: {}, Scope: {:?})",
                pkg.name,
                pkg.version,
                pkg.repo,
                pkg.scope
            );
        }
    }
    Ok(())
}
```

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

### Build and install Zoi locally

Source: https://github.com/zillowe/zoi/blob/main/CONTRIBUTING.md

These commands are used for the initial setup of the Zoi development environment. They involve configuring the build, compiling the project, and installing the binary. 'make' and 'sudo' are required.

```sh
./configure
make build
sudo make install
# (optional) Install CLI completions and setup Zoi's PATH
make setup
```

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

### Comprehensive Zoi Package Definition (.pkg.lua)

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Defines a Zoi package named 'hello' with multiple installation options including pre-compiled binaries, compressed archives, an installer script, and building from source. It includes platform-specific configurations, checksums, and digital signatures. Dependencies like 'native:go' for building from source are also specified.

```lua
-- hello.pkg.lua

-- Using local variables to follow DRY principle.
local repo_owner = "Zillowe"
local repo_name = "Hello"
local version = "2.0.0"
local git_url = "https://github.com/" .. repo_owner .. "/" .. repo_name .. ".git"
local release_base_url = "https://github.com/" .. repo_owner .. "/" .. repo_name .. "/releases/download/v" .. version

-- Platform mapping allows customizing OS and architecture names for URLs and filenames.
-- The key is the platform string reported by Zoi (e.g. "macos", "linux-amd64").
-- The value is the desired platform string to be used in the package script.
local platform_map = {
	macos = "darwin",
}

local function get_mapped_platform()
	local current_platform = SYSTEM.OS .. "-" .. SYSTEM.ARCH
	return platform_map[current_platform] or platform_map[SYSTEM.OS] or current_platform
end

local function get_mapped_os()
	return get_mapped_platform():match("([^%-]+)")
end

package({
	name = "hello",
	repo = "zillowe",
	version = version,
	description = "Hello World",
	website = "https://github.com/Zillowe/Hello",
	git = git_url,
	maintainer = {
		name = "Your Name",
		email = "your-email@example.com",
	},
	author = {
		name = "Zillowe Foundation",
		website = "https://zillowe.qzz.io",
		email = "contact@zillowe.qzz.io",
		key = "https://zillowe.pages.dev/keys/zillowe-main.asc",
		key_name = "zillowe-main",
	},
	license = "Apache-2.0",
	bins = { "hello" },
	conflicts = { "hello" },
})

install({
	selectable = true,
	{
		name = "Binary",
		type = "binary",
		url = (function()
			return release_base_url .. "/hello-" .. get_mapped_os() .. "-" .. SYSTEM.ARCH
		end)(),
		platforms = { "all" },
		checksums = (function()
			return release_base_url .. "/checksums-512.txt"
		end)(),
		sigs = {
			{
				file = (function()
					return "hello-" .. get_mapped_os() .. "-" .. SYSTEM.ARCH
				end)(),
			sig = (function()
					return release_base_url .. "/hello-" .. get_mapped_os() .. "-" .. SYSTEM.ARCH .. ".sig"
			end)(),
		},
	},
	},
	{
		name = "Compressed Binary",
		type = "com_binary",
		url = (function()
			local ext
			if SYSTEM.OS == "windows" then
				ext = "zip"
			else
				ext = "tar.xz"
			end
			return release_base_url .. "/hello-" .. get_mapped_os() .. "-" .. SYSTEM.ARCH .. "." .. ext
		end)(),
		platforms = { "all" },
		checksums = (function()
			return release_base_url .. "/checksums-512.txt"
		end)(),
		sigs = {
			{
				file = (function()
					local ext
					if SYSTEM.OS == "windows" then
						ext = "zip"
					else
						ext = "tar.xz"
					end
					return "hello-" .. get_mapped_os() .. "-" .. SYSTEM.ARCH .. "." .. ext
				end)(),
			sig = (function()
					local ext
					if SYSTEM.OS == "windows" then
						ext = "zip"
					else
						ext = "tar.xz"
					end
					return release_base_url
								.. "/hello-"
								.. get_mapped_os()
								.. "-"
								.. SYSTEM.ARCH
								.. "."
								.. ext
								.. ".sig"
				end)(),
			},
		},
	},
	{
		name = "Install Script",
		type = "script",
		url = (function()
			local ext
			if SYSTEM.OS == "windows" then
				ext = "ps1"
			else
				ext = "sh"
			end
			return "https://raw.githubusercontent.com/Zillowe/Hello/refs/heads/main/app/install." .. ext
		end)(),
		platforms = { "all" },
	},
	{
		name = "Build from source",
		type = "source",
		url = git_url,
		platforms = { "linux", "macos", "windows" },
		build_commands = {
			'go build -o hello -ldflags="-s -w" ./src',
		},
		bin_path = (function() -- the final binary path
			local bin
			if SYSTEM.OS == "windows" then
				bin = "hello.exe"
			else
				bin = "./hello"
			end
			return bin
		end)(),
		files = {
			{
				platforms = { "linux", "macos" },
				files = {
					{
						source = "README.md",
						destination = "/usr/local/share/doc/hello/README.md",
					},
				},
			},
			{
				platforms = { "windows" },
				files = {
					{
						source = "README.md",
						destination = "C:\\ProgramData\\hello\\README.md",
					},
				},
			},
		},
	},
})

dependencies({
	build = {
		required = { "native:go" },
	},
})

```

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

### Define a Library Package with pkg-config Support

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Packages shared/static libraries and header files as a 'library' type. This example includes configuration for generating a `.pc` file, specifying library paths, include flags, and description for `pkg-config` integration. It installs a tarball containing the library binaries.

```lua
-- libs/my-library.pkg.lua
package({
  name = "my-library",
  repo = "community",
  type = "library",
  version = "1.2.0",
  description = "A library for doing awesome things.",
  tags = { "library", "c++" },
  maintainer = {
    name = "Your Name",
    email = "your.email@example.com"
  },
  -- This block is used to generate the .pc file
  pkg_config = {
    description = "My Awesome Library",
    libs = "-L/usr/local/lib -lmy-library",
    cflags = "-I/usr/local/include/my-library"
  }
})

install({
  {
    type = "com_binary",
    url = "https://example.com/my-library/v" .. PKG.version .. "-" .. SYSTEM.OS .. "-" .. SYSTEM.ARCH .. ".tar.gz",
    platforms = { "linux-amd64" }
  }
})
```

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

### Manually Install Zoi from AUR

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This sequence of commands manually clones the `zoi-bin` package from the AUR, navigates into the directory, and then builds and installs it using `makepkg`. This is an alternative to using AUR helpers.

```shell
git clone https://aur.archlinux.org/zoi-bin.git
cd zoi-bin
makepkg -si
```

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

### Build from Source Package with Go and Docker

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Installs a package from a source repository, compiling it on the user's machine. It supports specifying build commands, Docker images for reproducible builds, and platform compatibility. Dependencies include Go and Make for building, and OpenSSL for runtime.

```lua
-- dev/compiler.pkg.lua
package({
  name = "compiler",
  repo = "community",
  version = "0.1.0",
  description = "A new programming language compiler.",
  git = "https://github.com/user/compiler",
  tags = { "compiler", "devtools" },
  maintainer = {
    name = "Your Name",
    email = "your.email@example.com"
  }
})

install({
  {
    type = "source",
    url = PKG.git, -- URL to the git repository.
    platforms = { "linux-amd64", "macos-amd64", "windows-amd64" },
    -- Optional: build inside a Docker container for reproducibility.
    docker_image = "hub:golang:1.21-alpine",
    -- Commands to execute in the cloned repository to build.
    build_commands = {
      "go build -o compiler"
    },
    -- Path to the built binary, relative to the repo root.
    -- When using docker_image, this is the path inside the container.
    bin_path = "./compiler"
  }
})

dependencies({
  build = {
    required = { "zoi:go", "native:make" },
    optional = { "cargo:some-build-tool:additional build helper" }
  },
  runtime = {
    required = { "native:openssl" }
  }
})
```

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

### Define Zoi Package Metadata and Installation (.pkg.lua)

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This Lua script defines a Zoi package, including its metadata like name, version, and description, along with the installation instructions. It demonstrates how to dynamically construct download URLs using package and system variables.

```lua
-- 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" },
  }
})
```

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

### Zoi com_binary Installation Example (.pkg.lua)

Source: https://github.com/zillowe/zoi/blob/main/docs/archives.mdx

This snippet demonstrates how to configure the `com_binary` installation method in a Zoi package definition file (`.pkg.lua`). It specifies the download URL, supported platforms, and platform-specific archive extensions. Zoi will handle downloading, verifying, and extracting the archive, then locating the executable based on the package name or a provided `bin_path`.

```lua
install({
  {
    type = "com_binary",
    url = "https://example.com/app-v{version}-{platform}.{platformComExt}",
    platforms = {"linux-amd64", "macos-amd64", "windows-amd64"},
    platformComExt = {
      linux = "tar.zst", -- or tar.gz / tar.xz
      macos = "tar.zst", -- or tar.gz / tar.xz
      windows = "zip"
    }
  }
})
```

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

### Update Package with Zoi Rust Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/examples.mdx

Provides an example of checking for and applying updates to an installed package using the Zoi Rust library. It handles cases where the package is updated, already up-to-date, or pinned. Requires the `zoi` crate.

```rust
use zoi::{update, UpdateResult};

fn main() {
    let package_source = "hello";

    println!("Checking for updates for '{}'...", package_source);

    // Call the update function.
    match zoi::update(package_source, true) {
        Ok(result) => match result {
            UpdateResult::Updated { from, to } => {
                println!("Successfully updated '{}' from v{} to v{}", package_source, from, to);
            }
            UpdateResult::AlreadyUpToDate => {
                println!("'{}' is already up to date.", package_source);
            }
            UpdateResult::Pinned => {
                println!("'{}' is pinned and was not updated.", package_source);
            }
        },
        Err(e) => {
            // This can happen if the package is not installed,
            // or if the user cancels the update prompt.
            eprintln!("Error updating '{}': {}", package_source, e);
        }
    }
}
```

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

### Install Zoi from AUR using yay

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This command installs the pre-compiled Zoi binary from the Arch User Repository (AUR) using the `yay` helper. It's a common method for Arch Linux users.

```shell
yay -S zoi-bin
```

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

### Resolve Package Information with Zoi Rust Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/examples.mdx

Demonstrates how to resolve and display metadata for a specific package using the Zoi Rust library before installation. It handles successful resolution and errors. Requires the `zoi` crate.

```rust
use zoi::resolve_package;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let package_source = "git";
    println!("Resolving package info for '{}'...", package_source);

    match resolve_package(package_source) {
        Ok(pkg) => {
            println!("Successfully resolved package: {}", pkg.name);
            println!("  Description: {}", pkg.description);
            println!("  License: {}", pkg.license);
            println!("  Maintainer: {} <{}>", pkg.maintainer.name, pkg.maintainer.email);
        }
        Err(e) => eprintln!("Error resolving package: {}", e),
    }

    Ok(())
}
```

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

### Install a Package using Zoi Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

The `install` function programmatically installs a package. It takes the package source, installation mode, a force flag, the reason for installation, and a flag for non-interactive mode. It returns a Result indicating success or an error.

```rust
pub fn install(
    source: &str,
    mode: InstallMode,
    force: bool,
    reason: InstallReason,
    non_interactive: bool,
) -> Result<(), Box<dyn std::error::Error>>
```

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

### Package Management Commands with Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This section details various command-line operations for managing packages using the 'zoi' tool. It covers installing, updating, uninstalling, listing, searching, and checking package dependencies. These commands are essential for interacting with the Zoi package manager.

```sh
zoi install <package_name>
zoi install <package_1> <package_2>
zoi update <package_name>
zoi update <package_1> <package_2>
zoi update all
zoi uninstall <package_name>
zoi uninstall <package_1> <package_2>
zoi install @community/htop
zoi install @core/linux/amd64/nvidia-driver
zoi list --all
zoi search <term>
zoi search editor -t cli,devtools
zoi search editor -t cli -t devtools
zoi why <package_name>
```

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

### Sync Repositories with Zoi CLI

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

This command synchronizes the Zoi package repositories. It is a prerequisite for installing packages and ensures that Zoi has the latest information about available packages.

```shell
zoi sync
```

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

### Backup and Restore Packages with Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Details the process of backing up and restoring installed packages using Zoi. Zoi maintains an SBOM file at `~/.zoi/pkgs/zoi.pkgs.json`, which can be backed up. Restoring on a new system involves running 'zoi install' with the path to this JSON file.

```sh
zoi install /path/to/your/zoi.pkgs.json
```

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

### Package Rollback with Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Explains how to revert a package to its previously installed version using the 'zoi rollback' command. Zoi automatically creates backups before upgrades, enabling seamless rollbacks if an update introduces issues.

```sh
zoi rollback <package-name>
```

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

### Core Functions - Install Package

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

Handles the entire installation process for a given package, allowing for various sources and installation modes.

```APIDOC
## `install` function

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

### Method

`pub fn install`

### Parameters

#### Path Parameters

* **source** (str) - 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) - Required - An enum that specifies the preferred installation method.
* **force** (bool) - Required - If `true`, Zoi will reinstall the package even if it is already present.
* **reason** (InstallReason) - Required - An enum indicating why the package is being installed. This is typically `Direct` for user-initiated installs.
* **non_interactive** (bool) - Required - If `true`, Zoi will automatically answer "yes" to any confirmation prompts, making the installation non-interactive.

### Response

#### Success Response

Returns `Ok(())` on successful installation.

#### Error Response

Returns `Err(Box<dyn std::error::Error>)` if any error occurs during installation.
```

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

### Get All Installed Packages in Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

Retrieves a list of all packages that have been installed by Zoi. The result is a vector of InstallManifest objects.

```rust
pub fn get_installed_packages() -> Result<Vec<InstallManifest>, Box<dyn Error>>
```

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

### Define a Package Collection for Web Development Tools

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

Creates a meta-package 'collection' that bundles several other packages as dependencies. This example specifies required runtime dependencies like Node.js, Bun, and Git, along with optional packages such as pnpm, serve, and TypeScript.

```lua
-- collections/web-dev-essentials.pkg.lua
package({
  name = "web-dev-essentials",
  repo = "community",
  type = "collection", -- Set the package type to 'collection'.
  version = "1.0",
  description = "A collection of essential tools for web development.",
  tags = { "collection", "web", "devtools" },
  maintainer = {
    name = "Community",
    email = "community@example.com"
  }
})

-- The 'runtime' dependencies are the packages that will be installed.
dependencies({
  runtime = {
    required = {
      "zoi:node",
      "zoi:bun",
      "native:git"
    },
    optional = {
      "npm:pnpm",
      "npm:serve",
      "npm:typescript"
    }
  }
})
```

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

### Testing Zoi Package Installation Locally (Shell)

Source: https://github.com/zillowe/zoi/blob/main/docs/creating-packages.mdx

Demonstrates how to install and uninstall a Zoi package locally using the `zoi` command-line tool. It covers installing from a local `.pkg.lua` file, specifically testing a source build, and testing the cleanup process with `zoi uninstall`.

```shell
# Install from your local .pkg.lua file
zoi install ./my-package.pkg.lua

# If testing a source build specifically
zoi build ./my-package.pkg.lua

zoi uninstall my-package
```

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

### Create Application from Template with Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Demonstrates how to create a new application using a template provided by Zoi. This involves specifying the template source and the desired application name. It supports both direct template names and scoped template names from repositories.

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

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

### Zoi CLI Environment Setup (Shell)

Source: https://github.com/zillowe/zoi/blob/main/docs/project-config.mdx

Illustrates how to set up defined environments using the Zoi CLI. Covers setting up an environment by alias, and interactively choosing an environment when no alias is provided.

```sh
# Set up an environment by alias:
zoi env web

# Interactively choose an environment:
zoi env

```

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

### Information & Querying - Resolve Package

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

Get package metadata without installing.

```APIDOC
## `resolve_package` function

Get package metadata without installing.

### Method

`pub fn resolve_package`

### Parameters

This function does not take any parameters.

### Response

#### Success Response

Returns package metadata.

#### Error Response

Returns an error if the package cannot be resolved.
```

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

### Define ZOI Rails App Template Package

Source: https://github.com/zillowe/zoi/blob/main/docs/examples.mdx

This Lua code defines a ZOI 'app' package for scaffolding a Rails application. It specifies the package metadata, platform compatibility, the command to create a new Rails app, and any necessary follow-up commands like bundle install. It also declares runtime dependencies.

```lua
-- apps/rails-app.pkg.lua
package({
  name = "rails-app",
  repo = "community",
  type = "app",
  version = "7",
  description = "Rails app template",
  tags = { "app", "rails", "ruby" },
  maintainer = {
    name = "Your Name",
    email = "you@example.com"
  },
  -- Platform-specific create command and optional follow-up commands
  app = {
    ({
      platforms = { "all" },
      appCreate = "rails new ${appName}",
      commands = {
        "cd ${appName} && bundle install",
        "cd ${appName} && git init"
      }
    })
  }
})

dependencies({
  runtime = {
    required = { "zoi:@core/ruby", "zoi:@main/gems/rails" }
  }
})
```

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

### Configure Zoi Package Installation Methods in Lua

Source: https://github.com/zillowe/zoi/blob/main/docs/creating-packages.mdx

This Lua script configures the installation methods for a Zoi package. It supports multiple methods like 'binary' and 'source', with options for dynamic URL construction, platform specificity, and building from source using Docker containers. The `selectable` option allows users to choose.

```lua
install({
  selectable = true, -- Allows the user to choose between these methods
  {
    name = "Binary", -- A descriptive name for the method
    type = "binary",
    url = "...",
    platforms = { "linux-amd64", "macos-amd64", "windows-amd64" }
  },
  {
    name = "Build from Source",
    type = "source",
    url = PKG.git, -- Use the git URL from the package definition
    platforms = { "all" },
    -- Optional: build inside a Docker container for reproducibility.
    -- Use "hub:" for Docker Hub and "ghcr:" for GitHub Container Registry.
    docker_image = "hub:golang:1.21",
    build_commands = { "make" },
    -- After building, Zoi will look for an executable with the same name as the package.
    -- If the binary has a different name or is in a subdirectory, specify its path.
    -- When using docker_image, this path is inside the container.
    bin_path = "build/my-cli"
  }
})
```

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

### Zoi Installation via NPM/Bun/PNPM/Yarn (Node.js)

Source: https://github.com/zillowe/zoi/blob/main/README.md

Commands to install and execute the @zillowe/zoi package using various Node.js package managers like npm, bun, pnpm, and yarn. These commands typically use `dlx` or `npx` to run the package without a global installation.

```sh
npx @zillowe/zoi
bunx @zillowe/zoi
pnpm dlx @zillowe/zoi
yarn dlx @zillowe/zoi
```

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

### Example repo.yaml Configuration for Zoi Package Registry

Source: https://github.com/zillowe/zoi/blob/main/docs/repositories.mdx

An example `repo.yaml` file demonstrating the configuration for a Zoi package registry. This file defines the repository's metadata, including its name, description, primary Git URL, optional mirrors for Git URLs, and URLs for pre-built packages with templated placeholders.

```yaml
name: Zoi repo
description: The official Zoi package repository.
repo-git: https://gitlab.com/Zillowe/Zillwen/Zusty/Zoiberg.git
mirrors-git:
  - https://github.com/Zillowe/Zoidberg.git
  - https://codeberg.org/Zillowe/Zoidberg.git
repo-pkg: https://zoi.zillowe.qzz.io/pkgs/{os}/{arch}/{version}/{package}
mirrors-pkg:
  - https://zoi.zilo.qzz.io/pkgs/{os}/{arch}/{version}/{package}
```

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

### Zoi Installation via Scoop (Windows)

Source: https://github.com/zillowe/zoi/blob/main/README.md

Commands to add the Zillowe scoop bucket and install the zoi package on Windows systems using the Scoop package manager.

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

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

### Install Zoi Custom Environment Collection

Source: https://github.com/zillowe/zoi/blob/main/docs/guides/omamix.mdx

This shell command installs a Zoi collection package from a custom repository. The `@git/` prefix indicates that the repository is located at a Git URL, and the subsequent path specifies the collection to install. This command triggers the installation of all dependencies and associated scripts defined in the collection.

```sh
# The repo name is derived from the URL (e.g. 'my-zoi-setup')
zoi install @git/my-zoi-setup/dev-environment
```

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

### Zoi Package Workflow: Meta, Build, Install (Shell)

Source: https://github.com/zillowe/zoi/blob/main/docs/creating-packages.mdx

Outlines the advanced `zoi package` command workflow for complex packages. It includes generating a static `*.meta.json` file from Lua scripts, building a Zoi package archive (`.pkg.tar.zst`) from the meta file for the current platform, and installing a package from a local archive.

```shell
# Generates a *.meta.json file.
zoi package meta <path/to/file.pkg.lua>

# Downloads assets, verifies, and bundles into a .pkg.tar.zst archive.
zoi package build <path/to/file.meta.json>

# Installs a package from a local Zoi package archive.
zoi package install <path/to/file.pkg.tar.zst>
```

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

### Zoi Installation Script for Windows

Source: https://github.com/zillowe/zoi/blob/main/README.md

PowerShell script to download and execute the zoi installer on Windows systems. It uses Invoke-RestMethod (irm) to fetch the script and Invoke-Expression (iex) to execute it.

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

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

### Add Custom Zoi Repository

Source: https://github.com/zillowe/zoi/blob/main/docs/guides/omamix.mdx

This shell command adds a custom Zoi package repository. Replace the provided URL with the actual URL of your Zoi setup repository. This step is necessary to allow Zoi to access and install packages from your custom repository.

```sh
# Replace with your repository's URL
zoi repo add https://github.com/YourUsername/my-zoi-setup.git
```

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

### Generate Shell Completions for Zoi

Source: https://github.com/zillowe/zoi/blob/main/PACKAGING.md

Generates shell completions for Zoi. The `shell` command sets them up for the user, while `generate-completions` prints them to standard output. Supports shells like bash, fish, and zsh.

```shell
./target/release/zoi shell <shell> # generates completions and set them up for the user
```

```shell
./target/release/zoi generate-completions <shell> # generates completions and prints them
```

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

### Create Rust Project Starter Extension

Source: https://github.com/zillowe/zoi/blob/main/docs/extensions.mdx

This Lua script defines a Zoi extension that acts as a project starter for new Rust projects. It automatically generates a `zoi.yaml` file with configurations for Rust and Cargo, including commands for running, testing, and watching the project.

```lua
-- my-rust-starter.pkg.lua
package({
  name = "my-rust-starter",
  repo = "community",
  type = "extension",
  version = "1.0",
  description = "A starter zoi.yaml for a Rust project.",
  maintainer = {
    name = "Your Name",
    email = "your.email@example.com"
  },
  extension = {
    type = "zoi",
    changes = {
      {
            type = "project",
        add = [[
name: my-rust-project
packages:
  - name: rust
    check: "rustc --version"
  - name: cargo-watch
    check: "cargo watch --version"
commands:
  - cmd: run
    run: cargo run
  - cmd: test
    run: cargo test
  - cmd: watch
    run: cargo watch -x run
]]
      }
    }
  }
})
```

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

### Zoi Installation via Homebrew (macOS/Linux)

Source: https://github.com/zillowe/zoi/blob/main/README.md

Command to install the zoi package on macOS and Linux systems using the Homebrew package manager. It adds the Zillowe tap and installs the zoi formula.

```sh
brew install Zillowe/tap/zoi
```

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

### Make Git Repository Directly Installable with `zoi.yaml`

Source: https://github.com/zillowe/zoi/blob/main/docs/publishing-packages.mdx

This YAML file, placed in the root of a Git repository, specifies which package Zoi should install when the repository is referenced directly. It allows users to install packages from your repository using `zoi install --repo <repo-spec>` without needing to add the repository source explicitly beforehand.

```yaml
# zoi.yaml in the root of your repository
package: "my-awesome-package"
```

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

### Zoi Installation via AUR (Arch Linux)

Source: https://github.com/zillowe/zoi/blob/main/README.md

Commands to install the zoi package from the Arch User Repository (AUR) using the `yay` helper or by manual compilation. This provides pre-compiled binaries or builds from source.

```sh
yay -S zoi-bin
git clone https://aur.archbuild.org/zoi-bin.git
cd zoi-bin
makepkg -si
```

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

### Zoi Installation via Cargo (Rust)

Source: https://github.com/zillowe/zoi/blob/main/README.md

Command to install the zoi-rs Rust package directly from crates.io using the cargo build tool. Requires Rust and Cargo to be installed.

```sh
cargo install zoi-rs
```

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

### Information & Querying - List Installed Packages

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

List all installed packages.

```APIDOC
## `get_installed_packages` function

List all installed packages.

### Method

`pub fn get_installed_packages`

### Parameters

This function does not take any parameters.

### Response

#### Success Response

Returns a list of installed packages.

#### Error Response

Returns an error if the list cannot be retrieved.
```

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

### Install Package Directly from a Git Repository Specification

Source: https://github.com/zillowe/zoi/blob/main/docs/publishing-packages.mdx

This command installs a package directly from a Git repository specified by its owner and repository name. Zoi will look for a `zoi.yaml` file in the repository root to determine which package to install. It supports various Git hosting services like GitHub and GitLab.

```shell
# Install from GitHub (default)
zoi install --repo YourUsername/my-zoi-repo

# Install from GitLab
zoi install --repo gl:YourUsername/my-zoi-repo
```

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

### Zoi Installation Script for Linux/macOS

Source: https://github.com/zillowe/zoi/blob/main/README.md

Shell script to download and execute the zoi installer on Linux and macOS systems. It uses curl to fetch the script and pipes it to bash for execution.

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

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

### Information & Querying - Check Installation

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

Check if a package is installed.

```APIDOC
## `is_package_installed` function

Check if a package is installed.

### Method

`pub fn is_package_installed`

### Parameters

This function does not take any parameters.

### Response

#### Success Response

Returns `true` if the package is installed, `false` otherwise.

#### Error Response

Returns an error if the check fails.
```

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

### Zoi Package Management Commands

Source: https://github.com/zillowe/zoi/blob/main/README.md

Common command-line interface commands for the Zoi package manager. These include installing, uninstalling, listing, searching packages, managing repositories, and upgrading Zoi itself. Assumes Zoi is installed and in the system's PATH.

```shell
zoi install <package_name>
zoi uninstall <package_name>
zoi install @<repo_name>/<package_name>
zoi list --all
zoi list --all --repo <repo_name>
zoi search <term>
zoi search <term> --repo <repo_name>
zoi repo add
zoi repo add <repo_name>
zoi repo add https://github.com/<user_name>/<repo_name>.git
zoi upgrade
```

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

### Zoi Repository Management Commands

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Commands for managing the list of package repositories that Zoi uses. This includes adding, removing, and listing repositories, as well as managing cloned git repositories.

```shell
# 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

# List all available repositories
zoi repo ls all

# List cloned git repositories
zoi repo git ls

# Remove a cloned git repository
zoi repo git rm my-repo
```

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

### Check Package Installation Status in Zoi

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/index.mdx

Checks if a specific package is installed within a given scope. It returns an Option containing the install manifest if found.

```rust
pub fn is_package_installed(
    package_name: &str,
    scope: Scope,
) -> Result<Option<InstallManifest>, Box<dyn Error>>
```

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

### Pin and Unpin Package with Zoi Rust Library

Source: https://github.com/zillowe/zoi/blob/main/docs/lib/examples.mdx

Demonstrates how to pin a specific version of a package and subsequently unpin it using the Zoi Rust library. It also shows how to list currently pinned packages. Requires the `zoi` crate.

```rust
use zoi::{pin, unpin, get_pinned_packages};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let package_to_pin = "hello";
    let version_to_pin = "1.0.0";

    println!("Pinning {} to version {}", package_to_pin, version_to_pin);
    pin(package_to_pin, version_to_pin)?;

    println!("\nCurrently pinned packages:");
    let pinned = get_pinned_packages()?;
    for p in &pinned {
        println!("- {}@{}", p.name, p.version);
    }

    println!("\nUnpinning {}...", package_to_pin);
    unpin(package_to_pin)?;
    println!("'{}' has been unpinned.", package_to_pin);

    Ok(())
}
```

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

### Zoi CLI Command Execution (Shell)

Source: https://github.com/zillowe/zoi/blob/main/docs/project-config.mdx

Demonstrates how to execute defined commands using the Zoi CLI. Includes examples for running commands by alias, passing arguments, and interactively selecting commands when no alias is specified.

```sh
# Run a command by alias:
zoi run dev

# Pass arguments to the underlying script, separating with --:
# If 'test' is 'npm test', this runs 'npm test -- --watch'
zoi run test -- --watch

# If 'fmt' is 'cargo fmt', this runs 'cargo fmt -- --all'
zoi run fmt --all

# Interactively choose a command (no alias provided):
zoi run

```

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

### Install Zoi Package Directly from Git Repository

Source: https://github.com/zillowe/zoi/blob/main/docs/repositories.mdx

Installs a Zoi package directly from a remote Git repository using the `--repo` flag with `zoi install`. This method is useful for installing packages without permanently adding the repository to your configuration. It supports various Git providers like GitHub, GitLab, and Codeberg.

```sh
# Install from a GitHub repository
zoi install --repo Zillowe/Hello

# Install from a GitLab repository
zoi install --repo gl:Zillowe/Hello

# Install from a Codeberg repository
zoi install --repo cb:Zillowe/Hello
```

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

### Build All Zoi Binaries with Cargo

Source: https://github.com/zillowe/zoi/blob/main/PACKAGING.md

Builds all available Zoi binaries, including 'zoi', 'zoi-completions', and 'zoi-mangen', in release mode using Cargo. This command ensures all project components are compiled.

```sh
cargo build --release
```

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

### Install Zoi Package from Nested or Custom Git Repositories

Source: https://github.com/zillowe/zoi/blob/main/docs/repositories.mdx

Allows installation of Zoi packages from specific locations within Git repositories. This includes installing from top-level repositories, nested paths within official repositories, and custom Git repositories using the '@git/' prefix.

```sh
# Install from the official community repository
zoi install @community/htop

# Install from a nested platform-specific path
zoi install @core/linux/amd64/nvidia-driver

# Install from the root of a custom git repo
zoi install @git/my-zoi-repo/package

# Install from a nested directory within a custom git repo
zoi install @git/my-zoi-repo/path/to/package
```

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

### Zoi Sync Management Commands

Source: https://github.com/zillowe/zoi/blob/main/docs/index.mdx

Commands for managing the Zoi package database registry URL. This includes setting the registry to different keywords or custom URLs and displaying the current registry URL.

```shell
# Set the package database registry URL
zoi sync set default
zoi sync set https://example.com/registry

# Display the current registry URL
zoi sync show
```

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

### Zoi Installation on Fedora with Terra Repo

Source: https://github.com/zillowe/zoi/blob/main/README.md

Instructions to add the Terra repository and install the zoi-rs package on Fedora systems. This method uses the DNF package manager.

```sh
# add terra repo
dnf install --nogpgcheck --repofrompath 'terra,https://repos.fyralabs.com/terra$releasever' terra-release
# install Zoi
sudo dnf install zoi-rs
```

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

### Build Zoi Binary with Cargo

Source: https://github.com/zillowe/zoi/blob/main/PACKAGING.md

Builds the main 'zoi' binary in release mode using Cargo. The output binary will be located in 'target/release/'. This is the standard method for building Rust projects.

```sh
# Build the main zoi binary in release mode
cargo build --bin zoi --release
```

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

### Install Package from a Custom Git Repository

Source: https://github.com/zillowe/zoi/blob/main/docs/publishing-packages.mdx

Installs a specific package from a previously added Git repository. It uses the `@git/` prefix followed by the repository name and the package name. This allows for seamless integration of private or custom packages into your Zoi projects.

```shell
# To install my-first-package from the example above
zoi install @git/my-zoi-repo/my-first-package
```

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

### Copying Additional Files in Zoi Packages (Lua)

Source: https://github.com/zillowe/zoi/blob/main/docs/creating-packages.mdx

Specifies additional files or directories to be copied during installation for 'source' and 'com_binary' types. The 'files' field within an installation method allows defining platform-specific file groups, each containing source paths (relative to build/archive root) and absolute destination paths on the user's system. `~/` can be used for user's home directory.

```lua
install({
  {
    name = "Build from Source",
    type = "source",
    url = "...",
    build_commands = { "make" },
    bin_path = "build/my-cli",
    files = {
      {
        platforms = { "linux", "macos" },
        files = {
          { source = "man/my-cli.1", destination = "/usr/local/share/man/man1/my-cli.1" },
          { source = "completions/my-cli.bash", destination = "/usr/share/bash-completion/completions/my-cli" }
        }
      },
      {
        platforms = { "windows" },
        files = {
          { source = "docs/LICENSE", destination = "C:\\ProgramData\\my-cli\\LICENSE" }
        }
      }
    }
  }
})
```