heretic-cli

heretic-cli agents

Manage global agent profiles — list, add, edit, delete, validate profiles and configure MCP servers

Subcommands

heretic-cli agents list                    # List all profiles
heretic-cli agents list --json             # JSON output
heretic-cli agents add <name>              # Create a new profile (interactive)
heretic-cli agents edit <name>             # Edit a profile
heretic-cli agents edit <name> --editor    # Open in $EDITOR
heretic-cli agents show <name>             # Display profile config
heretic-cli agents show <name> --resolved  # Show after interpolation
heretic-cli agents show <name> --reveal    # Show sensitive values
heretic-cli agents delete <name>           # Delete agent (with confirmation)
heretic-cli agents delete <name> -f        # Delete without confirmation
heretic-cli agents validate                # Validate all profiles
heretic-cli agents validate <name>         # Validate a specific profile
heretic-cli agents mcp <name>              # Paste MCP JSON, update global profile
heretic-cli agents mcp <name> --local      # Paste MCP JSON, update local override
heretic-cli agents mcp <name> --file f.json  # Read MCP JSON from file

Deleting an Agent

heretic-cli agents delete <name> removes an agent and all associated resources:

  1. Stops and removes all running/stopped containers for the agent
  2. Deletes the profile YAML (~/.heretic/agents/<name>.yaml)
  3. Deletes secret scripts (get-<name>-key.sh / .cmd)
  4. Deletes Claude settings (<name>-settings.json)

Use -f / --force to skip the confirmation prompt.

Adding MCP Servers

The agents mcp subcommand lets you paste or import MCP server JSON and merge it into a profile or local override.

# Paste JSON via stdin — paste your JSON, then press Ctrl+D (macOS/Linux) or Ctrl+Z+Enter (Windows)
heretic-cli agents mcp claude

# Read from a file
heretic-cli agents mcp claude --file ~/mcp-servers.json

# Apply to local override instead of global profile
heretic-cli agents mcp claude --local
heretic-cli agents mcp claude --local --file .vscode/mcp.json

Paste Mode

The paste mode reads directly from stdin — no editor required. When done pasting, press Ctrl+D (macOS/Linux) or Ctrl+Z then Enter (Windows) to submit. Use --file to read from a file instead.

Supported JSON Formats

All formats are auto-detected:

// Claude / Copilot CLI format
{ "mcpServers": { "server-name": { "command": "npx", "args": [...] } } }

// VS Code format
{ "servers": { "server-name": { "command": "npx", "args": [...] } } }

// Bare server map
{ "server-name": { "command": "npx", "args": [...] } }

Merge Strategy

Servers are merged by name. New servers with the same name replace existing ones; new names are appended.

When using --local, if no .heretic/cli/<name>.yaml exists yet, one is created with extends: <profile-name>.