CLI reference

Show what needs attention and the next safe Heddle action. Observe-only and safe in any directory.

Show what changed in the worktree, a thread, or two states.

Commit the current captured state to the authoritative Git checkout. Git Overlay only; runs no Git hooks.

Capture a recoverable Heddle step for undo, provenance, and review. No staging area, no path filter.

Create or resume an isolated thread for focused work. The checkout it makes has no .git of its own.

Prepare this thread for review or merge. Never lands, checkpoints, or pushes.

Integrate a ready thread into its local target. Fails closed on conflicts.

Push the source-authoritative history to a remote. Exit 75 is retryable; 76 is not.

Pull source-authoritative history from a remote, including context and discussions.

Clone from a Heddle remote.

Show state history. Aliased as heddle history.

Show state details for one state, defaulting to HEAD.

Initialize Heddle in a directory or existing Git checkout. Additive: it never modifies .git.

Adopt Git history into Heddle-native source authority. One-way.

Undo the last Heddle operation. Thread-local, and refuses to rewrite the worktree without --hard.

Resolve merge conflicts, then finish with heddle continue or heddle abort.

Verify this workspace; exits nonzero until every check is clean.

Manage threads: twenty subcommands covering creation, navigation, refresh, absorb, promote, drop, approval, markers, and cleanup.

• 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

Review a state — render the payload, sign it, walk to the next pending review, and see signal health.

• review show Render the review payload for a state
• review sign Submit a review signature on a state (kind: read / agent-preview / agent-co-review)
• review next Walk to the next pending review when review selection is configured
• review health Per-module signal health over a rolling window

Attach reasoning to files, symbols, and line ranges, with on-demand staleness detection. Not projected into Git.

• context set Attach a context annotation to a file, symbol, line range, or state
• context get Show context annotations for a 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
• context reason git Mine Git-agent transcripts and attach reasoning as context annotations

Symbol-anchored discussions. Six subcommands; resolution is by-edit or 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 (by-edit | dismiss)
• discuss reopen Reopen a resolved discussion
• discuss list List discussions filtered by state, symbol, or status
• discuss show Show a single discussion with its turns

Write a complete bare Git repository containing every reachable Heddle state as a Git commit, with branches and tags mirroring threads and markers.

Import Git commits to Heddle. Walks local branches and tags by default.

Bidirectional sync with Git: export followed by import.

Agent reservation and one-shot orchestration API — the writer-lease protocol for parallel writers. Entirely local.

• agent reserve Atomically reserve a thread for one writer; returns a lease_id and a bearer token
• agent heartbeat Update reservation heartbeat
• agent capture Capture under a token-authenticated writer lease
• 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)
• agent task Manage local agent task assignments: create, list, show, update
• agent fanout Plan and start native fan-out lanes: plan, start
• agent presence Inspect attribution and work context: list, show, explain, complete
• agent provenance Record provider/model/policy provenance: begin, segment, end, list, show

FUSE mount-daemon control plane, distinct from agent. Needs a --features mount build on Linux (FUSE), macOS (FSKit), or Windows (ProjFS).

• daemon serve Run a foreground mount daemon for this repository
• daemon status Report daemon liveness, version, uptime, and active mount count
• daemon stop Ask the running daemon to drain its mounts and exit

Explain repository health, plus always-shipped drift-checkers for markdown docs and JSON schemas.

• doctor docs Diff-check markdown documentation against the actual CLI surface; exits non-zero on drift
• doctor schemas Drift-check docs/json-schemas.md against the registered schemas

Verify repository integrity, or explicitly repair one surface. --git covers the Git projection; repair is a subcommand.

• fsck repair git Reconcile Git projection metadata or one projected ref

Redact a sensitive blob so reads return a stub. The tombstone stays; the bytes stay until you purge them.

• 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 whose signed redactions this replica accepts 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 bytes for an existing redaction. Irreversible, and gated by its own independent trust list.

• redact purge apply Physically remove the blob bytes referenced by an existing redaction. Requires --force, and a signing key authorized by [purge].trusted_keys
• redact purge list List every Purge oplog entry
• redact purge trust Manage the independent list of keys authorized to destroy bytes: add, list, remove. Redaction trust does not imply purge trust

Generate a shell completion script on stdout. Lives under heddle shell, with shell init and shell prompt.