heretic-cli

Setup & Upgrade

Complete guide to setting up heretic-cli from scratch — prerequisites, installation, initial configuration, first agent creation, upgrading, and health checks

This guide walks you through the complete setup process — from installing prerequisites to running your first agent — and covers how to keep heretic-cli up to date.

Prerequisites

Before installing heretic-cli, make sure you have:

  • Docker — Required for running agent containers. Install Docker Desktop or Docker Engine.
  • Git — For repository operations inside agent containers.
  • Bun — JavaScript/TypeScript runtime used by heretic-cli.

Windows Users

Windows requires Docker Desktop with WSL 2 backend for optimal compatibility.

Install Bun

If you don't have Bun installed:

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Install heretic-cli

bun install -g @giglabo/heretic-cli

Verify the installation:

heretic-cli --version

For alternative installation methods (build from source, native binaries), see the Installation page.

Initial Setup

Run the interactive setup wizard to configure global settings and create your first agent profile:

heretic-cli init

The wizard walks you through:

  1. GitHub token — Used for Git operations inside containers. The token is stored as a script path, never as a raw value.
  2. Agent type — Choose from Anthropic, Third-Party (ZAI, Kimi, custom), Copilot, or Kilocode.
  3. Agent name — A short identifier (e.g., claude, claude-zai, kilocode).
  4. Docker image — Default: giglabo/claude-heretic:latest.
  5. API token — Your provider's API key or OAuth token.
  6. Claude settings — Optional path to an existing settings.json file.

What Gets Created

After running heretic-cli init, you'll have:

~/.heretic/
  settings.yaml              # Global settings (GitHub tokens, etc.)
  agents/
    claude.yaml              # Your agent profile
  get-anthropic-key.sh       # Secret script (Unix)
  get-anthropic-key.cmd      # Secret script (Windows)
  claude-settings.json       # Claude Code settings

CLI-First Approach

All configuration is managed through CLI commands. Do not manually edit files in ~/.heretic/ unless debugging. Use heretic-cli init to modify settings and heretic-cli agents edit to change profiles.

Token Security

All tokens are stored as script paths — executable scripts that output the token value at runtime. The default scripts use a simple echo, but you should replace them with a secure method:

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

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

# GitHub CLI (for GH tokens)
gh auth token

See Secrets for the full reference on secret scripts.

Setting Up a Project

Once your global profile is ready, set up per-project configuration:

cd /path/to/your/project

# Create local config for your agent
heretic-cli local-init claude

This creates .heretic/cli/claude.yaml with project-specific overrides. Add .heretic/cli/ to your .gitignore.

Run Your Agent

heretic-cli run claude
# or shorthand:
heretic-cli claude

The CLI resolves your global profile, merges local overrides, generates temp files (MCP config, settings), and starts the container.

Adding More Agents

You can create multiple agent profiles for different providers:

# Add another agent interactively
heretic-cli agents add claude-zai

# Or run the full wizard again
heretic-cli init

List all configured agents:

heretic-cli agents list

Upgrading heretic-cli

Via Bun (Recommended)

bun update -g @giglabo/heretic-cli

Via Built-in Command

heretic-cli update

If installed via npm/bun, this command directs you to use bun update -g @giglabo/heretic-cli instead.

Verify the Upgrade

heretic-cli --version

Health Checks

Run diagnostics to verify your environment is set up correctly:

heretic-cli doctor

This checks:

  • Docker availability and version
  • Profile validity
  • Secret script accessibility
  • Container image availability

Auto-fix common issues:

heretic-cli doctor --fix

Verbose Mode

Use --verbose on any command for debug output when troubleshooting:

heretic-cli run claude --verbose
heretic-cli doctor --verbose

Deleting an Agent

To completely remove an agent and all associated resources:

heretic-cli agents delete claude

This stops and removes containers, deletes the profile YAML, secret scripts, and settings files. Use -f to skip confirmation.

Next Steps