heretic-cli init
Interactive setup wizard for global settings, agent profiles, token security, and multi-provider configuration
heretic-cli init
Token Security
All tokens (GitHub, Copilot, API keys) are stored as script paths, never as raw values:
# ~/.heretic/settings.yaml - stores script paths, not raw tokens
github:
token: /Users/you/.heretic/get-github-token-key.sh
copilot_token: /Users/you/.heretic/get-copilot-token-key.sh
The wizard creates executable scripts that output the token. Replace the default echo with a secure method:
Unix (.sh)
# macOS Keychain
security find-generic-password -s 'github-token' -w
# 1Password CLI
op read 'op://vault/github/token'
# pass (Unix password manager)
pass show github/token
Windows (.cmd)
@echo off
REM 1Password CLI
op read "op://vault/github/token"
PowerShell (.ps1)
# Windows Credential Manager
(Get-StoredCredential -Target "github-token").GetNetworkCredential().Password
The secret execution engine automatically selects the correct shell based on script extension:
.sh→bash(on Windows: Git Bash or WSL).cmd/.bat→cmd.exe.ps1→powershell -ExecutionPolicy Bypass -File
Agent Types
The init wizard supports four agent types:
| Type | Description | API Token | API URL |
|---|---|---|---|
| Anthropic | Direct Anthropic API | API key or OAuth token | Default (api.anthropic.com) |
| Third-Party | Proxy API (ZAI, Kimi, custom) | Provider API key | Custom URL |
| Copilot | Custom API (no Anthropic env vars) | Custom token | Not applicable |
| Kilocode | Kilo Code (OpenCode) agent | Kilocode API key | Not applicable |
Anthropic Token Types
When providing an Anthropic token, you choose the type:
| Token Type | Env Vars Set | Use Case |
|---|---|---|
| API Key | ANTHROPIC_API_KEY → mapped to ANTHROPIC_AUTH_TOKEN + ANTHROPIC_AUTH_KEY | Pay-per-use API billing |
| OAuth Token | CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN="", ANTHROPIC_BASE_URL="" | Claude subscription (Pro/Team) |
The empty ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL values are intentional — they prevent Claude Code from falling back to API mode when using an OAuth/subscription token.
Third-Party Providers
Third-party agents support multiple API providers through presets:
| Preset | Default URL | Default Model |
|---|---|---|
| ZAI | https://api.z.ai/api/anthropic | glm-5 |
| Kimi | https://api.moonshot.ai/anthropic | kimi-k2.5 |
| Custom | (user enters) | (user enters) |
Configuration Flow
- Select preset — Choose ZAI, Kimi, or Custom
- Enter agent name — Default based on preset (e.g.,
claude-zai,claude-kimi) - Enter API URL — Pre-filled for ZAI/Kimi, manual for Custom
- Enter API token — Your provider's API key
- Enter Docker image — Default:
giglabo/claude-heretic - Choose model config method — Environment variables or Settings JSON
- Enter model name — Pre-filled based on preset
- Customize environment variables — Review and modify preset defaults
Default Environment Variables
All presets include:
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
API_TIMEOUT_MS=600000
Model-related env vars (set to your chosen model):
ANTHROPIC_MODEL
ANTHROPIC_SMALL_FAST_MODEL
ANTHROPIC_DEFAULT_OPUS_MODEL
ANTHROPIC_DEFAULT_SONNET_MODEL
ANTHROPIC_DEFAULT_HAIKU_MODEL
CLAUDE_CODE_SUBAGENT_MODEL
Agent Settings
All agent types support an optional path to an existing settings.json file during setup:
- If provided, your settings are copied and used as the base
- If not provided, default settings with permissions are created
Copilot agents do not set any ANTHROPIC_* environment variables. The agent's API token is exposed as <NAME>_TOKEN (e.g., MYAGENT_TOKEN).
Kilocode Agents
When you select the Kilocode agent type, the wizard:
- Prompts for an agent name (e.g.,
kilocode) - Prompts for a Docker image (default:
giglabo/claude-heretic) - Optionally collects a Kilocode API key
- Creates three additional files:
- OpenCode settings (
~/.heretic/<name>-opencode.json) — enables auto-approve mode ("permission": "allow") - Kilocode MCP settings (
~/.heretic/<name>-kilocode-mcp.json) — global MCP server definitions for Kilo Code - Secret script (if API key provided) —
.sh(Unix) or.cmd(Windows)
- OpenCode settings (
The resulting profile includes:
provider: kilocode
agent_type: kilocode-cli
opencode_settings: ~/.heretic/<name>-opencode.json
kilocode_mcp_settings: ~/.heretic/<name>-kilocode-mcp.json
secrets:
KILOCODE_API_KEY: ~/.heretic/get-<name>-key.sh
env:
KILOCODE_API_KEY: "${KILOCODE_API_KEY}"
No Claude settings file is created for Kilocode agents — they use OpenCode's configuration format instead.