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),
    Schemas {
        verb: Vec<String>,
    },
    Start(ThreadStartArgs),
    Try(TryArgs),
    Run(RunArgs),
    Sync(SyncArgs),
    Continue,
    Abort,
    Land(LandArgs),
    Ready(ReadyArgs),
    Capture(SnapshotArgs),
    Commit(CommitArgs),
    Log(LogArgs),
    Timeline(TimelineArgs),
    Show {
        state: Option<String>,
    },
    Retro(RetroArgs),
    Diff(DiffArgs),
    Discuss {
        command: DiscussCommands,
    },
    Query(QueryArgs),
    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,
    },
    Resolve(ResolveArgs),
    Fsck(FsckArgs),
    Oplog {
        command: OplogCommands,
    },
    Import {
        command: ImportCommands,
    },
    Export {
        command: ExportCommands,
    },
    Push(PushArgs),
    Pull(PullArgs),
    Remote {
        command: RemoteCommands,
    },
    Auth {
        command: AuthCommands,
    },
    Whoami {
        server: Option<String>,
    },
    Context {
        command: ContextCommands,
    },
    Integration {
        command: IntegrationCommands,
    },
    Semantic {
        command: SemanticCommands,
    },
    Daemon {
        command: DaemonCommands,
    },
    Agent {
        command: AgentCommands,
    },
    Maintenance {
        command: MaintenanceCommands,
    },
    Clone(CloneArgs),
    Hook {
        command: HookCommands,
    },
}

Variants

Init(InitArgs)

Initialize Heddle in a directory or existing Git checkout.

Adopt(AdoptArgs)

Adopt Git history into Heddle-native source authority.

Git Overlay is the normal existing-Git mode: Git keeps source objects, refs, index, and worktree state while Heddle stores metadata in .heddle. adopt imports history and moves source authority to Heddle.

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.

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-contract/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, fsck repair git, 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)

Integrate a ready thread into its local target.

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)

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)

Commit the current captured state to the authoritative Git checkout.

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 physical state ID, logical change ID, or unambiguous prefix. Defaults to HEAD.

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.

Diff(DiffArgs)

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

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.

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.

Resolve(ResolveArgs)

Resolve merge conflicts.

Fsck(FsckArgs)

Verify repository integrity or explicitly repair one surface.

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

Import

Import from another version control system.

Fields

command: ImportCommands

Export

Export to another version control system.

Fields

command: ExportCommands

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

Auth

Authenticate with a Heddle server.

Fields

command: AuthCommands

Whoami

Report the acting identity (principal, token kind, scopes, operation ceiling, TTL, signing status, server reachability).

Fields

server: Option<String>

Heddle server address (defaults to the configured server).

Context

Manage code context annotations.

Fields

command: ContextCommands

Integration

Manage ambient harness integrations.

Fields

command: IntegrationCommands

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

Clone(CloneArgs)

Clone from remote.

Hook

Manage repository hooks.

Fields

command: HookCommands

Trait Implementations

impl FromArgMatches for Commands

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

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Commands, 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