CLI Reference¶

All commands are invoked as heddle COMMAND [OPTIONS]. Commands are grouped by whether they need a running NATS server.

Overview¶

Command	Purpose	NATS Required
`heddle setup`	Interactive configuration wizard	No
`heddle new worker`	Scaffold a new worker config	No
`heddle new pipeline`	Scaffold a new pipeline config	No
`heddle validate`	Validate config files	No
`heddle rag ingest`	Ingest Telegram exports into vector store	No
`heddle rag search`	Semantic search	No
`heddle rag stats`	Vector store statistics	No
`heddle rag serve`	Workshop with RAG dashboard	No
`heddle worker`	LLM worker actor	Yes
`heddle processor`	Non-LLM processor worker	Yes
`heddle pipeline`	Pipeline orchestrator	Yes
`heddle orchestrator`	Dynamic LLM orchestrator	Yes
`heddle scheduler`	Time-driven task scheduler	Yes
`heddle router`	Deterministic task router	Yes
`heddle submit`	Submit a goal	Yes
`heddle mcp`	MCP server gateway	Yes
`heddle workshop`	Worker Workshop web UI	No
`heddle ui`	Terminal dashboard (TUI)	Yes
`heddle mdns`	mDNS service discovery	No
`heddle dead-letter monitor`	Dead-letter queue consumer	Yes

Getting Started Commands (no NATS)¶

heddle setup¶

Interactive wizard that detects your environment and writes a config file.

heddle setup [OPTIONS]

Option	Default	Description
`--config-path`	`~/.heddle/config.yaml`	Config file path
`--non-interactive`	`false`	Skip prompts, use defaults

Steps performed:

Detects Ollama at localhost:11434
Prompts for Anthropic API key (optional)
Checks/pulls the embedding model
Scans for Telegram export files
Writes ~/.heddle/config.yaml

heddle new (group)¶

Scaffold new worker and pipeline configs interactively. YAML is generated from your answers — you don't need to write it from scratch.

heddle new worker¶

heddle new worker [OPTIONS]

Option	Default	Description
`--name`	(prompted)	Worker name (lowercase, underscores)
`--kind`	(prompted)	`llm` or `processor`
`--tier`	(prompted)	`local`, `standard`, or `frontier`
`--configs-dir`	`configs/`	Where to write the config
`--non-interactive`	`false`	Use defaults, skip prompts

Prompts for: name, kind, system prompt (or editor), model tier, input/output field names, timeout. Validates before writing.

heddle new pipeline¶

heddle new pipeline [OPTIONS]

Option	Default	Description
`--name`	(prompted)	Pipeline name
`--configs-dir`	`configs/`	Where to write the config
`--non-interactive`	`false`	Use defaults, skip prompts

Lists available workers, then prompts to add stages in a loop. For each stage: worker type, stage name, input mapping (guided path syntax). Validates the pipeline graph before writing.

heddle validate¶

Validate worker, pipeline, and orchestrator configs without starting any infrastructure. Auto-detects config type from file content.

heddle validate [OPTIONS] [PATHS...]

Option	Default	Description
`--all`	`false`	Validate all configs in `--configs-dir`
`--configs-dir`	`configs/`	Root config directory

Examples:

heddle validate configs/workers/my_worker.yaml       # single file
heddle validate configs/workers/*.yaml               # multiple files
heddle validate --all                                 # everything in configs/

Exit code 0 if all valid, 1 if any errors. Colored output with per-file pass/fail indicators.

heddle rag (group)¶

All RAG subcommands share a set of group-level options.

heddle rag [GROUP-OPTIONS] COMMAND

Group options (inherited by every subcommand):

Option	Default	Description
`--config-path`	`~/.heddle/config.yaml`	Config file path
`--db-path`	(from config)	Override vector store path
`--store`	(from config)	Backend: `duckdb` or `lancedb`
`--ollama-url`	(from config)	Override Ollama URL
`--embedding-model`	(from config)	Override embedding model

heddle rag ingest¶

Ingest Telegram JSON exports into the vector store.

heddle rag ingest [OPTIONS] PATHS...

Option	Default	Description
`--embed / --no-embed`	`--embed`	Generate embeddings via Ollama
`--window-hours`	`6`	Time window size in hours
`--chunk-target`	`400`	Target chunk size in chars
`--chunk-max`	`600`	Maximum chunk size in chars

PATHS accepts one or more directories or result.json files.

heddle rag search¶

Run a semantic similarity search against the vector store.

heddle rag search [OPTIONS] QUERY

Option	Default	Description
`--limit`, `-n`	`10`	Max results
`--min-score`	`0.0`	Minimum similarity score

heddle rag stats¶

Print vector store statistics (row count, embedding dimensions, disk size).

heddle rag stats

No additional options beyond the group options.

heddle rag serve¶

Start the Workshop web UI with the RAG dashboard enabled.

heddle rag serve [OPTIONS]

Option	Default	Description
`--port`	`8080`	Workshop port
`--host`	`127.0.0.1`	Bind address

Infrastructure Commands (NATS required)¶

All infrastructure commands connect to NATS and typically accept --nats-url and --skip-preflight. Most also require a --config YAML file that describes the actor.

heddle worker¶

Start an LLM worker actor.

heddle worker --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	Worker config YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--tier`	`standard`	Model tier: `local`, `standard`, `frontier`
`--skip-preflight`	`false`	Skip connectivity checks

heddle processor¶

Start a non-LLM processor worker (e.g. extractors, validators).

heddle processor --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	Processor config YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--tier`	`local`	Model tier
`--skip-preflight`	`false`	Skip connectivity checks

heddle pipeline¶

Start a pipeline orchestrator that chains workers in sequence.

heddle pipeline --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	Pipeline config YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--skip-preflight`	`false`	Skip connectivity checks

heddle orchestrator¶

Start the dynamic LLM orchestrator (goal decomposition, delegation).

heddle orchestrator --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	Orchestrator config YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--redis-url`	`redis://redis:6379`	Redis URL (state store)
`--skip-preflight`	`false`	Skip connectivity checks

heddle scheduler¶

Start the time-driven task scheduler.

heddle scheduler --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	Scheduler config YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--skip-preflight`	`false`	Skip connectivity checks

heddle router¶

Start the deterministic task router.

heddle router [OPTIONS]

Option	Default	Description
`--config`	`configs/router_rules.yaml`	Router rules YAML
`--nats-url`	`nats://nats:4222`	NATS server URL
`--skip-preflight`	`false`	Skip connectivity checks

heddle submit¶

Submit a goal to the orchestrator for processing.

heddle submit GOAL [OPTIONS]

Option	Default	Description
`--nats-url`	`nats://nats:4222`	NATS server URL
`--context`	(none)	Key=value pairs (repeatable)

Example:

heddle submit "Process document" --context file_ref=test.pdf --context lang=en

UI & Discovery Commands¶

heddle workshop¶

Start the Worker Workshop web UI.

heddle workshop [OPTIONS]

Option	Default	Description
`--port`	`8080`	HTTP port
`--host`	`127.0.0.1`	Bind address
`--configs-dir`	`configs/`	Directory of worker configs
`--db-path`	`~/.heddle/workshop.duckdb`	Workshop database
`--nats-url`	(none)	Optional NATS URL for live status
`--apps-dir`	`~/.heddle/apps`	Custom apps directory

heddle ui¶

Launch the terminal dashboard (TUI) for monitoring actors in real time.

heddle ui [OPTIONS]

Option	Default	Description
`--nats-url`	`nats://localhost:4222`	NATS server URL

heddle mdns¶

Broadcast mDNS service records so other Heddle nodes can discover this machine.

heddle mdns [OPTIONS]

Option	Default	Description
`--workshop-port`	`8080`	Advertised Workshop port
`--nats-port`	`4222`	Advertised NATS port
`--mcp-port`	`0`	Advertised MCP port (0 = disabled)
`--host`	(auto-detect)	Hostname to advertise

heddle mcp¶

Start the MCP (Model Context Protocol) server gateway.

heddle mcp --config PATH [OPTIONS]

Option	Default	Description
`--config`	(required)	MCP config YAML
`--transport`	`stdio`	Transport: `stdio` or `sse`
`--host`	`127.0.0.1`	Bind address (SSE only)
`--port`	`8000`	Port (SSE only)
`--skip-preflight`	`false`	Skip connectivity checks

heddle dead-letter monitor¶

Consume and display messages from the dead-letter queue.

heddle dead-letter monitor [OPTIONS]

Option	Default	Description
`--nats-url`	`nats://nats:4222`	NATS server URL
`--max-size`	`1000`	Max messages to retain in memory

Pre-flight Checks¶

Infrastructure commands (worker, processor, pipeline, orchestrator, scheduler, router, mcp) run three pre-flight checks before starting:

NATS connectivity -- verifies the NATS server is reachable and the JetStream API is available.
Model availability -- for LLM workers, confirms the configured model is loaded in Ollama (or that the API key is set for cloud models).
Stream/subject setup -- ensures the required NATS streams and subjects exist, creating them if necessary.

Pass --skip-preflight to bypass all three checks. Useful in CI or when you know the infrastructure is already running.

Environment Variables¶

Variable	Affects	Description
`OLLAMA_URL`	All commands	Ollama base URL (overrides config)
`OLLAMA_MODEL`	`worker`, `processor`	Default model name
`ANTHROPIC_API_KEY`	`worker`, `orchestrator`	Anthropic API key for cloud models
`FRONTIER_MODEL`	`worker`	Model name for the frontier tier
`OPENAI_API_KEY`	`worker`	OpenAI-compatible API key
`OPENAI_BASE_URL`	`worker`	OpenAI-compatible base URL
`HEDDLE_TRACE`	All infrastructure	Enable trace logging (`1` / `true`)
`HEDDLE_TRACE_CONTENT`	All infrastructure	Include message payloads in traces