Enum Commands 

pub enum Commands {
    Init(InitArgs),
    Adopt(AdoptArgs),
    Help {
        topics: Vec<String>,
    },
    Status {
        short: bool,
        watch: bool,
        watch_iterations: Option<usize>,
        watch_interval_ms: Option<u64>,
    },
    Watch(WatchArgs),
    Verify,
    Doctor(DoctorArgs),
    GitOverlay,
    Schemas {
        verb: Vec<String>,
    },
    Start(ThreadStartArgs),
    Try(TryArgs),
    Run(RunArgs),
    Sync(SyncArgs),
    Continue,
    Abort,
    Land(LandArgs),
    Ready(ReadyArgs),
    Capture(SnapshotArgs),
    Commit(CommitArgs),
    Checkpoint(CheckpointArgs),
    Log(LogArgs),
    Timeline(TimelineArgs),
    Show {
        state: Option<String>,
    },
    Retro(RetroArgs),
    Clean {
        force: bool,
        dry_run: bool,
    },
    Diff(DiffArgs),
    Switch(SwitchArgs),
    Discuss {
        command: DiscussCommands,
    },
    Query(QueryArgs),
    Transaction {
        command: TransactionCommands,
    },
    Review {
        command: ReviewCommands,
    },
    Redact {
        command: RedactCommands,
    },
    Visibility {
        command: VisibilityCommands,
    },
    Revert(RevertArgs),
    Undo(UndoArgs),
    Collapse(CollapseArgs),
    Expand(ExpandArgs),
    Thread {
        command: ThreadCommands,
    },
    Shell {
        command: ShellCommands,
    },
    Complete {
        subject: CompletionSubject,
    },
    Merge(MergeArgs),
    Resolve(ResolveArgs),
    Fsck {
        full: bool,
        thorough: bool,
        bridge: bool,
    },
    Oplog {
        command: OplogCommands,
    },
    Fetch {
        remote: Option<String>,
        all: bool,
    },
    Push(PushArgs),
    Pull(PullArgs),
    Remote {
        command: RemoteCommands,
    },
    Context {
        command: ContextCommands,
    },
    Integration {
        command: IntegrationCommands,
    },
    Stash {
        command: StashCommands,
    },
    Bridge {
        command: BridgeCommands,
    },
    Semantic {
        command: SemanticCommands,
    },
    Daemon {
        command: DaemonCommands,
    },
    Agent {
        command: AgentCommands,
    },
    Maintenance {
        command: MaintenanceCommands,
    },
    CherryPick {
        commit: String,
        message: Option<String>,
        no_commit: bool,
        force: bool,
    },
    Clone(CloneArgs),
    Rebase {
        thread: Option<String>,
        abort: bool,
        cont: bool,
        force: bool,
    },
    Hook {
        command: HookCommands,
    },
    Actor {
        command: ActorCommands,
    },
    Session {
        command: SessionCommands,
    },
}

Variants

Init(InitArgs)

Initialize a new Heddle repository.

Adopt(AdoptArgs)

Convert Git history into Heddle-native storage.

Git-overlay repos normally keep Git commits in .git and Heddle metadata in .heddle. Use adopt only when you explicitly want a Git-backed checkout converted into native Heddle storage.

Help

Curated, progressive-disclosure help.

heddle help prints the curated everyday verbs and points at heddle help advanced for everything else. heddle help <topic> prints the topic page (e.g. daemon, signals, bridge). heddle help <command path> falls through to that command’s --help so the printer never duplicates clap’s per-verb derivation.

Fields

topics: Vec<String>

Topic name (advanced, daemon, signals, …) 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.

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.

GitOverlay

Show the low-friction Git-overlay workflow.

Schemas

Print the JSON Schema for a --output json-emitting verb.

Contract-table introspection over CLI output shapes — useful when wiring tools that consume heddle <verb> --output json and want to validate or generate types. The schemas live in crates/cli/src/cli/commands/schemas.rs; the command contract table registers available and documented schema verbs for heddle doctor schemas drift detection against docs/json-schemas.md.

With no <verb>, prints the registered schema verbs. <verb> is the joined subcommand path — e.g. status, log, bridge git status, marker list.

Fields

verb: Vec<String>

The verb whose schema to emit. Run heddle schemas --help or look at docs/json-schemas.md for the registered list.

trailing_var_arg = true lets the verb spec carry literal --flag tokens (e.g. heddle schemas log --reflog, heddle schemas marker delete --prefix) without clap parsing them as options on schemas itself.

Start(ThreadStartArgs)

Create or resume an isolated thread for focused work.

Try(TryArgs)

Run a command in a sandboxed ephemeral thread.

Heddle creates a fresh thread with an isolated checkout, runs <cmd> inside it, and then either captures the result on a zero exit or drops the thread on a non-zero exit. The parent thread’s working tree is never touched — the ephemeral thread is the sandbox. Implements item 3.1 from the heddle 6→8 plan.

try is the new-sandbox sibling to run. Reach for run when you already have a thread and just want to exec a command inside its checkout (no thread creation, no capture, no rollback).

Run(RunArgs)

Automation/workflow command: run a command inside an existing thread’s execution root.

run is the existing-thread sibling to try. It looks up the named (or current) thread, sets the child’s cwd to that thread’s checkout, exports HEDDLE_THREAD_*, and runs <cmd>. It does NOT create a thread, capture state on success, or roll back on failure — those are try’s job. Reach for try when you want the sandbox lifecycle; reach for run when you already have a thread and just need to exec inside it.

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)

Land a ready thread and optionally publish it.

land is the local integration verb: capture outstanding work if needed, refresh against the target when safe, land the thread, write the Git checkpoint, and optionally push. 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)

Prepare this thread for review or merge.

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.

Commit(CommitArgs)

Save current work as one Heddle change, plus a Git checkpoint in Git-overlay repos.

Checkpoint(CheckpointArgs)

Commit the current captured work to the Git-overlay branch/index.

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).

Timeline(TimelineArgs)

Navigate, fork, reset, and recover agent tool-call timelines.

Show

Show state details.

Fields

state: Option<String>

State by change ID or hash prefix. Defaults to HEAD when omitted.

Retro(RetroArgs)

Summarize a working session.

Combines oplog, agent registry, marker, and context-annotation reads into one structured payload — agent-readable retro of captures, signals, and notable events since --since. Replaces the reconstruct-from-heddle log boilerplate.

Clean

Remove untracked files from worktree.

Fields

force: bool

Actually remove files (required for safety).

dry_run: bool

Only show what would be removed.

Diff(DiffArgs)

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

Switch(SwitchArgs)

Git-compatible alias for heddle thread switch.

Discuss

Open or resolve discussions anchored to symbols.

Open a discussion against a symbol; append turns; resolve by edit or dismiss. Anchors travel across renames and cross-file moves on subsequent state mutations.

Fields

command: DiscussCommands

Query(QueryArgs)

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

Transaction

Transactional multi-step edits. Begin, commit, abort, status. Operations within don’t produce intermediate states.

Hidden in alpha: buffered-op replay at commit and rewind-on-abort are still follow-on work; the verb stays available for testing but is not advertised in heddle help advanced.

Fields

command: TransactionCommands

Review

Review a state — render the payload, sign, see signal health.

heddle review show renders the review payload (summary, agent narrative, in-budget signals, anchored discussions). heddle review sign submits a read / agent_preview / agent_co_review signature on the state. heddle review health reports per-module signal fire rates over a rolling window.

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 purge afterward physically removes the bytes. Both are signed, attributed, oplog-audited operations. See docs/PRINCIPLES.md (the honesty principle) for context.

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 tier; list enumerates non-public states. Capture binds the inherited [review.discussion] default_visibility automatically (Invariant A) — these verbs are the explicit operator overrides.

Fields

command: VisibilityCommands

Revert(RevertArgs)

Revert changes from a state.

Undo(UndoArgs)

Undo the last Heddle operation.

Collapse(CollapseArgs)

Collapse (squash) multiple states into one.

Expand(ExpandArgs)

Expand a squashed land into the captures it collapsed.

Thread

Manage threads.

Fields

command: ThreadCommands

Shell

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

Fields

command: ShellCommands

Complete

Internal shell-completion candidate helper.

Fields

subject: CompletionSubject

Candidate set to print, one candidate per line.

Merge(MergeArgs)

Advanced/manual merge primitive. Prefer heddle land for managed threads.

Resolve(ResolveArgs)

Resolve merge conflicts.

Fsck

Verify repository integrity.

Fields

full: bool

Full check (includes content verification).

thorough: bool

Run slower graph and signature integrity checks.

bridge: bool

Include Git-overlay mirror, mapping, notes, and checkout checks.

Oplog

Inspect and repair the operation log.

heddle oplog recover explicitly salvages a truncated or torn oplog, reporting what was recovered — the operator-facing entrypoint over the same recovery the everyday read path runs automatically.

Fields

command: OplogCommands

Fetch

Download objects and refs from remote.

In Git-overlay mode this fetches branches and refs/notes/heddle, not Git tags.

Fields

remote: Option<String>

Remote name or URL.

all: bool

Fetch from all remotes.

Push(PushArgs)

Push to a remote repository.

In Git-overlay mode, push writes plain Git refs the remote’s users can inspect with git ls-remote: each Heddle thread’s state goes to refs/heads/<thread>, Heddle metadata (state identity carried as Git notes) goes to refs/notes/heddle, and with --all-threads Git tags go to refs/tags/<tag>. JSON output lists the refs actually written this invocation in refs_written.

Pull(PullArgs)

Pull from a remote repository.

Remote

Manage remote repositories.

Fields

command: RemoteCommands

Context

Manage code context annotations.

Fields

command: ContextCommands

Integration

Manage ambient harness integrations.

Fields

command: IntegrationCommands

Stash

Manage stashed changes.

Fields

command: StashCommands

Bridge

Bridge to other version control systems.

Fields

command: BridgeCommands

Semantic

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

Fields

command: SemanticCommands

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

Agent

Agent control surface — daemon lifecycle and reservation API.

heddle agent serve|status|stop controls the local gRPC daemon (Unix socket inside the repo). heddle agent reserve|capture|ready|release|list|heartbeat is the stable JSON contract orchestrators use to coordinate parallel writers. Distinct from heddle daemon (FUSE mount control plane) — different subsystem.

Fields

command: AgentCommands

Maintenance

Inspect and refresh rebuildable performance sidecars.

Fields

command: MaintenanceCommands

CherryPick

Apply specific commits.

Fields

commit: String

Commit to cherry-pick.

message: Option<String>

Commit message for the cherry-pick.

no_commit: bool

Apply changes to worktree without committing.

force: bool

Discard uncommitted local changes instead of refusing.

Clone(CloneArgs)

Clone from remote.

Rebase

Rebase current thread onto another.

Fields

thread: Option<String>

Thread to rebase onto.

abort: bool

Abort an in-progress rebase.

cont: bool

Continue an in-progress rebase after resolving conflicts.

force: bool

Discard uncommitted local changes instead of refusing.

Hook

Manage repository hooks.

Fields

command: HookCommands

Actor

Advanced debugging/provenance commands for Heddle actors attached to threads.

Fields

command: ActorCommands

Session

Advanced debugging/provenance commands for Heddle execution sessions.

Fields

command: SessionCommands

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