---
title: Commands
description: "Complete heretic-cli command reference — command map, global options, the shorthand form, argument parsing rules, logging, machine-readable output, and exit codes"
canonical: https://giglabo.com/heretic/docs/heretic-cli/commands
locale: en
---

# Commands

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

Complete heretic-cli command reference — command map, global options, the shorthand form, argument parsing rules, logging, machine-readable output, and exit codes

## Synopsis

```
heretic-cli [-v|--version] [-V|--verbose] [--log-file <path>] <command> [args]
```

## Command map

```
heretic-cli
├── init                                    Interactive global setup (tokens + agent profiles)
├── agents
│   ├── list [--json]
│   ├── add <name> [--force]
│   ├── edit <name> [--editor]
│   ├── show <name> [--resolved] [--reveal]
│   ├── validate [name]
│   ├── delete <name> [-f|--force]
│   └── mcp <name> [--local] [--file <path>]
├── local-init [profile] [--compose] [-f|--force]
├── local-validate [profile]
├── run <agent-name> [command...]           -d, -s, --mcp, --root,
│                                           --sidecar, --builder-image, --disable-sidecars
├── <agent-name>                            shorthand for `run <agent-name>`
├── ps [--json] [-s|--session <name>]
├── stop [name] [--all] [-f|--force] [--keep] [-s|--session <name>]
├── attach <name> [-s|--session <name>]
├── image
│   ├── build [agent/tool flags] [-n|-t|-r|-p|--no-cache|--dry-run|-a]
│   ├── build-sidecar <node|python|java|go|rust> [flags]
│   └── generate [--format dockerfile|entrypoint|ssh-exec|sidecar-exec|sidecar-dockerfile|exec-server]
├── doctor [--fix]
└── update
```

## Core commands

| Command | Description |
|---------|-------------|
| [`init`](https://giglabo.com/heretic/docs/heretic-cli/commands/init) | Interactive setup wizard for GitHub tokens and agent profiles |
| [`agents`](https://giglabo.com/heretic/docs/heretic-cli/commands/agents) | Manage global agent profiles and their MCP servers |
| [`local-init`](https://giglabo.com/heretic/docs/heretic-cli/commands/local-init) | Scaffold per-project configuration (and validate it with `local-validate`) |
| [`run`](https://giglabo.com/heretic/docs/heretic-cli/commands/run) | Start an agent container |
| [`ps`, `stop`, `attach`](https://giglabo.com/heretic/docs/heretic-cli/commands/ps-stop-attach) | Container lifecycle |

## Build and maintenance commands

| Command | Description |
|---------|-------------|
| [`image`](https://giglabo.com/heretic/docs/heretic-cli/commands/image) | Build agent images and builder (sidecar) images, or print generated templates |
| [`doctor`](https://giglabo.com/heretic/docs/heretic-cli/commands/doctor) | Environment health checks, with a limited `--fix` |
| [`update`](https://giglabo.com/heretic/docs/heretic-cli/commands/update) | Two-phase self-update from the latest GitHub release |

## Global options

| Flag | Meaning |
|------|---------|
| `-v`, `--version` | print the version and exit 0 |
| `-V`, `--verbose` | verbose (debug-level) logging |
| `--log-file <path>` | tee all logs (trace level) to a file; parent directories are created |
| `-h`, `--help` | help for the command or subcommand, exit 0 |

> **Warning: -v is version, -V is verbose — and both are program-level**
>
> The lowercase/uppercase pair is the opposite of most CLIs. Global flags must appear **before** the subcommand, because everything after an agent name belongs to the container command:
>
> ```bash
> heretic-cli -V run claude            # correct: verbose CLI
> heretic-cli run claude --verbose     # WRONG: --verbose is passed into the container
> ```

## Shorthand: `heretic-cli <profile>`

An unknown command is treated as a profile name, so `heretic-cli claude` is `heretic-cli run claude`. This path parses arguments by hand and supports a subset of `run`'s flags:

| Supported in shorthand | Not supported |
|------------------------|---------------|
| `-d` / `--detach` | `--mcp <value>` (silently ignored) |
| `-s` / `--session <name>` | trailing command words without `--` |
| `--root`, `--disable-sidecars` | |
| `--sidecar <runtime>`, `--builder-image <rt>=<img>` | |
| a custom command **after** `--` | |

```bash
heretic-cli claude -s feature-x -- npm test     # works
heretic-cli claude npm test                     # does NOT run npm test
heretic-cli run claude npm test                 # use this instead
```

## Argument parsing rules

- **`run` passes options through.** Everything after the agent name — including flags — becomes the container command, which is why `run claude --watch` sends `--watch` to the container.
- **`--root` is hoisted.** The first `--root` found before a `--` separator is moved next to the command keyword, so `run --root claude` and `run claude --root` are equivalent. After `--` it is left untouched: `run claude -- npm test --root` keeps `--root` as an npm flag.
- **`--` ends heretic's own parsing.** Use it whenever your command has flags of its own.

## Logging and machine-readable output

Logs go through a pino logger on **stdout**: `LEVEL message` with colors in the compiled binary, pretty-printed timestamps in dev mode. Machine-readable payloads are printed on the same stream, so filter them when scripting:

| Machine-readable output | Command |
|-------------------------|---------|
| JSON | `heretic-cli ps --json`, `heretic-cli agents list --json` |
| YAML | `heretic-cli agents show <name> [--resolved]`, `heretic-cli local-validate [profile]` |

There is no global `--json` flag, no `--no-color`, and no shell-completion generator.

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | success; `--help` / `--version`; `doctor` with no failures; "nothing matched" messages from `stop` |
| `1` | argument errors, command failures, `doctor` with at least one `[fail]`, failed validation |
| *container's own code* | `run` in interactive mode exits with the exit code of the container |
| `124` / `255` | inside the container: `sidecar-exec` timeout / server-side start failure |

## What heretic-cli deliberately does not do

- No `logs`, `exec`, `restart`, `rm` or `inspect` — use the `docker` CLI (`docker logs heretic-<agent>-<session>-<hash>`); `attach` is the only session entry point.
- No `agents rename`/`copy`, and no non-interactive `agents add` — script it by writing `~/.heretic/agents/<name>.yaml` and validating with `agents validate`.
- No `run --dry-run` — the closest equivalents are `agents show <name> --resolved` and `local-validate <profile>`.
- No pinned/rollback self-update — `update` only ever moves to the latest release.

## Next Steps

- [run](https://giglabo.com/heretic/docs/heretic-cli/commands/run) — every flag and what lands in the container
- [Configuration](https://giglabo.com/heretic/docs/heretic-cli/configuration) — the three config layers
- [Reference: Troubleshooting](https://giglabo.com/heretic/docs/heretic-cli/reference/troubleshooting) — error messages and fixes

## Related

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