heretic-cli init

Synopsis

heretic-cli init          # no options other than -h/--help

Two phases: GitHub tokens → ~/.heretic/settings.yaml, then an agent profile loop → ~/.heretic/agents/. The wizard is idempotent — re-run it to change tokens or add agents.

Phase 1 — GitHub tokens

Enter your GitHub token (optional, press Enter to skip):
Enter GitHub Copilot token (optional, press Enter to skip):

Existing values are shown masked (first 8 characters + **** + last 4; anything shorter than 12 characters becomes ****). Submitting the masked default unchanged keeps the existing script path — the comparison is literal, so do not hand-edit the masked value.

For each new token a secret script is written, and only its path is stored:

The Copilot token uses get-copilot-token-key.sh / .cmd.

# ~/.heretic/settings.yaml
github:
  token: /home/you/.heretic/get-github-token-key.sh
  copilot_token: /home/you/.heretic/get-copilot-token-key.sh

Both fields also accept a raw token for backward compatibility: the value is only executed when it ends in .sh, .cmd, .ps1 or .bat.

These tokens are injected into every container as GH_TOKEN and GITHUB_TOKEN, and additionally as GH_COPILOT_TOKEN / GITHUB_COPILOT_TOKEN when the profile has provider: copilot (falling back to the GitHub token if no Copilot token is set).

Token security

The generated script is a deliberate seam — replace its body with your own secret store:

# Unix (.sh)
security find-generic-password -s 'github-token' -w      # macOS Keychain
op read 'op://vault/github/token'                        # 1Password CLI
pass show github/token                                   # pass
gh auth token                                            # GitHub CLI

@echo off
op read "op://vault/github/token"

(Get-StoredCredential -Target "github-token").GetNetworkCredential().Password

The shell is chosen by extension: .sh → bash (Git Bash or WSL on Windows), .cmd / .bat → cmd.exe, .ps1 → powershell -ExecutionPolicy Bypass -File. On Windows the wizard only generates .cmd; .ps1 scripts work but must be created by hand.

Phase 2 — agent profiles

=== Current Agent Profiles ===
1. claude - giglabo/claude-heretic (docker)

What would you like to do?
  > Add new agent
    Delete agent          (only when at least one profile exists)
    Done managing agents

Add new agent starts with the agent type:

Profile names must match [a-z0-9-_]+ (case-insensitive). If ~/.heretic/agents/<name>.yaml exists you are asked to confirm the overwrite.

Anthropic flow

Prompts: name (default claude) → Docker image (default giglabo/claude-heretic) → token (optional) → token type (only when a token was given) → optional path to an existing settings.json.

The empty strings are intentional: they stop Claude Code from falling back to API mode. Empty values are normally stripped from the container environment, but a key explicitly set to "" in env is preserved.

Third-party flow (ZAI / Kimi / custom)

All presets seed CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and API_TIMEOUT_MS=600000. You then choose Keep defaults, Modify default values, or Add more env vars (a loop that ends on an empty name; names must match [A-Z_][A-Z0-9_]*).

Next you decide where the model configuration lives:

• Environment Variables — the six model variables go into the profile's env
• Settings JSON — they go into the env block of ~/.heretic/<name>-settings.json instead (or you point at an existing settings file, which must exist)

The six variables:

main   ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL
small  ANTHROPIC_SMALL_FAST_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, CLAUDE_CODE_SUBAGENT_MODEL

Leaving the small model blank makes it fall back to the primary model.

Copilot flow

Prompts: name (default copilot) → Docker image (required, no default) → optional dedicated token. With a dedicated token the profile gets a PROFILENAME_TOKEN variable fed from the matching PROFILENAME_API_KEY secret — the profile name uppercased with dashes turned into underscores, so my-copilot becomes MY_COPILOT_TOKEN; without one the container relies on the global GH_COPILOT_TOKEN / GITHUB_COPILOT_TOKEN injection. No ANTHROPIC_* variables and no Claude settings file are created for Copilot agents.

What a created profile looks like

image: giglabo/claude-heretic
runner: docker
agent_type: claude              # copilot-cli when provider is copilot
provider: anthropic             # anthropic | thirdparty | copilot
description: Anthropic agent    # or "Third-party agent (zai)" / "Copilot agent"
interactive: true
tty: true
volumes:
  - source: ${CWD}
    target: /workspace
workdir: /workspace
env: {}                         # provider-specific, see above
claude_settings: /home/you/.heretic/claude-settings.json   # omitted for copilot
secrets:
  CLAUDE_API_KEY: /home/you/.heretic/get-claude-key.sh     # only when a token was given

The secret variable name is derived from the profile name: uppercase, - → _, suffix _API_KEY (so claude-zai → CLAUDE_ZAI_API_KEY). A secret that is not also referenced in env is resolved but not exported into the container — it exists only for ${…} interpolation.

Default Claude settings file

When you do not supply an existing settings file, ~/.heretic/<name>-settings.json is created as:

{
  "permissions": {
    "allow": ["Read", "Edit", "Write", "Bash", "WebFetch", "WebSearch", "mcp__*"]
  },
  "model": "opus"
}

At run time this is merged with the project's .heretic/cli/claude-settings.json (arrays unioned, objects shallow-merged, local wins) and mounted as ~/.claude/settings.json inside the container.

Deleting from the wizard vs agents delete

The wizard's Delete agent removes only three paths and never touches containers: ~/.heretic/agents/<name>.yaml, ~/.heretic/get-<name>-key.sh, ~/.heretic/<name>-settings.json. It does not remove Windows .cmd scripts. Use heretic-cli agents delete <name> for a complete removal including containers.

Final summary

=== Configuration Complete ===
GitHub Token: ghp_xxxx****abcd
GitHub Copilot Token: (not configured)

Agent Profiles: 2
  - claude
  - claude-zai

Run an agent with: heretic-cli <profile-name>

Gotchas

• Tokens are stored in plaintext inside the generated script — protect the file, or replace its body with a secret-manager call.
• init never creates project-local configuration; that is local-init.
• The directories ~/.heretic and ~/.heretic/agents are created up front, so a cancelled wizard can leave an empty profile directory behind.
• A secret script that prints nothing logs Secret script returned empty value (a warning, not an error) and the variable ends up empty — and then gets stripped from the container environment.

Next Steps

• agents — inspect, edit and validate what the wizard created
• Secrets — the three secret value modes
• Agent Profiles — the full profile schema