> For the complete documentation index, see [llms.txt](https://docs.controltheory.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.controltheory.com/controltheory-documentation/gonzo-docs/getting-started/installation.md).

# Installation

Get Gonzo installed and ready to analyze your logs. Choose the installation method that works best for your environment.

### Package Managers

#### Go Install (Recommended)

If you have Go installed, this is the fastest way to get the latest version:

```bash
go install github.com/control-theory/gonzo/cmd/gonzo@latest
```

#### Homebrew (macOS/Linux)

For macOS and Linux users with Homebrew:

```bash
# Install gonzo
brew install gonzo
```

### Binary Downloads

Download pre-built binaries for your platform from the [GitHub releases page](https://github.com/control-theory/gonzo/releases).

Available for:

* Linux (x86\_64, ARM64)
* macOS (Intel, Apple Silicon)
* Windows (x86\_64)

{% tabs %}
{% tab title="Linux" %}

```bash
# Download and install (replace with latest version)
wget https://github.com/control-theory/gonzo/releases/download/v1.0.0/gonzo-linux-amd64
chmod +x gonzo-linux-amd64
sudo mv gonzo-linux-amd64 /usr/local/bin/gonzo
```

{% endtab %}

{% tab title="macOS" %}

```bash
# Download and install (replace with latest version)
curl -L -o gonzo https://github.com/control-theory/gonzo/releases/download/v1.0.0/gonzo-darwin-amd64
chmod +x gonzo
sudo mv gonzo /usr/local/bin/gonzo
```

{% endtab %}

{% tab title="Windows" %}

1. Download `gonzo-windows-amd64.exe` from the releases page
2. Rename to `gonzo.exe`
3. Add to your PATH or place in a directory that's already in PATH
   {% endtab %}
   {% endtabs %}

### Build from Source

For development or to get the absolute latest features:

#### Prerequisites

* Go 1.21 or higher
* Make (optional, for convenience commands)

#### Build Steps

```bash
# Clone the repository
git clone https://github.com/control-theory/gonzo.git
cd gonzo

# Build using Make (recommended)
make build

# Or build directly with Go
go build -o gonzo cmd/gonzo/main.go

# Install to GOPATH/bin
go install ./cmd/gonzo
```

#### Development Build Options

```bash
# Quick build
make build

# Development mode (format, vet, test, build)
make dev

# Build for all platforms
make cross-build

# Run tests
make test
```

### Shell Completion

Enable shell autocompletion for a better CLI experience:

{% tabs %}
{% tab title="Bash" %}

```bash
# Add to ~/.bashrc
source <(gonzo completion bash)

# Or install permanently
gonzo completion bash > /usr/local/share/bash-completion/completions/gonzo
```

{% endtab %}

{% tab title="Zsh" %}

```bash
# Add to ~/.zshrc
source <(gonzo completion zsh)

# Or install permanently (for oh-my-zsh)
gonzo completion zsh > ~/.oh-my-zsh/completions/_gonzo
```

{% endtab %}

{% tab title="Fish" %}

```bash
gonzo completion fish | source

# Or install permanently
gonzo completion fish > ~/.config/fish/completions/gonzo.fish
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
# Add to your PowerShell profile
gonzo completion powershell | Out-String | Invoke-Expression
```

{% endtab %}
{% endtabs %}

### Verification

Verify your installation is working:

```bash
# Check version
gonzo version

# Test with sample logs
echo '{"level":"info","msg":"test log"}' | gonzo

# View help
gonzo --help
```

### What's Next?

* Quick Start Tutorial - Learn the basics with a hands-on example
* Basic Usage - Common usage patterns
* Interface Overview - Understanding the Gonzo dashboard

### Troubleshooting Installation

#### Common Issues

**Command not found after installation**

* Make sure `$GOPATH/bin` is in your PATH for Go installs
* For manual installations, verify the binary is in your PATH

**Permission denied errors**

* Use `sudo` when moving binaries to system directories
* Or install to user directories like `~/bin`

**Go version errors**

* Gonzo requires Go 1.21 or higher
* Update Go: <https://golang.org/dl/>

Need help? Check our Troubleshooting Guide or [open an issue](https://github.com/control-theory/gonzo/issues).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.controltheory.com/controltheory-documentation/gonzo-docs/getting-started/installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.