Skip to content

cli.md

Latest commit

 

History

History
140 lines (98 loc) · 5.27 KB

cli.md

File metadata and controls

140 lines (98 loc) · 5.27 KB

CLI Reference

This page is a command lookup for the current Heddle CLI surface.

Main Commands

Chat and one-shot use

  • heddle or heddle chat: start interactive chat mode in the current workspace
  • heddle ask "<goal>": run a single prompt and exit, backed by a one-off saved session

Control plane

  • heddle daemon: start the browser control-plane daemon

Provider auth

  • heddle auth status: show stored provider credentials
  • heddle auth login openai: sign in with an OpenAI ChatGPT/Codex account
  • heddle auth login openai --no-browser: print the authorization URL without opening a browser
  • heddle auth logout openai: remove the stored OpenAI credential

OpenAI account sign-in is experimental and user-selected. It is not official OpenAI support, and Heddle is not affiliated with, endorsed by, or sponsored by OpenAI. Anthropic currently uses API-key auth; Heddle does not support Anthropic consumer subscription OAuth.

Heartbeat and scheduling

  • heddle heartbeat start [--every 30m] [--task "<durable task>"]: create or enable the default heartbeat task and run the foreground scheduler
  • heddle heartbeat task add --id <id> --task "<durable task>" [--every 15m]: create or update a scheduled heartbeat task
  • heddle heartbeat task list: list local heartbeat tasks
  • heddle heartbeat task show <id>: show a task's schedule, last decision, and last run summary
  • heddle heartbeat task enable <id>: enable a heartbeat task
  • heddle heartbeat task disable <id>: disable a heartbeat task
  • heddle heartbeat run --once: run due heartbeat tasks once
  • heddle heartbeat run [--poll 60s]: run the foreground heartbeat scheduler until interrupted
  • heddle heartbeat runs list [--task <id>] [--limit 10]: list saved heartbeat run records
  • heddle heartbeat runs show <run-id|latest> [--task <id>]: show the final agent output for a saved heartbeat run

Project setup

  • heddle init: create a heddle.config.json template in the current project

Common Flags

These flags show up across multiple commands:

  • --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 an available provider API key over a stored OAuth credential for that run

Common Usage Examples

Start chat in the current repo:

heddle

Run a one-shot question:

heddle ask "Summarize the test strategy in this repository"

ask still behaves like a one-shot command from the terminal, but Heddle stores the run as a one-off session under .heddle/ so traces, memory maintenance, and later review use the same persisted conversation path as other session-backed runs.

Run against another workspace:

heddle --cwd /path/to/project

Force OpenAI Platform API-key mode when both OAuth and API-key credentials exist:

heddle --prefer-api-key chat --model gpt-5.4-mini
heddle --prefer-api-key ask "List the top-level build commands"
heddle --prefer-api-key daemon

Start the control plane:

heddle daemon

After the daemon starts, open the browser control plane to inspect sessions, review current Git workspace changes, inspect historical turn evidence, and use the Workspaces section to switch between local projects. For one-off CLI usage against another project, keep using --cwd.

Start the foreground heartbeat scheduler:

heddle heartbeat start --every 30m

Interactive Chat Commands

Inside heddle / heddle chat, the most-used local commands are:

  • /model: show the active model
  • /model set <query>: filter and choose a model interactively
  • /reasoning: show configured and effective reasoning effort
  • /reasoning set <query>: filter and choose reasoning effort interactively
  • /reasoning <low|medium|high>: set reasoning effort directly for the current session
  • /reasoning default: clear explicit reasoning effort for the current session
  • /session list: show recent saved sessions
  • /session choose <query>: filter and choose a saved session
  • /continue: continue the current session
  • /compact: compact older session history

Prompt editing supports Shift+Enter for newlines, Ctrl+Z/Ctrl+Y for undo/redo, and Up/Down for submitted prompt history when the cursor is on the first or last logical line.

Development Commands In This Repository

Inside this repository, common development commands include:

yarn cli:dev
yarn chat:dev
yarn daemon:dev
yarn server:dev
yarn client:dev
yarn build
yarn test
yarn eslint
yarn typecheck

Notes

  • The installed command is heddle.
  • By default, commands operate on the current working directory unless --cwd is provided.
  • Workspace state is local to the project under .heddle/. Saved sessions use .heddle/chat-sessions.catalog.json plus per-session files under .heddle/chat-sessions/. The browser control plane can register and switch between local workspaces, but each workspace keeps its own sessions, traces, memory, and tasks.
  • Heartbeat scheduler commands are local-first; adding a task does not create a background OS service by itself.

See Also