Reference / CLI Reference

CLI Reference

The installed command is heddle. By default, commands operate on the current working directory unless you pass --cwd.

Main commands

heddle                       # Start interactive terminal chat
heddle chat                  # Start interactive terminal chat
heddle ask "<goal>"          # Run a one-shot prompt and save it as a session
heddle daemon                # Start the local browser control plane
heddle init                  # Create a local .heddle/config.json template

Common flags

--cwd <path>

Run against another workspace path.

--model <name>

Choose the active model.

--max-steps <n>

Limit the agent loop length.

--prefer-api-key

Prefer provider API keys over stored OpenAI OAuth credentials.

Provider auth

heddle auth status
heddle auth login openai
heddle auth login openai --no-browser
heddle auth logout openai

Memory commands

heddle memory status
heddle memory init
heddle memory list [path]
heddle memory read <path> [--offset n] [--max-lines n]
heddle memory search <query> [--path path] [--max-results n]
heddle memory validate [--repair]
heddle memory maintain [--dry-run] [--reconcile]

Heartbeat commands

heddle heartbeat start [--every 30m] [--task "<task>"] [--poll 60s] [--once]
heddle heartbeat task add --id <id> --task "<task>" [--every 15m]
heddle heartbeat task list
heddle heartbeat task show <id>
heddle heartbeat task enable <id>
heddle heartbeat task disable <id>
heddle heartbeat run [--task <id>]
heddle heartbeat runs list [--task <id>] [--limit 10]
heddle heartbeat runs show <run-id|latest> [--task <id>]

Heartbeat commands attach to a live control-plane server or start an embedded server so terminal and browser clients use the same task and run-record shapes.

Interactive chat commands

/help
/model
/model list
/model set <query>
/model <name>
/reasoning
/reasoning set <query>
/reasoning <low|medium|high>
/reasoning default
/auth
/session list
/session choose <query>
/session new [name]
/session switch <id>
/session continue <id>
/session rename <name>
/session pin
/session unpin
/session close <id>
/continue
/compact
/drift
/drift on
/drift off
!<command>

Workspace state

Heddle keeps workspace-local state under .heddle/. Saved sessions use .heddle/chat-sessions.catalog.json plus per-session files under .heddle/chat-sessions/. Session names, pin state, archive state, model choice, and reasoning effort stay with the saved session. The browser control plane can register and switch between local workspaces, but each workspace keeps its own sessions, traces, memory, and tasks.