---
title: Setup & Upgrade
description: "End-to-end heretic-cli setup — prerequisites, the init wizard, what it writes to ~/.heretic, project configuration, running your first agent, upgrading, and health checks"
canonical: https://giglabo.com/heretic/docs/heretic-cli/setup-and-upgrade
locale: en
---

# Setup & Upgrade

> Markdown twin of https://giglabo.com/heretic/docs/heretic-cli/setup-and-upgrade
> 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

End-to-end heretic-cli setup — prerequisites, the init wizard, what it writes to ~/.heretic, project configuration, running your first agent, upgrading, and health checks

This guide takes you from an empty machine to a running agent, then covers upgrades and health checks.

## 1. Prerequisites

- **Docker Engine or Docker Desktop** — running, API version ≥ 1.41
- **`docker` CLI on `PATH`** — used for `attach`, `docker compose`, and image builds
- **Bun ≥ 1.2** — for the package install (not needed for a native binary)

> **Warning: Windows**
>
> Docker Desktop with the WSL 2 backend. Secret scripts are generated as `.cmd` files there.

```bash
curl -fsSL https://bun.sh/install | bash          # macOS / Linux
powershell -c "irm bun.sh/install.ps1 | iex"      # Windows
```

## 2. Install

```bash
bun install -g @giglabo/heretic-cli
heretic-cli -v
```

Other options (native binary, from source) are on the [Installation](https://giglabo.com/heretic/docs/heretic-cli/installation) page.

## 3. Global setup: `heretic-cli init`

```bash
heretic-cli init
```

The wizard has two phases and no flags — it is fully interactive and idempotent, so you can re-run it any time.

**Phase 1 — GitHub tokens.** Two optional prompts (GitHub token, GitHub Copilot token). Existing values are shown masked; pressing Enter keeps them. Each token is written into a secret script and only the **script path** is stored in `~/.heretic/settings.yaml`.

**Phase 2 — agent profiles.** A loop where you add or delete profiles. Adding one starts with the agent type:

| Choice | `provider` | `agent_type` | Token |
|--------|-----------|--------------|-------|
| Anthropic (direct API) | `anthropic` | `claude` | optional |
| Third-Party (ZAI, Kimi, or custom) | `thirdparty` | `claude` | required |
| Copilot (custom API) | `copilot` | `copilot-cli` | optional — falls back to the global Copilot token |

Profile names must match `[a-z0-9-_]+`. For Anthropic agents you also choose the **token type** — API key (API billing) or OAuth token (Claude subscription) — which decides the environment block written into the profile.

The full prompt-by-prompt reference is on the [init](https://giglabo.com/heretic/docs/heretic-cli/commands/init) page.

### What gets created

```
~/.heretic/
├── settings.yaml                    # github.token / github.copilot_token (paths to scripts)
├── agents/
│   └── claude.yaml                  # one file per agent profile
├── get-github-token-key.sh          # GitHub token script   (.cmd on Windows)
├── get-copilot-token-key.sh         # Copilot token script  (.cmd on Windows)
├── get-claude-key.sh                # per-agent token script: get-<profile>-key.sh
└── claude-settings.json             # per-agent Claude Code settings: <profile>-settings.json
```

> **Note: CLI-first**
>
> Manage all of this through commands: `heretic-cli init` for tokens, `heretic-cli agents edit <name>` for profiles, `heretic-cli agents mcp <name>` for MCP servers. Hand-edited files stay unvalidated until you run `heretic-cli agents validate`.

### Token security

Tokens live inside generated scripts, and the profile only references the script path. The default script is a plain `echo` — replace the body with your own secret store and nothing else changes:

```bash
#!/bin/bash
# macOS Keychain
security find-generic-password -s 'anthropic-key' -w

# 1Password CLI
op read 'op://vault/Anthropic API/credential'

# pass
pass show anthropic/api-key
```

See [Secrets](https://giglabo.com/heretic/docs/heretic-cli/configuration/secrets) for the three secret value modes and the exact resolution rules.

## 4. Project setup

```bash
cd /path/to/your/project
heretic-cli local-init claude
```

This creates `.heretic/cli/claude.yaml` (a commented template), `.heretic/cli/claude-settings.json`, and `.heretic/temp/`, and suggests adding `.heretic/cli/` to `.gitignore`.

> **Warning: The fresh template parses to null**
>
> The generated `<profile>.yaml` contains only comments, and a local override file that exists **must** parse to an object. Until you uncomment something (or write `extends: <profile>`), `run` and `local-validate` fail with `Invalid config: expected an object`. Deleting the file also works — the global profile alone is a complete configuration. Details on [local-init](https://giglabo.com/heretic/docs/heretic-cli/commands/local-init).

## 5. Run the agent

```bash
heretic-cli run claude
# shorthand:
heretic-cli claude
```

The CLI resolves the global profile, merges the local override and CLI flags, runs secret scripts, generates the session files, and starts the container. See [run](https://giglabo.com/heretic/docs/heretic-cli/commands/run).

## 6. More agents

```bash
heretic-cli agents add claude-zai     # interactive, container-focused prompts
heretic-cli init                      # full wizard, provider presets and model env vars
heretic-cli agents list
```

`agents add` cannot set `secrets`, `mcp`, `provider`, `tool_backends` and similar fields — use `heretic-cli agents edit <name> --editor` or the `init` wizard for those. See [agents](https://giglabo.com/heretic/docs/heretic-cli/commands/agents).

## Upgrading

| Installed via | Upgrade with |
|---------------|--------------|
| Bun package | `bun update -g @giglabo/heretic-cli` |
| Native binary | `heretic-cli update` |

`heretic-cli update` downloads the latest GitHub release asset and stages it next to the executable as `.heretic-cli.pending`; the **next** `heretic-cli` invocation applies it, prints `Update applied successfully!` and exits without running your command — so run it twice:

```bash
heretic-cli update
heretic-cli -v        # applies the staged update, then prints the new version
```

For package installs the command detects it and points you at `bun update` instead. Full behaviour, including rollback, is on the [update](https://giglabo.com/heretic/docs/heretic-cli/commands/update) page.

## Health checks

```bash
heretic-cli doctor
heretic-cli doctor --fix
```

`doctor` checks the Docker daemon, Docker API version, Docker Compose availability, `~/.heretic`, `settings.yaml`, global profiles, local configs, required images, Docker Hub reachability, and volume source paths. `--fix` does exactly two things: create `~/.heretic` and pull missing profile images.

> **Warning: Validate profiles explicitly**
>
> In 0.1.0 the global-profile checks report `0 profile(s) validated` regardless of what you have configured. Use `heretic-cli agents validate` and `heretic-cli local-validate` for real validation — see [doctor](https://giglabo.com/heretic/docs/heretic-cli/commands/doctor).

### Verbose output

`-V/--verbose` and `--log-file` are **program-level** options and must come before the subcommand — anything after the agent name is passed to the container instead:

```bash
heretic-cli -V run claude
heretic-cli --log-file ./heretic.log doctor
```

## Deleting an agent

```bash
heretic-cli agents delete claude        # -f to skip the confirmation
```

Stops and removes that agent's containers, then deletes the profile YAML, its secret scripts (`.sh` and `.cmd`) and its Claude settings file. Project-local `.heretic/` files, images and cache volumes are left alone.

## Next Steps

- [Quick Start](https://giglabo.com/heretic/docs/heretic-cli/quick-start) — three complete agent recipes
- [Agent Profiles](https://giglabo.com/heretic/docs/heretic-cli/configuration/agent-profiles) — full profile schema
- [Docker Images](https://giglabo.com/heretic/docs/heretic-cli/configuration/docker-images) — pick or build an agent image
- [MCP Servers](https://giglabo.com/heretic/docs/heretic-cli/configuration/mcp-servers) — give the agent tools
- [Troubleshooting](https://giglabo.com/heretic/docs/heretic-cli/reference/troubleshooting) — verified symptoms and fixes

## Related

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