Enum Commands 

pub enum Commands {
    Init(InitArgs),
    Import(ImportArgs),
    Help {
        all: bool,
        topics: Vec<String>,
    },
    Status {
        short: bool,
        watch: bool,
        watch_iterations: Option<usize>,
        watch_interval_ms: Option<u64>,
    },
    Watch(WatchArgs),
    Verify {
        provenance: bool,
    },
    Doctor(DoctorArgs),
    Start(ThreadStartArgs),
    Sync(SyncArgs),
    Continue,
    Abort,
    Land(LandArgs),
    Ready(ReadyArgs),
    Capture(SnapshotArgs),
    Log(LogArgs),
    Show {
        state: Option<String>,
    },
    Diff(DiffArgs),
    Blame(BlameArgs),
    Discuss(DiscussArgs),
    Query(QueryArgs),
    Review {
        command: ReviewCommands,
    },
    Redact {
        command: RedactCommands,
    },
    Visibility {
        command: VisibilityCommands,
    },
    Env {
        command: EnvCommands,
    },
    Revert(RevertArgs),
    Undo(UndoArgs),
    Thread {
        command: ThreadCommands,
    },
    Shell {
        command: ShellCommands,
    },
    Completions {
        shell: Option<String>,
    },
    Complete {
        subject: CompletionSubject,
    },
    Resolve(ResolveArgs),
    Push(PushArgs),
    Pull(PullArgs),
    Remote {
        command: RemoteCommands,
    },
    Context {
        for_thread: Option<String>,
        command: Option<ContextCommands>,
    },
    Integration {
        command: IntegrationCommands,
    },
    Daemon {
        command: DaemonCommands,
    },
    Netd {
        command: NetdCommands,
    },
    Agent {
        command: AgentCommands,
    },
    Maintenance {
        command: MaintenanceCommands,
    },
    Clone(CloneArgs),
    Hook {
        command: HookCommands,
    },
}

Variants

Init(InitArgs)

Initialize Heddle in a directory or existing Git checkout.

Import(ImportArgs)

Bring an existing Git repository into Heddle.

Help

Curated, progressive-disclosure help.

heddle help prints the task map. heddle help --all prints the full command tree. heddle help <topic> prints the topic page (e.g. model, advanced, git-concepts). heddle help <command path> falls through to that command’s --help.

Fields

all: bool

Print the full command tree instead of the task map.

topics: Vec<String>

Topic name (model, advanced, git-concepts, …) or command path. When omitted, prints the curated default.

Status

Show what needs attention and the next safe Heddle action.

Fields

short: bool

Short format.

watch: bool

Continuously refresh status.

watch_iterations: Option<usize>

Internal helper for tests: stop after N watch updates.

watch_interval_ms: Option<u64>

Internal helper for tests: polling interval in milliseconds.

Watch(WatchArgs)

Stream live oplog activity.

Tails the repository’s append-only oplog file like tail -f, emitting snapshots, merges, and thread events as they happen. Exits on Ctrl-C.

Verify

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

Fields

provenance: bool

Verify each state’s offline authorship and review-signature chain.

Doctor(DoctorArgs)

Explain repository health, or run targeted doctor checks.

heddle doctor (no subcommand) reports repository health and the next recovery step. heddle doctor docs diff-checks markdown documentation against the actual CLI surface and exits non-zero on drift — wire it into CI to stop docs from going stale.

Start(ThreadStartArgs)

Create or resume an isolated thread for focused work.

Sync(SyncArgs)

Automation/workflow command: refresh the current thread onto its target when safe.

Continue

Continue the active operation without remembering the specific subcommand.

Abort

Abort the active operation without remembering the specific subcommand.

Land(LandArgs)

Integrate into the local target thread; push to publish.

land is the local integration verb: capture outstanding work if needed, refresh against the target when safe, and land the thread. It fails closed when conflicts or other blockers exist. Pair it with ready when you want the verdict and next action before landing anything.

Ready(ReadyArgs)

Check this checkout before local integration.

ready captures outstanding work if needed, checks conflicts, blockers, freshness, and semantic risk, then marks the thread ready or blocked and prints the next action. It never lands, checkpoints, or pushes; use it when you want Heddle’s verdict before integrating the work.

Capture(SnapshotArgs)

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

Log(LogArgs)

Show state history.

By default, when a thread name is given (e.g. heddle log master), the walk is first-parent only — equivalent to git log --first-parent <branch>. To see every ancestor reachable through merge commits, pass --graph (which renders the full DAG) or --all (which lists every state regardless of ancestry).

Show

Show state details.

Fields

state: Option<String>

State by physical state ID, logical change ID, or unambiguous prefix. Defaults to HEAD.

Diff(DiffArgs)

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

Blame(BlameArgs)

Show line-by-line attribution for a tracked file.

Names the state that last changed each line, with the same structured principal / agent shape as log and show. heddle query --attribution <path> remains as the equivalent query form.

Discuss(DiscussArgs)

Open or resolve discussions anchored to code.

Subcommands: new, reply, resolve, reopen, list, show, wait. --path / --symbol / --line are the code anchor; --state is the historical revision; --body / --file is the markdown body.

Native Heddle only. Discussions live in .heddle and travel over heddle push / heddle pull to a Heddle remote. They are not projected into Git, so git clone does not carry them; in Git Overlay mode they are local to that working copy.

Query(QueryArgs)

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

Review

Review and approve an exact hosted Thread comparison.

show, approve, and list default to the current Thread. readiness checks the exact source and target comparison before hosted landing. Remote selection is explicit, then the configured default, and fails when neither is available.

Fields

command: ReviewCommands

Redact

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

heddle redact apply declares a redaction; the blob bytes stay on disk and reads return the operator-supplied stub. heddle redact purge afterward physically removes the bytes. Both are signed, attributed, oplog-audited operations. See docs/PRINCIPLES.md (the honesty principle) for context.

Redaction is path/blob hide inside history. It is not heddle env (runtime secrets; literal .env capture is reserved, exit 65) and not heddle visibility (per-state audience, downward-closed).

Fields

command: RedactCommands

Visibility

Declare and inspect a state’s audience visibility tier.

heddle visibility set binds a tier to a state; promote lifts it to a less-restrictive tier via a superseding record; show reports the effective declared tier; list enumerates non-public sidecar records in this store. Capture binds the inherited [review.discussion] default_visibility automatically (Invariant A) — these verbs are the explicit operator overrides.

Private is per-state and downward-closed: a public descendant that still names private-ancestor blobs is withheld from lesser audiences. It does not hide one path inside a later public tip. Runtime secrets belong in heddle env (literal .env capture is reserved, exit 65); path-level hide of bytes already in history is heddle redact. See heddle help visibility.

Fields

command: VisibilityCommands

Env

Run a child with a confidential runtime profile.

heddle env run --profile <name> -- <cmd> asks the local policy broker to unwrap named slots and injects them into the child environment only. Values never land in the worktree, the store, or command JSON. Same-UID callers are cooperative; OS isolation is later.

Literal .env / .env.local files are reserved (capture exits 65). heddle visibility does not replace this for secrets beside a public tip; heddle redact stubs a blob already in history.

Fields

command: EnvCommands

Revert(RevertArgs)

Revert changes from a state.

Undo(UndoArgs)

Undo the last Heddle operation.

Thread

Manage threads.

Fields

command: ThreadCommands

Shell

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

Fields

command: ShellCommands

Completions

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

With no shell, prints install lines. With bash, zsh, or fish, emits the same script as heddle shell completion.

Fields

shell: Option<String>

Shell to generate completion for: bash, zsh, or fish.

Complete

Internal shell-completion candidate helper.

Fields

subject: CompletionSubject

Candidate set to print, one candidate per line.

Resolve(ResolveArgs)

Resolve merge conflicts.

Push(PushArgs)

Push the source-authoritative history to a remote.

Pull(PullArgs)

Pull source-authoritative history from a remote.

Remote

Manage remote repositories.

Fields

command: RemoteCommands

Context

Manage code context annotations.

Native Heddle only. Annotations live in .heddle, and travel over heddle push / heddle pull to a Heddle remote. They are deliberately not projected into Git — not into refs/notes/*, not into a tracked file — so git push and git clone do not carry them. In Git Overlay mode annotations still work and are still useful; they are simply local to that working copy.

Fields

for_thread: Option<String>

Show a bounded pre-turn briefing for a Thread.

command: Option<ContextCommands>

Integration

Manage ambient harness integrations.

Fields

command: IntegrationCommands

Daemon

FUSE mount-daemon control plane — distinct from agent.

heddle daemon serve runs a foreground mount daemon that owns FUSE sessions for --workspace virtualized --daemon threads. It is normally spawned on demand by the per-thread CLI; running it interactively is for debugging. status reports liveness/uptime/mount count without spawning; stop asks a running daemon to drain mounts and exit.

Fields

command: DaemonCommands

Netd

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

heddle netd serve runs a long-lived async daemon that binds the machine’s single persistent Iroh endpoint on the persisted device node id and keeps it relay-reachable, so outstanding claim links keep resolving across restarts. Hosted verbs (whoami, push, pull, clone) reuse that endpoint’s warm weft session when netd is running. Unlike daemon, it is not gated on Linux/FUSE and never idle-exits. status reports liveness and the advertised node id; stop asks a running daemon to close its endpoint and exit.

Fields

command: NetdCommands

Agent

Agent reservation and one-shot orchestration API.

heddle agent reserve|capture|ready|release|list|heartbeat is the stable JSON contract orchestrators use to coordinate parallel writers. heddle daemon remains the distinct FUSE mount control plane.

Fields

command: AgentCommands

Maintenance

Inspect and refresh rebuildable performance sidecars.

Fields

command: MaintenanceCommands

Clone(CloneArgs)

Download an existing repository into a local directory.

Hook

Manage repository hooks.

Fields

command: HookCommands

Trait Implementations

impl FromArgMatches for Commands

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for Commands

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand