CLI

One binary serves the local UI and drives the same server-side workflow executor the canvas uses.

threadle [server-options]
threadle run <file|recipe|template|graphId> [run-options]
threadle jobs|status [--all]
threadle attach <jobId>
threadle logs [jobId] [--follow]
threadle stop <jobId>
threadle services|health
threadle providers | agents | sessions | graphs | models | nodes | templates | recipes
threadle --list-templates
threadle help | -h | --help

Invocation	Effect
`threadle`	Start the API + UI on `127.0.0.1`
`threadle serve`	Same as bare `threadle` — the command name is optional
`threadle run <target>`	Import or load a graph and execute it (foreground, in-process)
`threadle run <target> --detach`	Start on the running server; print `jobId` and exit
`threadle jobs`	List recent jobs (all statuses)
`threadle status`	List running jobs (`--all` = history)
`threadle attach <jobId>`	Follow a job’s logs until it ends (same as `logs -f`)
`threadle logs [jobId]`	Print logs (`--follow` / `-f` until the job ends)
`threadle stop <jobId>`	Cancel a running job
`threadle services` / `health`	Server process + provider availability
`threadle providers`	Provider adapters only
`threadle agents`	Agents discovered for `--dir` / cwd
`threadle sessions`	Sessions (`-q`, `--provider`, `--limit`)
`threadle graphs` / `workflows`	Saved graphs
`threadle models`	Models returned by `/api/models`
`threadle nodes`	Installed custom nodes
`threadle templates`	Bundled teaching examples
`threadle recipes`	Job recipes (`examples/recipes`)
`threadle --list-templates`	Same as `templates`
`threadle help` / `--help`	Print help and exit

Unknown commands exit 2. Override the server base with THREADLE_URL (default http://127.0.0.1:<port> from --port).

Most inventory commands require a running server (threadle --no-open). templates and recipes work offline from the bundled / repo catalogs.

Server mode

Flag	Default	Meaning
`--port <n>`	`4570`	TCP port — the host is always `127.0.0.1`
`--no-open`	off	Don’t open a browser tab
`--dir <path>`	cwd	Project directory highlighted for agents and discovery
`-h`, `--help`		Show help

threadle --port 4600 --no-open

Keep this process up for UI ▶ / ≫, run --detach, and every job / inventory command below. Startup also begins the read-only filesystem watchers over Claude Code, opencode, and Cursor storage. SIGINT / SIGTERM shut down managed helper processes and exit 0.

Jobs

Same registry as the Runs view and UI server runs.

Command	Effect
`threadle jobs`	Recent jobs — running, done, failed, cancelled
`threadle status`	Running only; pass `--all` for the same history `jobs` shows
`threadle attach <jobId>`	Follow that job’s logs until it ends
`threadle logs [jobId] [-f]`	One job’s log, or recent lines across jobs; `-f` = attach
`threadle stop <jobId>`	Cancel a running job

threadle run knot-concat --detach
threadle attach job_….…
threadle jobs
threadle stop job_….…

Inventory

Read-only probes against the live server (except templates / recipes, which use the local catalogs when the server is down).

Command	Effect	Useful flags
`threadle services` / `health`	Health, process info, and every provider’s availability	—
`threadle providers`	Provider adapters only	—
`threadle agents`	Agents discovered for a project	`--dir <path>`
`threadle sessions`	Recent sessions	`-q` / `--query`, `--provider`, `--limit`, `--dir`
`threadle graphs` / `workflows`	Graphs under `~/.config/threadle/graphs/`	—
`threadle models`	Models from `/api/models`	—
`threadle nodes`	Custom nodes under `~/.config/threadle/nodes/`	—
`threadle templates`	Bundled teaching examples	also `--list-templates`
`threadle recipes`	Job recipes (`examples/recipes`)	offline

threadle services
threadle agents --dir .
threadle sessions -q auth --provider cursor --limit 20
threadle graphs
threadle models
threadle nodes
threadle templates
threadle recipes

`threadle run`

Same executor as UI server jobs: prompts, converters, custom nodes, agents, sessions, iterators, knots, tripwires, frames, mute/bypass, retry, error policy, and {{param:…}} substitution. Results are written back into the graph under ~/.config/threadle/graphs/.

Target resolution

<target> is resolved in this order — the first match wins.

#	Kind	Matched when
1	Recipe id	A job recipe (`repo-brief`, `diff-review-panel`, …) — `threadle recipes`
2	Template id	A bundled teaching example (`hello-wire`, `plan-implement-review`, …)
3	Portable graph file	The path exists as a file; parsed as `threadle/graph@1` and imported
4	Example / recipe path	`examples/recipes/<target>[.json]` or `examples/workflows/<target>[.json]` relative to cwd
5	Saved graph id	A graph with that id exists under `~/.config/threadle/graphs/`

Options

Flag	Meaning
`--param <name>=<value>`	Fill `{{param:name}}`. Repeatable. Name must match `[a-zA-Z0-9_-]{1,64}`; value capped at 100 000 characters
`--approve-all`	Auto-pass approval gates, live handoffs, and tripwire parks
`--dir <path>`	Project directory for agent CLI runs (default: cwd)
`--detach`	`POST /api/run/workflow` on the running server; print `jobId`; exit. Requires `threadle` already listening
`--keep`	Keep an imported graph after a foreground run (default for files/templates)
`--ephemeral`	Delete the imported graph after a foreground run (`--keep` wins; refused with `--detach`)

Foreground vs `--detach`

Mode	Behavior	Appears in Runs / `threadle jobs`?
Foreground `threadle run`	Blocks the terminal; streams logs to stdout	No (unless you later open the kept graph)
`threadle run --detach`	Hands the job to the live server and exits	Yes — same registry as UI ▶ / ≫

# terminal A
threadle --no-open

# terminal B — several workflows in parallel
threadle run detached-delay --detach
threadle run knot-concat --detach
threadle jobs
threadle attach <jobId>
threadle logs <jobId> --follow

What server / detached runs cannot do

The executor preflights the graph and refuses before any agent work happens.

Situation	Behavior
Approval gate / live handoff	Needs `--approve-all` / UI approve-all, otherwise refused
Context node with no payload	Always blocks — cannot distill mid-run. Materialize in the Library first, or mute
Payload hash present but blob deleted	`detached run blocked — context "<label>" payload is missing`
Agent node with no model	Blocks — pick a model in the inspector
Required input not wired	Blocks — see Loose ends
Cycle in the graph	`cycle detected — workflow can never finish`

Muted and bypassed nodes are exempt — muting is the escape hatch for a node you don’t want in this run.

Output and exit behavior

Foreground log lines are prefixed by lane — a space for node output, · for meta, ! for stderr. Banner lines bracket the run:

❯ running "Starter workflow" (a1b2c3d4) [imported]
✓ done — 2 output node(s) updated
· graph kept as a1b2c3d4 — open with: threadle

Exit code	Meaning
`0`	Workflow finished (or detach accepted)
`1`	Execution / server error
`2`	Usage error — missing target, bad `--param`, unknown command

Worked example

threadle recipes
threadle run repo-brief --dir ~/code/unfamiliar-project --approve-all

threadle --list-templates
threadle run plan-implement-review \
  --param task="Add a regression test for the login race" \
  --approve-all --dir .

# or background it on a running server
threadle run plan-implement-review \
  --param task="Add a regression test for the login race" \
  --approve-all --detach
threadle jobs
threadle services

Recipes — job graphs with contracts
Examples — teaching templates
Run — canvas ▶ / ≫ / partial
Detached runs — close the browser, reopen later
Examples — what each template teaches
Files & config — where graphs, payloads and logs live
Troubleshooting — when a run refuses to start
Providers — what services / providers report