CLI reference

Show what needs attention and the next safe Heddle action

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

Capture a recoverable Heddle step for undo, provenance, and review

Create or resume an isolated thread for focused work

Check this checkout before local integration

Integrate into the local target thread; push to publish

Push the source-authoritative history to a remote

Pull source-authoritative history from a remote

Download an existing repository into a local directory

Show state history

Show state details

Initialize Heddle in a directory or existing Git checkout

Import a Git checkout on this computer

Undo the last Heddle operation

Resolve merge conflicts

Verify this workspace; exits nonzero until every check is clean

Manage threads

• thread create Create a thread ref at the current state
• thread current Print the name of the current thread (the thread the working checkout is attached to). Read-only — no state change. Useful in shell pipelines: `cd "$(heddle thread cd "$(heddle thread current)")"`
• thread switch Switch the current checkout to an existing thread ref
• thread cd Print the on-disk path for a thread. Read-only — no state change, no auto-capture. Without a shell hook: cd "$(heddle thread cd X)" With `heddle shell init`, `heddle thread cd X` becomes `cd <path>`
• 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 ownership Inspect or explicitly transfer a Thread's native ownership
• thread ownership status Show the local owner or the complete signed conflict
• thread ownership claim Explicitly transfer a local-key Thread to the currently authorized account
• thread ownership resolve Original local owner chooses one accepted claim; the current account accepts
• thread checkout Create a working checkout for this thread
• thread drop Drop a thread and mark it abandoned
• thread cleanup Sweep merged, stale auto-created, or abandoned threads
• thread collapse Collapse (squash) multiple states into one
• thread expand Expand a squashed land into the captures it collapsed
• thread marker Manage named state markers under the thread namespace
• thread marker list List markers, optionally filtered by name prefix
• thread marker create Create marker at current state
• thread marker delete Delete marker(s)
• thread marker show Show marker details

Review and approve an exact hosted Thread comparison

• review show Show the exact source and target comparison for a Thread
• review approve Approve the exact source and target comparison shown for this thread, using your configured signing identity.
• review list List signed review decisions for a Thread
• review revoke Revoke one of your signed approvals
• review readiness Check whether a Thread's exact comparison is ready to land into a target
• review sign Submit a low-level review signature on a state
• review next Walk to the next pending review when review selection is configured
• review health Per-module signal health over a rolling window

Manage code context annotations

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

Open or resolve discussions anchored to code

• discuss new Open a new discussion
• discuss reply Reply to an existing discussion
• discuss resolve Resolve a discussion
• discuss reopen Reopen a resolved discussion
• discuss list List repository discussions
• discuss show Show one discussion and its causal heads
• discuss wait Replay hosted discussion events after the local watermark, then go live

Export Heddle states to Git

Import Git commits to Heddle without changing source authority

Bidirectional sync with Git (export + import)

Agent reservation and one-shot orchestration API

• agent reserve Atomically reserve a thread for one writer
• 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
• agent task create Create a local agent task assignment
• agent task list List local agent task assignments
• agent task show Show one local agent task assignment
• agent task update Update one local agent task assignment
• agent fanout Plan and start native fan-out lanes
• agent fanout plan Preview fan-out lane setup and return commands without writing
• agent fanout start Create task assignments and materialized child lanes
• agent provenance Record provider, model, and policy provenance across an agent run
• agent provenance begin Begin a provider/model provenance session
• agent provenance segment Record a provider, model, or policy change within the current session
• agent provenance end End the current or selected provenance session
• agent provenance show Show the current or selected provenance session
• agent provenance list List provenance sessions
• agent presence Inspect attribution and work context for local agents
• agent presence list List agent presence records known to this repository
• agent presence show Show the current or selected agent presence record
• agent presence explain Explain why Heddle attached the current or selected presence record
• agent presence complete Mark the current or selected presence record complete
• agent timeline Navigate, fork, reset, and recover agent tool-call timelines
• agent timeline status Show the current timeline cursor, counts, and recovery status
• agent timeline record-start Record the start of a native tool timeline step
• agent timeline record-finish Record the finish of a native tool timeline step
• agent timeline fork Fork a timeline branch from a step or native harness tool call
• agent timeline reset Reset the logical timeline cursor, optionally materializing checkout files
• agent timeline recover Recover a pending timeline materialization after an interrupted reset/seek

FUSE mount-daemon control plane — distinct from `agent`

• daemon serve Run a foreground mount daemon for this repository
• daemon status Report daemon liveness, version, uptime, and active mount count. No-op success when the daemon isn't running
• daemon stop Ask the running daemon to drain its mounts and exit. Sweeps any leftover registry entries with `fusermount -u` as a safety net before returning

Explain repository health, or run targeted doctor checks

• doctor docs Diff-check markdown documentation against the actual CLI surface

Verify repository integrity or explicitly repair one surface

• maintenance fsck repair Repair an integrity surface, then verify it
• maintenance fsck repair git Reconcile Git projection metadata or one projected ref

Redact a sensitive blob in a state so reads return a stub instead of the content

• redact apply Declare a redaction on a blob in a state. The blob bytes stay on disk; reads return the stub. Use `heddle redact purge` afterward to physically remove the bytes
• redact list List every active redaction in the repo
• redact show Show a single redaction by its content-addressed id
• redact purge Physically remove bytes for an existing redaction
• redact purge apply Physically remove the blob bytes referenced by an existing redaction. Refuses if no redaction declared the blob first
• redact purge list List every `Purge` oplog entry — who removed bytes, when, and which redaction the purge acted on

Physically remove bytes for an existing redaction

• redact purge apply Physically remove the blob bytes referenced by an existing redaction. Refuses if no redaction declared the blob first
• redact purge list List every `Purge` oplog entry — who removed bytes, when, and which redaction the purge acted on

Print a tab-completion script for bash, zsh, or fish

Generate a shell completion script on stdout

Bring an existing Git repository into Heddle.

• import local Import a Git checkout on this computer
• import url Have the server import a public HTTPS Git URL
• import status Watch a durable import operation until it reaches a terminal state
• import retry Retry a failed durable import operation

Curated, progressive-disclosure help

Stream live oplog activity

Refresh the current thread onto its target when safe

• sync git Bidirectional sync with Git (export + import)

Continue the active operation without remembering the specific subcommand

Abort the active operation without remembering the specific subcommand

Show line-by-line attribution for a tracked file

Structured query over the operation log. Filter by actor, time window, signal kind, symbol, thread, verbs. Returns structured results consumable by agents

Declare and inspect a state's audience visibility tier

• visibility set Declare a visibility tier on a state. Public is the default and stays record-free (absence ≡ public); a non-public tier writes a per-state sidecar record and an oplog audit entry
• visibility promote Promote a state to a less-restrictive tier by appending a superseding record. Requires an existing visibility record to supersede
• visibility show Show a state's effective visibility tier
• visibility list List every state that carries a non-public visibility tier

Run a child with a confidential runtime profile

• env create Create a runtime profile from current environment values
• env list List runtime profiles and slot names. Never prints values
• env run Run a child with profile slots injected as environment variables

Revert changes from a state

Shell integration helpers (auto-cd on thread start/switch/cd)

• shell init Emit a shell wrapper function on stdout. Source it from your shell rc to make `heddle start`, `heddle thread switch`, and `heddle thread cd` auto-`cd` into the target thread's worktree
• shell completion Generate a shell completion script on stdout
• shell prompt Print a compact prompt segment: current thread, dirty marker, and remote divergence. Intended for PS1 helpers

Internal shell-completion candidate helper

Explicit interoperability with other version-control formats

• bridge git Explicit Git projection operations
• bridge git import Import Git commits to Heddle without changing source authority
• bridge git export Export Heddle states to Git

Manage remote repositories

• remote list List configured remotes
• remote add Add a remote
• remote remove Remove a remote
• remote set-default Set the default Heddle remote for pull and push
• remote show Show remote details

Authenticate with a Heddle server

• auth login Authenticate with a Heddle server
• auth logout Remove stored credentials for a server
• auth status Show current authentication status
• auth invite Create or list signup invites owned by the signed-in account
• auth invite list List signup invites owned by the signed-in account
• auth trust Inspect or explicitly replace the deployment descriptor root pin
• auth trust show Show the descriptor root pin controlling a server connection
• auth trust replace Atomically replace an automatic descriptor root pin
• auth derive-agent Derive a scoped, short-lived agent token offline. Advanced: not a first-screen noun
• auth create-service-token Create a service token for CI/scripts with explicit native capabilities. Advanced: not a first-screen noun

Create or list signup invites (thin alias of `auth invite`)

• invite list List signup invites owned by the signed-in account

Grant a principal access to a hosted spool

• grant create Grant a principal a role on a hosted spool
• grant list List grants on a hosted spool
• grant delete Remove a grant by its stable record ID shown by `heddle grant list`

Promote a personal hosted spool to a root-level spool

Offer this agent account for a human to claim

Report the capture actor, then hosted auth

Manage ambient harness integrations

• integration list List Heddle-managed harness integrations
• integration install Install harness integrations
• integration doctor Verify installed harness integrations
• integration uninstall Uninstall harness integrations
• integration upgrade Rewrite Heddle-managed integrations in place
• integration relay Internal relay invoked by installed hooks/plugins
• integration stamp Fast identity-cursor write. Prefer the argv fast path in `main`

Semantic analysis queries (call-graph hot-spots, churn, signature-stability surfaces)

• semantic diff Compare the symbols stored in two states' attached semantic indexes
• semantic hot Aggregate semantic-change events across recent history and surface the files or functions with the most activity
• semantic refs Query persisted refs-of, callers-of, or importers-of at a state
• semantic index Backfill the content-addressed merkle semantic index over history

Box-scoped network daemon control plane — distinct from `daemon` (FUSE mounts)

• netd serve Run the foreground network daemon: bind the persistent device endpoint, keep relays online, hold warm weft sessions for hosted CLI verbs, and serve same-uid control RPCs. Never idle-exits
• netd status Report network-daemon liveness and the advertised device node id. No-op success when the daemon isn't running
• netd stop Ask the running network daemon to close its endpoint and exit

Inspect and refresh rebuildable performance sidecars

• maintenance fsck Verify repository integrity or explicitly repair one surface
• maintenance fsck repair Repair an integrity surface, then verify it
• maintenance fsck repair git Reconcile Git projection metadata or one projected ref
• maintenance inspect Inspect repository performance sidecars and repo shape
• maintenance refresh Refresh repository performance sidecars without changing repository meaning
• maintenance repack Repack native objects now through the resource-controlled scheduler
• maintenance gc Garbage collect unreachable objects
• maintenance oplog Inspect and repair the operation log
• maintenance oplog recover Salvage a truncated or torn operation log and report what was recovered

Manage repository hooks

• hook list List installed hooks
• hook install Install a hook
• hook uninstall Uninstall a hook
• hook events Show the hook event catalog (W2/A15)