Installation | VibeCoder Heretic

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)

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.

Install with Bun (recommended)

# 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:

bun update -g @giglabo/heretic-cli

Verify

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

-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.

Build from source

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

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:

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

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.

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 — configure tokens and your first agent
Quick Start — working agent recipes
doctor — verify the environment