CLI Reference

Global options

These are declared on heddle itself and may appear before or after the subcommand:

There is currently no --version flag. Use heddle --help to confirm the CLI is installed.

heddle run

Execute an Agent Spec flow.

heddle run <flow> [options]

Arguments

Options

--no-stream is decided before the request goes out, not as a fallback. Use it for an endpoint that cannot serve SSE or that bills streamed calls differently. Note that an agent carrying a post transform does not stream regardless, since a token that has reached a client cannot be recalled once the transform rejects the answer.

A spec writing api_key: $OPENAI_API_KEY reads that variable at its first model call. On a terminal, run asks for the ones this shell does not have before the run starts rather than failing several nodes in — hidden as you type, kept in this process only, and skipped with enter. Nothing is asked without a terminal on stdin and stderr, so scripts and CI are unaffected; --no-ask-env declines the question on a terminal as well. See API keys.

--mount and --workspace are not on that list. A workspace exists on every run and --safe decides only whether anything enforces its edges, so where a run's files come from is a separate question from what confines them. Both are checked before the run starts: a source that is not there, a destination that climbs out of the workspace, a symbolic link anywhere in the tree, or two mounts landing on the same path is an error at second zero rather than at whichever node reaches it first.

Examples

# Basic run
heddle run flow.yaml --tools-dir ./tools

# With input data
heddle run flow.json --tools-dir ./tools --input '{"query": "quantum computing"}'

# One turn of a conversation kept on disk
heddle run flow.yaml --tools-dir ./tools --session support-42 --input '{"query": "hello"}'

# Interactive chat, kept in the same conversation
heddle run flow.yaml --tools-dir ./tools --session support-42 -i

# Verbose logging
heddle --verbose run flow.yaml --tools-dir ./tools

# Confine tools to an OS sandbox
heddle run flow.yaml --tools-dir ./tools --safe

# Sandboxed, offline, with one writable output directory
heddle run flow.yaml --tools-dir ./tools --safe --deny-net --allow-write ./out

Output

The final state is printed to stdout as formatted JSON, unless --protocol is given, which replaces it with a frame stream. Progress, tool activity, and errors go to stderr, so stdout stays pipeable:

heddle run flow.json --input '{"query": "hello"}' | jq .result

--input becomes the run's starting state as given. It is not checked against the start node's declared outputs: malformed JSON fails immediately, but a key nothing declares is carried and is readable, since an agent is sent its whole input state as JSON and {{key}} substitution reads whatever the state holds. A declared key you omit is simply absent, and a prompt referencing it keeps the placeholder.

Rendering the run in another protocol

--protocol <name> hands the run's events to an encoder and writes its frames to stdout, one JSON object per line. The human progress output is replaced, not merely redirected: the encoder is the only thing rendering the run.

heddle run examples/ag-ui/flow.json --plugin ./examples/ag-ui/encoder.json \
  --protocol ag-ui --input '{"query": "hello"}'

{"data":{"type":"RUN_STARTED","threadId":"5d4ed795-…","runId":"5d4ed795-…"}}
{"data":{"type":"STEP_STARTED","stepName":"start"}}
{"data":{"type":"STEP_FINISHED","stepName":"start"}}
{"data":{"type":"STATE_SNAPSHOT","snapshot":{"query":"hello"}}}
{"data":{"type":"STEP_STARTED","stepName":"end"}}
{"data":{"type":"STEP_FINISHED","stepName":"end"}}
{"data":{"type":"STATE_SNAPSHOT","snapshot":{"query":"hello"}}}
{"data":{"type":"RUN_FINISHED","threadId":"5d4ed795-…","runId":"5d4ed795-…"}}

JSON Lines rather than the server's event:/data: framing, because SSE is how an HTTP response body carries a name beside a payload and stdout is not one. The name is not lost: each line is the frame, so event is present when the protocol names its frames and absent when it carries the type inside data. --protocol heddle shows the named half, heddle's own frames, with no plugin loaded at all:

{"event":"flow_start","data":{"type":"flow_start"}}
{"event":"node_start","data":{"type":"node_start","nodeName":"start","nodeType":"StartNode","attempt":1,"state":{"query":"hello"}}}

The final state is not appended. With a protocol selected stdout is the frame stream, and a pretty-printed object after it is a parse error for anything reading a line at a time. Nothing is lost either: flow_complete carries the whole run state, so an encoder that wants the answer already has it.

A protocol nothing provides is an error listing what is available; the encoder for one comes from --plugin, and a plugin may not claim the name heddle.

Sessions

Covered in full in Sessions; the flags in brief. --session keeps a run in a conversation and gives the agent the turns before it. Each invocation is one turn:

heddle run flow.yaml --session support-42 --input '{"query":"where is my order?"}'
heddle run flow.yaml --session support-42 --input '{"query":"and the second one?"}'

A session is a directory: meta.json, a turns.jsonl appended to once per turn, and a checkpoint.json present only while a run is unfinished. Ids are random unless you name one; on the CLI a name you chose is fine, because the store is your own home directory. (The server issues its own; see Server.)

Passing _chat_history yourself alongside --session is refused: the session is the conversation, and heddle would have to pick one of the two to throw away.

Durable runs

--durable writes the run down at every node boundary. A process that dies mid-run leaves a checkpoint, and --resume picks it up at the node it had reached. Nothing before that node runs again.

heddle run flow.yaml --session support-42 --durable --input '{"query":"…"}'
# … the process dies …
heddle run flow.yaml --session support-42 --resume

It costs one store write per node, which is why it is asked for rather than implied by --session.

Stopping for a human

A middleware may suspend a run at a tool call or a node. The run stops, the question is written into the session, and the process can exit:

Stopped for a human: "ApprovalGate" is asking.
{ "tool": "refund", "arguments": { "amount": 4200 }, "question": "Approve refund?" }

--resume --answer '<json>' continues it. The answer reaches the run as the result of the call that was waiting, and nothing that already ran runs again: not the model call for that round, not the tools already called in it. Calls the round never reached are made on the way back.

A suspension needs a session to be written into; a run without one is refused rather than stopped with no way back.

Interactive chat

-i opens the terminal chat UI. Alone, the conversation lasts as long as the terminal; with --session it is kept, and reopening with the same id starts on the conversation so far.

Your message is bound to the first output declared on the flow's start node, falling back to query if it declares none. Type /exit or /quit to leave.

heddle bundle

Pack a flow and everything it runs with into one shareable .heddle archive. This is the flag reference; Bundles covers the format, what deliberately does not travel, and how to treat a bundle you received.

heddle bundle <flow> [options]

heddle bundle spec.yaml --tools-dir tools --plugin plugin.json \
  --mount skills --input '{"query":"hello"}' -o agent.heddle

Whoever receives the file needs nothing else:

heddle run agent.heddle

Options

What a bundle is

A .heddle is a gzipped tar with a heddle.json manifest at its root, so tar -tzf agent.heddle shows exactly what you were handed, no heddle required. The bundle is checked before it is written: the spec must parse, the graph must hold, and every tool the flow names must be carried by --tools-dir or a --plugin, so a bundle that packs is a bundle that runs.

At run time the bundle proposes and the command line disposes: --input overrides the recorded default, a --plugin-config for the same component type wins, and extra --mount or --plugin flags compose with the bundle's. heddle validate agent.heddle inspects one without running it.

What a bundle deliberately does not carry:

• Credentials. A spec references a key as $ENV_VAR; it resolves on the machine that runs, never the one that packed.
• Sandbox policy and session state. --safe and --session are the operator's decisions about their own machine, and a file that arrived in the mail does not make them.
• Discovery grants. A bundled plugin declaring discoverTools still needs --discover-tools from whoever runs it.

An in-process plugin (an importable module rather than a .json manifest) is refused: what it imports lives on the author's machine, so a bundle cannot carry its closure. Give the plugin a manifest and bundle that.

heddle doctor

Ask whether this machine has what a bundle needs, without running it.

heddle doctor <bundle-or-flow> [options]

$ heddle doctor local-notetaker.heddle
local-notetaker cannot run here — 2 requirements unmet:

  ✗ whisper-cli      not on PATH     brew install whisper-cpp
  ✗ OPENAI_API_KEY   not set         for the notes step

  ✓ ffmpeg, node v22.17.0

Everything missing is listed at once, with whatever the author wrote beside it, so a machine is fixed in one pass rather than one failure at a time. Exit status is 0 when every requirement holds and 1 when any does not, which is what makes it usable in CI — a workflow that packs a bundle can assert its runner can run one.

Options

This runs nothing and installs nothing — see requirements for why that is the whole design rather than a missing feature. heddle run performs the same check before it starts; on a terminal it pauses there — for the few requirements heddle has its own install recipe for (whisper-cli, ffmpeg, the whisper models) it offers to run the fix after showing it, and the rest you fix in another shell and press enter to re-check — and anywhere else it fails with the same list. heddle doctor is how you ask before the meeting rather than during it.

An environment variable is reported as set or not set. Its value is never printed.

heddle sessions

Inspect the conversations heddle has kept.

heddle sessions ls [--limit <n>]     # most recently used first
heddle sessions show <id> [--json]   # the transcript, or the stored record
heddle sessions rm <id>              # delete it and everything in it

All three take --session-dir <path>. A session with an unfinished run is listed as unfinished, and show says what it is waiting for.

heddle validate

Validate an Agent Spec component.

heddle validate <spec> [options]

Arguments

Options

What it checks

1. Schema validation against the Open Agent Specification
2. Graph compilation and structural validation, for flows
3. That every tool the flow names resolves, against the composed registry, so this runs when --tools-dir is given or when a loaded plugin contributes tools

No API key is needed. Providers are constructed on first use, so compiling a flow, and therefore validating it, never reaches a credential. A spec whose llm_config names $OPENAI_API_KEY validates with nothing in the environment.

A .json argument to --plugin is read as a manifest, which is data: validating a flow that uses an out-of-process plugin starts none of that plugin's code.

heddle init

Scaffold a new project.

heddle init <project-name>

Creates a project directory containing a template flow.json and a sample tool in tools/. Existing files at those paths are overwritten.