heretic-cli

Commands

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

CommandDescription
initInteractive setup wizard for GitHub tokens and agent profiles
agentsManage global agent profiles and their MCP servers
local-initScaffold per-project configuration (and validate it with local-validate)
runStart an agent container
ps, stop, attachContainer lifecycle

Build and maintenance commands

CommandDescription
imageBuild agent images and builder (sidecar) images, or print generated templates
doctorEnvironment health checks, with a limited --fix
updateTwo-phase self-update from the latest GitHub release

Global options

FlagMeaning
-v, --versionprint the version and exit 0
-V, --verboseverbose (debug-level) logging
--log-file <path>tee all logs (trace level) to a file; parent directories are created
-h, --helphelp for the command or subcommand, exit 0

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

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 shorthandNot 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 --
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 outputCommand
JSONheretic-cli ps --json, heretic-cli agents list --json
YAMLheretic-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

CodeMeaning
0success; --help / --version; doctor with no failures; "nothing matched" messages from stop
1argument errors, command failures, doctor with at least one [fail], failed validation
container's own coderun in interactive mode exits with the exit code of the container
124 / 255inside 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