heretic-cli

heretic-cli run

Start agent containers in interactive or detached mode with session support, MCP overrides, and command customization

Usage

heretic-cli run claude                 # Interactive mode
heretic-cli run claude -d              # Detached (background) mode
heretic-cli run claude -s feature-x    # Run in named session
heretic-cli run claude --mcp mcp.json  # Override MCP config from file
heretic-cli run claude -- echo hello   # Override container command

Shorthand

Any unknown command is treated as run:

heretic-cli claude                     # Same as: heretic-cli run claude
heretic-cli claude -d                  # Same as: heretic-cli run claude -d
heretic-cli claude -s feature-x        # Same as: heretic-cli run claude -s feature-x

Options

FlagDescription
-dDetached (background) mode
-s, --session <name>Run in a named session
--mcp <path-or-json>Override MCP configuration
--Everything after -- overrides the container command

MCP Override

Override MCP servers at runtime:

# From a JSON file
heretic-cli run claude --mcp ./my-servers.json

# Inline JSON
heretic-cli run claude --mcp '[{"name":"fs","command":"npx","args":["-y","@mcp/server-fs"]}]'

The JSON must be an array of server objects with name and command fields.

How It Works

  1. Resolves configuration by merging global profile + local overrides + CLI flags
  2. Executes secret scripts to retrieve API tokens
  3. Generates and mounts MCP configuration
  4. Merges Claude settings (global + local) and mounts them
  5. Starts the Docker container with the resolved environment

Sessions

Use -s to run multiple isolated instances from the same project:

heretic-cli run claude -s feature-a
heretic-cli run claude -s feature-b

See Sessions for details.