---
title: Installation
description: Install heretic-cli with Bun, build a native binary from source, and verify the Docker prerequisites on Linux, macOS, and Windows
canonical: https://giglabo.com/heretic/docs/heretic-cli/installation
locale: en
---

# Installation

> Markdown twin of https://giglabo.com/heretic/docs/heretic-cli/installation
> Fetch this instead of the HTML page: same content, a fraction of the bytes.
> Site structure and the full page list for agents: https://giglabo.com/llms.txt

Install heretic-cli with Bun, build a native binary from source, and verify the Docker prerequisites on Linux, macOS, and Windows

## Prerequisites

| Requirement | Why it is needed |
|-------------|------------------|
| **Docker Engine** or **Docker Desktop** | runs the agent containers; the CLI talks to the daemon through the Docker API (minimum API version **1.41**) |
| **`docker` CLI on `PATH`** | `attach` shells out to `docker attach`, the compose runner to `docker compose`, `image build` to `docker build` / `docker buildx` — the daemon socket alone is not enough |
| **Bun ≥ 1.2** | for the package install and for building from source; a native binary needs no runtime |
| **Git** | for repository work inside the container (the agent images ship it) |

> **Warning: Windows**
>
> Use Docker Desktop with the WSL 2 backend. On Windows the CLI generates `.cmd` secret scripts instead of `.sh`; PowerShell `.ps1` scripts also work but must be written by hand — see [Secrets](https://giglabo.com/heretic/docs/heretic-cli/configuration/secrets).

## Install with Bun (recommended)

```bash
# Install Bun if you don't have it
curl -fsSL https://bun.sh/install | bash          # macOS / Linux
powershell -c "irm bun.sh/install.ps1 | iex"      # Windows

# Install the CLI globally
bun install -g @giglabo/heretic-cli
```

The published package ships a Bun-targeted bundle exposed as the `heretic-cli` binary, so Bun must stay installed. For a self-contained executable, build a native binary (below).

Upgrade the same way:

```bash
bun update -g @giglabo/heretic-cli
```

### Verify

```bash
heretic-cli -v          # prints the version, e.g. 0.1.0
heretic-cli doctor      # environment health checks
```

> **Warning: -v is version, -V is verbose**
>
> `heretic-cli` uses the opposite convention to most CLIs: lowercase `-v` prints the version, uppercase `-V` enables verbose logging, and it must be placed **before** the subcommand. See [Commands](https://giglabo.com/heretic/docs/heretic-cli/commands).

## Build from source

```bash
git clone https://github.com/giglabo/heretic.git
cd heretic/cli
bun install

bun run dev -- --help    # run straight from source
bun run dev -- init
```

## Native binary

```bash
cd heretic/cli
bun install

bun run build            # current platform   → dist/heretic-cli
bun run build:all        # all release targets → dist/heretic-cli-<platform>-<arch>
```

Individual targets: `build:linux-x64`, `build:linux-arm64`, `build:macos-x64`, `build:macos-arm64`, `build:windows`.

Move the artifact onto your `PATH` — prefer a user-owned directory, because `heretic-cli update` replaces the binary in place and needs write access to its own directory:

```bash
install -m 0755 dist/heretic-cli ~/.local/bin/heretic-cli
```

> **Note: Keep dev builds off your PATH**
>
> `heretic-cli update` overwrites the running binary with the latest **release** asset, including a locally built one. See [update](https://giglabo.com/heretic/docs/heretic-cli/commands/update).

## Platform support

| Platform | Architecture | Native build target |
|----------|--------------|---------------------|
| Linux | x64, arm64 | `build:linux-x64`, `build:linux-arm64` |
| macOS | x64, arm64 | `build:macos-x64`, `build:macos-arm64` |
| Windows | x64 | `build:windows` |

Windows arm64 has no dedicated build target — install with Bun there.

## Next Steps

- [Setup & Upgrade](https://giglabo.com/heretic/docs/heretic-cli/setup-and-upgrade) — configure tokens and your first agent
- [Quick Start](https://giglabo.com/heretic/docs/heretic-cli/quick-start) — working agent recipes
- [doctor](https://giglabo.com/heretic/docs/heretic-cli/commands/doctor) — verify the environment

## Related

- HTML version of this page: https://giglabo.com/heretic/docs/heretic-cli/installation
- Site map for agents: https://giglabo.com/llms.txt