CLI reference
heddle capture
Shippedheddle capture --intent "<text>" [--confidence <0..1>] [--force] Snapshot the working tree into a new state on the current thread. The atomic unit of work; cheap by design; capture often.
A capture takes the entire working tree, hashes the content, and appends a new state to the current thread. The state's identifier is content-addressed — two captures with identical content produce the same state ID.
Captures are cheap and disposable by default. The thread collapses the messy middle (retries, conflicts, etc.) at merge time, so there's no reason to wait for a 'clean' state before capturing.
Actor identity (provider, model, session, segment, policy) is read at capture time from HEDDLE_AGENT_PROVIDER, HEDDLE_AGENT_MODEL, HEDDLE_SESSION_ID, HEDDLE_SESSION_SEGMENT, HEDDLE_AGENT_POLICY. Principal identity comes from HEDDLE_PRINCIPAL_NAME and HEDDLE_PRINCIPAL_EMAIL. Each can be overridden with a CLI flag below. Precedence is: CLI flag > thread-declared actor > env var > session config > user config > repo config.
Flags
--intent <text>, -m <text>- Natural-language intent for this recoverable step. Becomes the row text in `heddle thread show`.
--confidence <number>- Honest confidence estimate, 0.0–1.0.
--force, -f- Allow a large or deletion-heavy capture without the safety preflight.
--agent-provider <text>- Override `HEDDLE_AGENT_PROVIDER` for this capture.
--agent-model <text>- Override `HEDDLE_AGENT_MODEL` for this capture.
--agent-session <text>- Override `HEDDLE_SESSION_ID` for this capture.
--agent-segment <text>- Override `HEDDLE_SESSION_SEGMENT` for this capture.
--policy <text>- Override `HEDDLE_AGENT_POLICY` for this capture.
--no-policy- Omit policy attribution from this capture.
--no-agent- Omit agent attribution from this capture (treat as a human capture).
--split- Split selected paths into another thread instead of capturing the whole worktree. Pairs with `--into` and one or more `--path`.
--into <thread>- Target thread when using `--split`.
--path <PATH>- Repository-relative path prefix to include when using `--split`. Repeatable.
Examples
A typical capture
bash$ heddle capture --intent "wire datalog scope rules"Captured state hd-9a2f (b3a8e201)Confidence: 0.85Split selected paths into another thread
bash$ heddle capture --split --into task/biscuit-authz.shim --path src/auth/jwt.rs --path src/auth/compat.rsCaptured state hd-9c41 (e201b3a8)