CLI command index

Create .donestate/objective.json and .donestate/policy.json starter files.

donestate init [--repo PATH] [--force]

--repo PATH

Repository root; defaults to the current directory.

--force

Replace existing starter files instead of refusing to overwrite them.

Starter files are written with restrictive file permissions.

Run the prose-first local workflow, optionally publish a reviewable branch or pull request, and seal the result for independent verification.

donestate go "GOAL" [--repo PATH] [--accept TEXT] [--publish none|branch|pull_request] [--base REF] [--verification-requirements FILE] [--trusted-verifiers HEX[,HEX...]] [--state-dir PATH]

--repo PATH

Repository root; defaults to the current directory.

--accept TEXT

Override the first acceptance criterion.

--publish MODE

none (default), branch, or pull_request.

--base REF

Base branch/ref used for publication; defaults to main.

--verification-requirements FILE

JSON machine-checkable requirements for v2 independent verification.

--trusted-verifiers HEX[,HEX...]

Comma-separated pinned verifier fingerprints.

--state-dir PATH

State directory; defaults to .donestate/state.

Publication requires a clean starting worktree. push/open_pr authority is granted only when publication is explicitly requested.

Durably create an objective without starting execution.

donestate create --objective FILE --policy FILE [--state-dir PATH]

--objective FILE

Required objective JSON document.

--policy FILE

Required execution-policy JSON document.

--state-dir PATH

State directory; defaults to .donestate/state.

Start a previously created objective that is still in RECEIVED.

donestate start RUN_ID [--state-dir PATH]

--state-dir PATH

State directory; defaults to .donestate/state.

Create and immediately execute an explicit objective under an explicit execution policy.

donestate run --objective FILE --policy FILE [--state-dir PATH]

--objective FILE

Required objective JSON document.

--policy FILE

Required execution-policy JSON document.

--state-dir PATH

State directory; defaults to .donestate/state.

Resume one recoverable local run from durable state rather than starting a duplicate run.

donestate resume RUN_ID [--state-dir PATH]

--state-dir PATH

State directory; defaults to .donestate/state.

Unsettled prior effects become AMBIGUOUS_EFFECT and are not blindly replayed.

Cancel eligible local work without rewriting settled, verification, or ambiguous history.

donestate cancel RUN_ID [--state-dir PATH]

--state-dir PATH

State directory; defaults to .donestate/state.

Delete eligible settled or cancelled local run state.

donestate delete RUN_ID --confirm [--state-dir PATH]

--confirm

Required explicit deletion confirmation.

--state-dir PATH

State directory; defaults to .donestate/state.

Deleting DoneState state does not delete remote Git branches, pull requests, or repository history.

List durable local runs as structured JSON.

donestate list [--state STATE] [--limit N] [--state-dir PATH]

--state STATE

Optional exact DoneState run-state filter.

--limit N

Maximum returned runs, from 1 to 1000; defaults to 100.

--state-dir PATH

State directory; defaults to .donestate/state.

Print the durable run, action records, and current event-chain verification result.

donestate status RUN_ID [--state-dir PATH]

--state-dir PATH

State directory; defaults to .donestate/state.

Create the exact independent-verification handoff for a run.

donestate handoff RUN_ID [--state-dir PATH] [--out FILE]

--state-dir PATH

State directory; defaults to .donestate/state.

--out FILE

Write the handoff JSON to a file instead of stdout.

Published subjects use v2; historical/local-only runs without a publication subject retain the v1 compatibility path.

Validate and record a complete v2 independent-verifier response.

donestate verify-response --file FILE [--state-dir PATH]

--file FILE

Required v2 verification-response JSON document.

--state-dir PATH

State directory; defaults to .donestate/state.

Subject, nonce, digest, signer and replay protections are validated together.

Ask an OpsTruth MCP endpoint to independently verify a sealed published subject and record the returned v2 response.

donestate verify-opstruth RUN_ID --endpoint URL [--state-dir PATH]

--endpoint URL

Required credential-free HTTPS OpsTruth MCP endpoint.

--state-dir PATH

State directory; defaults to .donestate/state.

Record a signed legacy v1 independent-verifier attestation.

donestate attest --file FILE [--state-dir PATH]

--file FILE

Required legacy attestation JSON document.

--state-dir PATH

State directory; defaults to .donestate/state.

Compatibility path for historical v1 runs; new published workflows use the v2 response contract.

Verify the local run's hash-chained event log and exit non-zero when invalid.

donestate verify-log RUN_ID [--state-dir PATH]

--state-dir PATH

State directory; defaults to .donestate/state.

Discover explicitly labelled repair issues plus recent failing-workflow evidence using local GitHub CLI authentication.

donestate maintenance-discover [--repo OWNER/NAME] [--repo-path PATH] [--state-dir PATH]

--repo OWNER/NAME

Optional exact GitHub repository; otherwise inferred from the local checkout.

--repo-path PATH

Local checkout used for GitHub context; defaults to the current directory.

--state-dir PATH

State directory; defaults to .donestate/state.

Only issues labelled donestate:repair are repair-eligible. Failing workflows are evidence only.

List locally recorded bounded maintenance findings.

donestate maintenance-list [--repo OWNER/NAME] [--state-dir PATH]

--repo OWNER/NAME

Optional repository filter.

--state-dir PATH

State directory; defaults to .donestate/state.

Run one repair-eligible labelled issue as a bounded PR-only repair and stop for independent verification.

donestate maintenance-repair FINDING_ID [--repo PATH] [--base REF] [--verification-requirements FILE] [--trusted-verifiers HEX[,HEX...]] [--state-dir PATH]

--repo PATH

Local repository checkout; defaults to the current directory.

--base REF

Base branch/ref; defaults to the repository default branch.

--verification-requirements FILE

JSON verification requirements for the exact published subject.

--trusted-verifiers HEX[,HEX...]

Comma-separated pinned verifier fingerprints.

--state-dir PATH

State directory; defaults to .donestate/state.

Issue text is treated as untrusted problem evidence, not authority. DoneState does not merge its own repair PR.

Return machine-readable capability discovery for both humans and agents.

donestate capabilities

Run a bounded local demonstration that deliberately stops at AWAITING_VERIFICATION.

donestate demo

The demo never self-verifies.