> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lucasgelfond/zerobrew/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Get started with zerobrew and run your first commands

# Quick start

This guide will help you get started with zerobrew by walking through the most common commands and workflows.

## Your first installation

Let's install a package using zerobrew. We'll use `jq`, a popular command-line JSON processor:

<Steps>
  <Step title="Install a package">
    Run the install command:

    ```bash theme={null}
    zb install jq
    ```

    You'll see output showing the installation progress:

    ```
    ==> Installing jq...
    ==> Resolving dependencies (1 packages)...
        jq 1.7.1
    ==> Downloading and installing formulas...
        jq               ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed

    ==> Installed 1 packages in 0.68s
    ```
  </Step>

  <Step title="Verify the installation">
    Check that `jq` is now available:

    ```bash theme={null}
    jq --version
    ```

    You should see the version number printed.
  </Step>
</Steps>

## Installing multiple packages

You can install multiple packages in a single command:

```bash theme={null}
 zb install wget git curl
```

zerobrew will automatically:

* Resolve all dependencies
* Download packages in parallel
* Install them efficiently using content-addressable storage

## Working with Brewfiles

Brewfiles allow you to manage your packages as code. This is useful for reproducible environments and dotfiles.

<Steps>
  <Step title="Create a Brewfile">
    Create a file named `Brewfile` in your project directory:

    ```ruby Brewfile theme={null}
    # Development tools
    brew "git"
    brew "wget"
    brew "jq"

    # Programming languages
    brew "python@3.11"
    brew "node"

    # Optional: casks (macOS applications)
    # cask "docker-desktop"
    ```
  </Step>

  <Step title="Install from Brewfile">
    Install all packages from the Brewfile:

    ```bash theme={null}
    zb bundle
    ```

    Or specify a custom file:

    ```bash theme={null}
    zb bundle install -f myfile
    ```
  </Step>

  <Step title="Export current packages">
    You can also export your currently installed packages to a Brewfile:

    ```bash theme={null}
    zb bundle dump
    ```

    To overwrite an existing file:

    ```bash theme={null}
    zb bundle dump -f Brewfile --force
    ```
  </Step>
</Steps>

## Running without installing

Use `zbx` to run a package without linking it to your prefix:

```bash theme={null}
zbx jq --version
```

This is useful for:

* One-time commands
* Testing packages before installation
* Running different versions temporarily

## Common commands

Here's a quick reference of the most common zerobrew commands:

<CodeGroup>
  ```bash Install packages theme={null}
  # Install one package
  zb install jq

  # Install multiple packages
  zb install wget git curl

  # Build from source instead of using bottles
  zb install ffmpeg --build-from-source

  # Install without creating symlinks
  zb install libsodium --no-link
  ```

  ```bash Manage packages theme={null}
  # List installed packages
  zb list

  # Get package information
  zb info jq

  # Uninstall a package
  zb uninstall jq

  # Check for outdated packages
  zb outdated

  # Update package metadata
  zb update
  ```

  ```bash Bundle operations theme={null}
  # Install from Brewfile
  zb bundle

  # Install from custom file
  zb bundle install -f myfile

  # Export installed packages
  zb bundle dump

  # Export to custom file (overwrite)
  zb bundle dump -f output --force
  ```

  ```bash Maintenance theme={null}
  # Garbage collect unused store entries
  zb gc

  # Remove all installed packages
  zb reset

  # Initialize zerobrew environment
  zb init
  ```
</CodeGroup>

## Advanced options

zerobrew supports several global options:

### Concurrency control

Adjust the number of parallel operations (default is 20):

```bash theme={null}
zb --concurrency 10 install ffmpeg
```

### Custom directories

Override the default installation directories:

```bash theme={null}
zb --root /custom/root --prefix /custom/prefix install jq
```

Or use environment variables:

```bash theme={null}
export ZEROBREW_ROOT="/custom/root"
export ZEROBREW_PREFIX="/custom/prefix"
zb install jq
```

### Auto-initialize

Automatically initialize zerobrew if not already set up:

```bash theme={null}
zb --auto-init install jq
```

## Shell completion

Generate shell completion scripts for your shell:

<CodeGroup>
  ```bash Bash theme={null}
  zb completion bash > ~/.local/share/bash-completion/completions/zb
  ```

  ```bash Zsh theme={null}
  zb completion zsh > "${fpath[1]}/_zb"
  ```

  ```bash Fish theme={null}
  zb completion fish > ~/.config/fish/completions/zb.fish
  ```
</CodeGroup>

## Understanding the output

When you install a package, zerobrew shows detailed progress:

```
==> Installing jq...
```

Indicates the package being installed.

```
==> Resolving dependencies (3 packages)...
    jq 1.7.1
    oniguruma 6.9.9
    libffi 3.4.4
```

Shows all packages that will be installed, including dependencies.

```
==> Downloading and installing formulas...
    jq               ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
    oniguruma        ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
    libffi           ━━━━━━━━━━━━━━━━━━━━━━━━ ✓ installed
```

Progress bars for each package showing download and installation status.

```
==> Installed 3 packages in 1.23s
```

Summary with total time elapsed.

## Next steps

<CardGroup cols={2}>
  <Card title="Commands reference" icon="terminal">
    Explore all available zerobrew commands and options
  </Card>

  <Card title="Configuration" icon="gear">
    Learn about environment variables and configuration options
  </Card>
</CardGroup>

<Tip>
  Remember that zerobrew is experimental. If you encounter issues with a specific formula, you can always fall back to using Homebrew for that package while using zerobrew for others.
</Tip>