CLI reference

Initialise a Heddle repo beside Git. Adopts the current branch as main.

Snapshot the working tree into the current thread.

Manage threads — 17 subcommands covering creation, navigation, refresh, absorb, promote, drop, approval, and cleanup.

• thread create Start a new task thread
• thread switch Switch the current checkout to an existing thread ref
• thread list List threads in the repository
• thread show Display one thread with actor and workflow context
• thread captures Show granular captures on a thread
• thread rename Rename a thread ref
• thread refresh Rebase the thread onto its target thread
• thread move Move selected captured paths between threads
• 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 Promote a thread to a heavy checkout at a chosen path
• thread drop Drop a thread and mark it abandoned
• thread approve Record a merge approval for source → target (feature-gated: hosted-client)
• thread approvals List approvals recorded for source → target (feature-gated: hosted-client)
• thread revoke-approval Revoke a previously recorded approval by id (feature-gated: hosted-client)
• thread check-merge Check whether source → target would merge under branch-protection policies (read-only, feature-gated)
• thread cleanup Sweep threads that have outlived their usefulness — drop checkouts and registry entries

Fork from any state into a new (or detached) thread for parallel exploration without context loss.

Read the review payload for a state, sign it, walk to the next pending review, and surface signal health.

• review show Render the review payload for a state (defaults to HEAD)
• review sign Submit a review signature on a state (kind: read / agent_preview / agent_co_review)
• review next Walk to the next pending review
• review health Per-module signal health over a rolling window of states

Attach reasoning to files, symbols, and line ranges — re-anchored on every capture so notes survive refactor.

• context set Attach a context annotation to a file, symbol, line range, or state
• context get Show context annotations for a file or state target
• context list List all active context targets
• context history Show full revision history for one logical annotation
• context edit Add a new revision to an existing logical annotation
• context supersede Create a replacement annotation and supersede an older one
• context rm Remove context annotations
• context check Check annotation staleness against current code
• context suggest Suggest low-noise targets that may benefit from context
• context audit Audit stale, superseded, and duplicate context

Symbol-anchored discussions with multi-mode resolution (into-annotation / by-edit / dismiss).

• discuss open Open a new discussion anchored to a (file, symbol)
• discuss append Append a turn to an existing discussion
• discuss resolve Resolve a discussion via --mode (into-annotation | by-edit | dismiss)
• discuss list List discussions filtered by state, symbol, or status
• discuss show Show a single discussion with its turns

Round-trip with Git — init mirror, export states, import history, sync both ways, push/pull a remote.

• bridge git status Show the Heddle ↔ Git bridge state
• bridge git init Initialize the Git mirror at .heddle/git/
• bridge git export Export states to a bare Git repo at --destination
• bridge git import Import local branches and tags from a source repo (--path, --ref)
• bridge git sync Bidirectional sync — export then import
• bridge git push Push to the bridged Git remote (default: origin)
• bridge git pull Pull from the bridged Git remote (default: origin)

Run the agent gRPC daemon over a Unix socket, plus the reservation API for out-of-process orchestration.

• agent serve Start the agent gRPC daemon (Unix socket; requires --foreground)
• agent status Show daemon status (pid, socket, pidfile)
• agent stop Ask the running daemon to drain and exit
• agent reserve Atomically reserve a thread for one writer
• agent heartbeat Update reservation heartbeat
• agent capture Capture under a session-validated reservation
• agent ready Mark a reservation's thread ready for integration
• agent release Release a reservation (status: complete | abandoned)
• agent list List agent reservations (optionally filtered to alive ones)

FUSE mount daemon — surfaces threads as virtual filesystems. Linux + --features mount build only.

• daemon serve Run the mount daemon in the foreground
• daemon status Probe whether the daemon is alive
• daemon stop Request a graceful shutdown

Repository integrity check. Walks the object graph; --bridge also validates the Git overlay; --repair reconstructs from the oplog.

Repository health snapshot, plus dev-build-only drift-checkers. `doctor docs` keeps this docs site in sync with the binary; `doctor schemas` keeps published JSON samples in sync.

• doctor docs Diff-check markdown docs against the real CLI surface — exits non-zero on drift
• doctor schemas Diff-check `docs/json-schemas.md` against the canonical schema registry

Emit shell completion scripts — bash, zsh, fish (no powershell).

Redact sensitive blobs from history. Reads return a stub; the receipt stays.

• redact apply Redact a blob and write a tombstone
• redact list List active redactions in this repo
• redact show Show the tombstone for a redaction
• redact trust add Add an operator public key to [redact] trusted_keys so signed redactions from that key are accepted over the wire
• redact trust list List the currently-trusted operator keys
• redact trust remove Remove an operator public key from the trust list

Physically remove redacted bytes from disk. Irreversible. The hard form of redaction.

• purge apply Harden a redaction into a purge
• purge list List purges performed in this repo