attest
Sign attestation artifacts -- actions, decisions, approvals, handoffs, endorsements, receipts.
treeship attest action
Record that an actor performed an action.
treeship attest action \
--actor agent://researcher \
--action openai.chat.completion \
--meta '{"model":"gpt-4o","tokens":1247,"prompt_hash":"sha256:abc..."}'Options
| Option | Description |
|---|---|
--actor <uri> | Who performed the action (required) |
--action <label> | What action occurred (required) |
--parent <id> | Parent artifact ID for chain linking |
--approval-nonce <nonce> | Nonce from an existing approval |
--input-digest <sha256:hex> | SHA-256 digest of the input consumed |
--output-digest <sha256:hex> | SHA-256 digest of the output produced |
--content-uri <uri> | URI to referenced content |
--meta <json> | Arbitrary JSON metadata |
--out <path> | Write raw DSSE envelope to file (use - for stdout) |
Use --input-digest to attest that an action occurred on specific content without revealing the content itself. The digest proves which data was processed. The content never enters the artifact.
Privacy-preserving attestation
treeship attest action \
--actor agent://clinical-ai \
--action clinical.note.summarize \
--input-digest sha256:e3b0c44298fc1c149afb4c8996fb924 \
--content-uri ehr://patient/94821/note/2026-03-26treeship attest decision
Record an LLM inference decision with model, token usage, and confidence metadata.
treeship attest decision \
--actor agent://analyst \
--model claude-opus-4 \
--tokens-in 8432 \
--tokens-out 1247 \
--summary "Contract analysis complete." \
--confidence 0.91Options
| Option | Description |
|---|---|
--actor <uri> | Who made the decision (required) |
--model <name> | Model identifier, e.g. claude-opus-4, gpt-4o |
--tokens-in <n> | Input token count |
--tokens-out <n> | Output token count |
--prompt-digest <sha256:hex> | SHA-256 digest of the prompt |
--summary <text> | Plain-text summary of the decision |
--confidence <0-1> | Confidence score between 0 and 1 |
--parent <id> | Parent artifact ID for chain linking |
Decision attestations are designed for LLM audit trails. They record which model was used, how many tokens were consumed, and what the model concluded, without storing the prompt or response content.
treeship attest approval
Record that an approver authorized an intent. A random nonce is generated automatically.
treeship attest approval \
--approver human://alice \
--description "approve stripe charge max $500 to acme" \
--expires 2026-03-26T18:00:00Z \
--allowed-actor agent://checkout \
--allowed-action stripe.charge.create \
--max-uses 1At least one scope flag (--allowed-actor, --allowed-action,
--allowed-subject, --max-uses) is required. Without one the command refuses
with approval has no scope; pass --unscoped to mint a bearer approval on
purpose. Note also that --expires takes an RFC 3339 timestamp -- a duration
like 1h is stored verbatim and reads as already expired.
Returns the approval artifact ID and the nonce. Pass the nonce to the agent so it can echo it in --approval-nonce when attesting the action.
Options
| Option | Description |
|---|---|
--approver <uri> | Approver identity URI (required) |
--subject <id> | Artifact ID being approved (the subject of the approval itself) |
--description <text> | Plain text scope of what is authorized |
--allowed-actor <uri> | Scope: actor URIs permitted to consume this approval (repeatable) |
--allowed-action <label> | Scope: action labels permitted under this approval (repeatable) |
--allowed-subject <uri> | Scope: subject URIs permitted as the action's target (repeatable) |
--max-uses <n> | Signed into the grant for future ledger enforcement |
--unscoped | Required to mint a bearer approval (no scope axes set); without it the CLI refuses |
--expires <timestamp> | RFC 3339 expiry time |
Scope is the new default
As of v0.9.6, treeship attest approval refuses to mint an approval that has no scope axis (no --allowed-* and no --max-uses). Pass --unscoped to opt in to a bearer approval explicitly. Verify will warn that an unscoped approval proves binding only -- not actor/action/subject authorization.
Replay posture (v0.9.10)
v0.9.9 shipped the local Approval Use Journal and the consumer-side Hub checkpoint verifier. v0.9.10 closed four trust-bypass paths in those checks. Each replay level surfaces as its own verify row:
replay-package-local— duplicate uses inside this package. Always available.replay-local-journal— the workspace's<config>/journals/approval-use/enforces single-use for(grant_id, nonce_digest). Available when verifying inside the workspace that produced the package.replay-included-checkpoint— embeddedJournalCheckpointrecords verify offline (eachrecord_digestrecomputes).replay-hub-org— a Hub-signed checkpoint covers every embedded use_id. Available when present; the Hub server itself is out of scope for v0.9.9-v0.9.10.
Plus four bundle-level binding rows (added in v0.9.10):
approval-use-record-digest, approval-use-nonce-binding, approval-use-action-binding, approval-use-chain-continuity. Each pins a specific invariant; the panel renders one ✓ or ✗ per row, never silent pass.
The honesty rule: a row reports ✓ only when the matching evidence is present and verified, ✗ only when present and failed, - when the evidence isn't in the package. See Replay levels for the full ladder.
treeship attest handoff
Record a transfer of work between actors.
treeship attest handoff \
--from agent://researcher \
--to agent://executor \
--artifacts art_a1b2,art_c3d4Options
| Option | Description |
|---|---|
--from <uri> | Source actor URI (required) |
--to <uri> | Destination actor URI (required) |
--artifacts <ids> | Comma-separated artifact IDs being transferred (required) |
--approvals <ids> | Comma-separated approval IDs the receiver inherits |
--obligations <text> | Comma-separated obligations the receiver must satisfy |
--verified <file> | Presentation file the receiver verified live. Requires --challenge. Records custody: live only if it verifies right now against this ship's trust roots; otherwise refuses and writes nothing |
--challenge <nonce> | The nonce this ship minted that the presentation answers |
--max-staple-age <duration> | Freshness bound for the presentation's Merkle staple; unknown age fails closed |
--custody-reason <reason> | Record custody: asserted with a reason, e.g. same_computer for agents sharing one keystore. Conflicts with --verified |
--close-loop <session_id> | Bind a sealed local session as close-loop evidence; its receipt.json digest is signed into the handoff. Refuses a session it cannot find |
Custody
A handoff records how custody was established, and verify grades it rather than repeating the signer's word:
# The receiver minted the nonce, the sender answered it, and it verified:
treeship attest handoff --from agent://grok --to agent://claude \
--artifacts art_intent --verified grok.presentation.json --challenge "$NONCE"
# custody: live -- card art_…, verified by agent://claude at 2026-09-02T…| Recorded | verify prints | When |
|---|---|---|
--verified + --challenge, and the check passed | custody: live -- card …, verified by … | The signed block carries the presentation digest and the nonce |
| nothing | custody: asserted (no verification recorded) | Every handoff minted without a verify, including all handoffs before 0.27.0 |
--custody-reason same_computer | custody: asserted (same_computer) | Agents sharing a keystore; a challenge against yourself is not liveness |
a block claiming live without digest or nonce | custody: asserted (claims live without presentation digest and challenge) | The verifier refuses to launder a claim the evidence does not support |
--verified binds the live grade to the presenter: a presentation for agent://grok cannot certify a handoff --from agent://codex. custody and close_loop are inside the signed statement, so neither can be added or upgraded on the wire. In --format json, checks[].custody.live is the verifier's grade, and checks[].close_loop carries the evidence.
treeship attest endorsement
Record an endorsement of an existing artifact. Used for post-hoc validation, compliance sign-off, and countersignatures.
treeship attest endorsement \
--endorser human://auditor \
--subject art_a1b2 \
--kind validationtreeship attest endorsement \
--endorser human://compliance \
--subject art_c3d4 \
--kind compliance \
--rationale "Meets SOC-2 requirements" \
--expires 2026-12-31T00:00:00Z \
--policy-ref https://example.com/policyOptions
| Option | Description |
|---|---|
--endorser <uri> | Endorser identity URI (required) |
--subject <id> | Artifact ID being endorsed (required) |
--kind <type> | Endorsement kind: validation, compliance, countersignature, review (required) |
--rationale <text> | Human-readable rationale for the endorsement |
--expires <timestamp> | Expiration timestamp (RFC 3339) |
--policy-ref <uri> | URI to the governing policy document |
--meta <json> | Extra metadata as a JSON object |
--parent <id> | Parent artifact ID for chain linking |
--out <path> | Write raw DSSE envelope to file (use - for stdout) |
Endorsements are separate artifacts that reference the subject via --subject. They form their own chain and can be verified independently. Use --policy-ref to link to the policy or checklist that was followed during review.
treeship attest receipt
Record an external system confirmation (webhook, timestamp, inclusion proof).
treeship attest receipt \
--system system://stripe-webhook \
--kind confirmation \
--subject art_a1b2 \
--payload '{"eventId":"evt_abc","status":"succeeded"}'For larger structured receipts, read the payload from a file:
treeship attest receipt \
--system system://acme-memory \
--kind memory.proof \
--payload-file memory-proof.json \
--payload-digest sha256:...Options
| Option | Description |
|---|---|
--system <uri> | System that produced the receipt (required) |
--kind <type> | Receipt kind: confirmation, timestamp, inclusion, webhook (required) |
--subject <id> | Subject artifact ID |
--payload <json> | Receipt payload as a JSON object |
--payload-file <path> | Read receipt payload JSON from a file |
--payload-digest <digest> | Digest of the external payload, for example sha256:<hex> |