Getting Started

Installation

There is nothing to install. npx fetches the CLI and runs it:

npx @heddle-run/cli --help

Every heddle on this page can be spelled npx @heddle-run/cli. That is not a shortcut around a missing install step; it is the shape of the thing. heddle is a runtime you point at a document, so it belongs outside your project: no dependency, no lockfile entry, nothing that has to be migrated when heddle changes.

To keep it on the machine rather than fetching it each time, install it globally via npm:

npm install -g @heddle-run/cli

Verify the installation:

heddle --help

heddle requires Node.js 18 or newer.

Set an API key

The scaffolded project uses OpenAI, so export a key before running anything:

export OPENAI_API_KEY=sk-...

Every provider needs a resolvable key, including local ones. See LLM Providers for how to point a flow at Ollama or vLLM instead.

Create your first agent

Scaffold a new project:

heddle init my-agent

This creates:

my-agent/
├── flow.json      # Your workflow definition
└── tools/
    └── example_tool.sh   # A sample tool

The generated flow is a single agent wired between a start and an end node. It takes one input, query, and its system prompt interpolates that value with {{query}}.

Run the workflow

heddle run my-agent/flow.json \
  --tools-dir my-agent/tools \
  --input '{"query": "What is the Open Agent Specification?"}'

--input is a JSON object that becomes the run's starting state. It is not checked against the start node: a key nothing declares is carried anyway, and a declared key you omit is simply absent, so a prompt referencing {{missing}} reaches the model with the placeholder still in it. The final state is printed to stdout as JSON; progress and errors go to stderr.

Add --verbose for per-node logging:

heddle --verbose run my-agent/flow.json --tools-dir my-agent/tools --input '{"query": "hello"}'

Conversations

--session keeps a run in a conversation and hands the agent the turns before it. Each command is one turn:

heddle run my-agent/flow.json --tools-dir my-agent/tools --session my-first --input '{"query": "hello"}'
heddle run my-agent/flow.json --tools-dir my-agent/tools --session my-first --input '{"query": "and again?"}'

Sessions live in ~/.heddle/sessions/. heddle sessions ls lists them and heddle sessions show <id> prints a transcript. Sessions covers the rest: what is on disk, runs that survive a dead process, and runs that stop to wait for a person.

Interactive chat mode

For debugging and exploration, add -i:

heddle run my-agent/flow.json --tools-dir my-agent/tools -i

That conversation lasts as long as the terminal. Add --session <id> to keep it, and reopening with the same id starts on the conversation so far. Type /exit to quit.

Your message is bound to the first output declared on the start node, falling back to query if the start node declares none.

Validate a spec

Check your workflow before running it:

heddle validate my-agent/flow.json --tools-dir my-agent/tools

This validates the spec against the Agent Spec schema, compiles it, checks the graph, and checks that an executable exists for every tool the flow names.

Share it

Once the agent works, hand it to someone as one file: the spec, the tools and their executable bits, everything.

heddle bundle my-agent/flow.json --tools-dir my-agent/tools -o my-agent.heddle

heddle run my-agent.heddle --input '{"query": "hello"}'

The receiver needs heddle and an API key. A spec names its key as $ENV_VAR, resolved on the machine that runs, so credentials never travel. See Bundles.

Where to go next