Skip to content

cli.md

Latest commit

 

History

History
148 lines (105 loc) · 5.86 KB

cli.md

File metadata and controls

148 lines (105 loc) · 5.86 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 chat-v1: start the legacy terminal UI fallback
  • 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, manage local workspaces, inspect memory status, and use the heartbeat task workbench. The default browser UI is web-v2; the legacy v1 UI is available only when you explicitly serve v1 assets, for example with yarn client:build:v1 and heddle daemon --assets-dir dist/src/web in a repository checkout. For one-off CLI usage against another project, keep using --cwd.

Start the foreground heartbeat scheduler:

heddle heartbeat start --every 30m

Interactive Chat Commands

heddle and heddle chat start the API-backed terminal UI. The legacy terminal UI remains available as an explicit fallback through heddle chat-v1.

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 chat:dev:v1
yarn daemon:dev
yarn daemon:dev:v1
yarn server:dev
yarn client:dev
yarn client:dev:v1
yarn build
yarn client:build:v1
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. The browser control plane can operate the same local tasks and run records, including create/edit/run/resume/delete flows.

See Also