HEDDLE

CLI reference

heddle thread

Shipped
heddle thread [OPTIONS] <COMMAND>

Manage threads, the unit of work in Heddle. Threads collapse captures, retries, aborts, conflicts, and merges into one reviewable, recoverable record.

Output text (default)

A thread is the smallest unit of agent work that makes sense to review. It carries a name (e.g. task/biscuit-authz), an assigned agent, a delegator, an ordered list of captures, and, at the end, an integration.

Twenty subcommands sit under thread. The navigation trio is thread current (print the current thread name, read-only), thread cd (print a thread's on-disk path, read-only) and thread switch (attach the checkout to an existing thread ref). Note that thread switch takes a thread, not an arbitrary state — there is no top-level heddle switch, and ADR 0046 rules out adding one.

Markers live here too, under thread marker (list, create, delete, show): a marker is an immutable named reference to a state, where a thread is a mutable one. thread marker delete is the one destructive command in the CLI with no --force gate.

A thread is current when its base is the tip of its target and stale once the target has advanced past it. thread refresh replays it onto its target; heddle land will refresh-then-merge for you when the replay is clean, and fails closed when manual resolution is required.

See also

Subcommands

The thread family covers everything from starting a thread to cleaning one up. Each subcommand has its own page in v2; for now they're listed here with their one-line summaries.

  • thread create Create a thread ref at the current state
  • thread current Print the name of the current thread. Read-only
  • thread switch Switch the current checkout to an existing thread ref
  • thread cd Print the on-disk path for a thread. Read-only
  • thread list List threads
  • thread show Show one thread with actor and workflow context
  • thread captures Show granular captures on a thread
  • thread rename Rename a thread ref
  • thread refresh Refresh a thread onto its target thread
  • thread move Move selected captured paths from one thread into another
  • thread absorb Absorb a child thread into its parent or another thread
  • thread resolve Guide a blocked or stale thread toward its next clean state
  • thread promote Materialize an existing thread ref at a chosen path
  • thread drop Drop a thread and mark it abandoned
  • thread approve Record a merge approval for source → target
  • thread approvals List approvals recorded for source → target
  • thread revoke-approval Revoke a previously recorded approval by id
  • thread check-merge Check whether source → target would merge under the repo's branch-protection policies. Read-only
  • thread cleanup Sweep merged, stale auto-created, or abandoned threads
  • thread marker Manage named state markers: list, create, delete, show. A marker is an immutable named reference to a state