Skip to content

cli.md

Latest commit

 

History

History
261 lines (197 loc) · 12.2 KB

cli.md

File metadata and controls

261 lines (197 loc) · 12.2 KB
Raw

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>"] [--poll 60s] [--concurrency 2] [--once]: create or update a task and keep the server-backed scheduler running, or run once with --once
  • 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 [--task <id>] [--concurrency 2]: ask the control-plane server to run due heartbeat tasks with bounded concurrency, or one task when --task is provided
  • 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 local .heddle/config.json template in the current project

Evaluation harness

  • heddle eval agent [--cases-dir <path>] [--case <id>] [--output <path>] [--dry-run]: run JSON-defined agent eval cases
  • heddle eval clean [--results-dir <path>] [--before <datetime>] [--yes]: prune generated eval result directories

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.

Pass a multiline prompt without shell quoting:

heddle ask --prompt-file implementation-request.md
heddle ask --prompt-file - < implementation-request.md

--prompt-file - is the explicit stdin mode. Heddle never reads stdin merely because it is piped, so an accidentally inherited or open stdin stream cannot make an otherwise normal invocation hang. A positional prompt and --prompt-file are mutually exclusive.

For a supervisor process, request the versioned JSON Lines protocol:

heddle ask --prompt-file - --output jsonl < implementation-request.md

In jsonl mode, stdout contains only one JSON object per line. Diagnostics and runtime attachment notices go to stderr. Every record includes schemaVersion: 1, a type, and terminal. The current record types are:

  • run.accepted, containing the exact workspace, session, and run IDs;
  • run.activity, containing the shared control-plane activity and its ordered sequence number;
  • run.stream.reconnecting, reporting bounded transport recovery;
  • exactly one terminal run.result, run.cancelled, run.error, run.stream.error, or command.error record.

run.result includes the final outcome and summary, the persisted trace path, and changed-file paths when the run trace contains edit or Git-diff evidence. Heddle intentionally does not label every dirty workspace file as created by the run: if a tool did not record per-run evidence, inspect the workspace diff after completion instead of treating a shared working-tree snapshot as attribution.

The process exits with status 0 only when the terminal run result has outcome: "done". Rejected input, a busy target session, cancellation, stream failure, provider failure, and other non-done outcomes exit nonzero. A scriptable invocation does not enter the interactive prompt queue: when a selected reusable session is already running or queued, it fails admission so the supervisor never loses the exact run identity it must observe.

Approval policy is unchanged. run.activity records can show an approval wait, but JSONL mode does not silently auto-approve it. Configure a suitable host permission policy before launching, or let another attached TUI/web/API client resolve the approval for that session.

Choose the smallest integration surface that fits the host:

  • use heddle ask --output jsonl for a zero-code subprocess integration;
  • use the conversation SDK for an in-process TypeScript host that needs typed callbacks and lifecycle composition;
  • use the control-plane API for a remote or multi-client product integration.

For a Codex-supervised implementation workflow, let Codex plan or review the task, invoke heddle ask --output jsonl for the Heddle-owned implementation step, and keep consuming records until the single terminal record arrives. Treat a zero process exit as completed work, then review the reported trace, changed-file evidence, and the repository diff before committing. A nonzero exit is not a completed implementation even if earlier activity records showed useful progress.

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

Use a local or OpenAI-compatible model:

ollama list
heddle --model ollama/llama3.2:latest ask "Summarize this repository"
heddle --model lmstudio/local-model ask "Summarize this repository"

Ollama models do not require a hosted provider API key. Start Ollama locally, then select an installed chat model with the ollama/ prefix.

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 supported browser UI is web-v2. For one-off CLI usage against another project, keep using --cwd.

Start the server-backed heartbeat scheduler:

heddle heartbeat start --every 30m --concurrency 2

Run due heartbeat tasks once:

heddle heartbeat run --concurrency 2

Interactive Chat Commands

heddle and heddle chat start the API-backed terminal UI.

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
  • /session new [name]: create and switch to a new session
  • /session switch <id>: switch to another saved session
  • /session continue <id>: switch to a session and resume it immediately
  • /session rename <name>: rename the current session
  • /session pin: keep the current session grouped above normal recent sessions
  • /session unpin: return the current session to normal recent ordering
  • /session close <id>: remove a saved session
  • /continue: continue the current session
  • /compact: compact older session history
  • /skills: list discovered Agent Skills and activation status for this workspace
  • /skills enable <name>: enable one Agent Skill for future turns in this workspace
  • /skills disable <name>: disable one active Agent Skill for future turns in this workspace
  • /browser: show Browser Automation status for this workspace
  • /browser enable: enable built-in Browser Automation guidance and browser tools for future default turns in this workspace
  • /browser disable: disable built-in Browser Automation guidance and browser tools for future default turns in this workspace
  • /browser headed: run future Browser Automation sessions in a visible browser window
  • /browser headless: run future Browser Automation sessions without a visible browser window
  • /browser profile <id>: select the Heddle-owned browser profile future browser runs should use
  • /browser backend <playwright|native-chrome>: select the browser backend future browser runs should use
  • /browser endpoint <url>: set the local native Chrome CDP endpoint, for example http://127.0.0.1:9223
  • /browser launch-native [url]: launch locally installed Chrome with the selected Heddle-owned profile and a CDP endpoint; omit the URL to open Wikipedia as a meaningful smoke target
  • /browser check-native: check whether the configured native Chrome CDP endpoint is reachable
  • /browser channel <chromium|chrome|msedge>: select the Playwright browser channel future browser runs and manual profile windows should use
  • /browser open-profile [url]: open the selected Heddle-owned browser profile in a visible window for manual login or session management
  • /browser close-profile: close the selected manual browser profile window and release its profile lock

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.

When the terminal UI is running, Heddle sends desktop notifications for active session approval waits and run completion. Delivery uses the operating system notification bridge through the terminal process, uses Warp's terminal-native notification escape sequence when running inside Warp, falls back to the native macOS notification bridge for non-Warp macOS terminals, requests sound for non-info notifications, and also sends a terminal attention signal for terminal apps that support bell-based notifications. Approval policy and run state still come from the shared control-plane session events. Banner and sound presentation still depend on the operating system and terminal app notification settings for the sender application.

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 task state is local-first, but heartbeat command execution is control-plane backed. Task and run commands attach to a live server or start an embedded server so terminal and browser clients use the same heartbeat API and run-record shapes.

See Also