---
title: heretic-cli
description: Command-line interface for managing containerized AI coding agents with layered configuration, secure secrets, build sidecars, and multi-provider support
canonical: https://giglabo.com/heretic/docs/heretic-cli
locale: en
---

# heretic-cli

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

Command-line interface for managing containerized AI coding agents with layered configuration, secure secrets, build sidecars, and multi-provider support

`heretic-cli` runs AI coding agents (Claude Code, GitHub Copilot CLI, OpenCode, Gemini CLI) inside Docker containers on your own machine or server. It manages the agent profiles, the images they run in, the secrets they need, the MCP servers they talk to, and the sibling containers that carry build toolchains.

It is a single native executable built with Bun and TypeScript — no runtime dependency tree, no daemon of its own.

## CLI-First Approach

All agent configuration is done through CLI commands. The CLI creates and manages:

- **Secret scripts** — small executables that print API tokens on demand, so no token is ever written into YAML
- **Claude settings** — Claude Code permissions and model configuration per agent
- **Agent profiles** — the full container definition (image, volumes, env, MCP, runner)

> **Note: Never edit generated config by hand**
>
> Use `heretic-cli init`, `heretic-cli agents edit` and `heretic-cli local-init` for all changes. Hand-edited files are not validated until you run `heretic-cli agents validate` or `heretic-cli local-validate`.

## Key Features

- **Multi-provider support** — Anthropic (API key or OAuth subscription), third-party Anthropic-compatible APIs (ZAI, Kimi, or any custom base URL), and GitHub Copilot
- **Layered configuration** — global profile → per-project override → CLI flags, with `${VAR}` interpolation
- **Secure secrets** — token values come from scripts, environment references, or literals, resolved at run time
- **MCP integration** — inline servers, external JSON files, and auto-detection of the three common MCP JSON shapes
- **Sessions** — several isolated instances of the same agent in the same project
- **Build sidecars** — keep `npm`, `pip`, `mvn`, `go`, `cargo` out of the agent image and run them in sibling containers over HTTP, or on a remote host over SSH
- **Image builder** — generate and build agent images and builder images from templates, single- or multi-arch
- **Cross-platform** — Linux, macOS and Windows

## Commands at a Glance

| Command | What it does |
|---------|--------------|
| `init` | Interactive global setup: GitHub tokens and agent profiles |
| `agents` | Profile CRUD: `list`, `add`, `edit`, `show`, `validate`, `delete`, `mcp` |
| `local-init` | Create a per-project override for a profile (or a `compose.yaml` template) |
| `local-validate` | Resolve and validate the project's local configs |
| `run` | Start an agent container (also reachable as `heretic-cli <profile>`) |
| `ps` / `stop` / `attach` | Inspect, stop and re-attach to running agents |
| `image` | Build agent images, builder (sidecar) images, or print generated templates |
| `doctor` | Environment health checks |
| `update` | Self-update from the latest GitHub release |

## Quick Overview

```bash
# 1. Global setup: tokens + first agent profile
heretic-cli init

# 2. Per-project overrides (optional but recommended)
cd ~/code/my-project
heretic-cli local-init claude

# 3. Run the agent in this directory
heretic-cli run claude          # or: heretic-cli claude
```

## Next Steps

- [Installation](https://giglabo.com/heretic/docs/heretic-cli/installation) — install heretic-cli
- [Setup & Upgrade](https://giglabo.com/heretic/docs/heretic-cli/setup-and-upgrade) — end-to-end first-time setup
- [Quick Start](https://giglabo.com/heretic/docs/heretic-cli/quick-start) — three working agent recipes
- [Commands](https://giglabo.com/heretic/docs/heretic-cli/commands) — full command reference
- [Configuration](https://giglabo.com/heretic/docs/heretic-cli/configuration) — profiles, overrides, secrets, MCP, sidecars

## Related

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