verify

treeship verify accepts three target shapes and one optional cross-check:

• a URL to a receipt JSON document served by the Hub
• a file path to a local .treeship or .agent package directory
• an artifact ID from local storage (the original v0.1 path; chain walk + signature checks)

Pair any of those with --certificate to also confirm the session stayed inside the envelope of an Agent Certificate.

Usage

treeship verify <url-or-path-or-artifact-id> [OPTIONS]

Options

Exit codes

Examples

treeship verify https://api.treeship.dev/v1/receipt/ssn_abc123

  ✓  Downloaded receipt
  ✓  Merkle root verified
  ✓  2/2 inclusion proofs passed
  ✓  Leaf count matches artifact count
  ✓  Timeline ordering verified
  ✓  Chain linkage intact

Structurally consistent.

  ⚠  signatures and issuer were NOT verified from this source
       checked:      Merkle root, inclusion proofs, leaf count, timeline order
       not checked:  who signed this receipt (no signature or trust-root check)

  hint: to verify signatures against your trust roots, use the local
        artifact form: treeship verify <artifact-id>

  Session:   ssn_abc123
  Ship:      ship_demo
  Agent:     researcher
  Duration:  4m 22s
  Actions:   28

treeship verify .treeship/sessions/ssn_abc123.treeship

treeship verify ./researcher.agent

treeship trust add <key_id> <pubkey> --kind agent_cert
# or sync from your hub:
treeship hub sync-trust

treeship verify https://api.treeship.dev/v1/receipt/ssn_abc123 \
  --certificate ./researcher.agent

  ✓  Certificate verified
  ✓  Ship IDs match
  ✓  All 12 tool calls authorized by certificate

Complete trust loop verified.

treeship verify art_f7e6d5c4 --full

treeship verify $RECEIPT_URL --format json --certificate $CERT_PATH \
  | jq -e '.cross_verify.ok == true'

{
  "outcome": "structural-pass",
  "signatures_verified": false,
  "issuer_verified": false,
  "note": "structural checks only (Merkle root, inclusion proofs, leaf count, timeline). Signatures and issuer are NOT verified from a fetched receipt; use the local artifact-ID verify path for signature verification.",
  "receipt": { "session_id": "ssn_abc123", "ship_id": "ship_demo", "schema_version": "1", "artifact_count": 28 },
  "checks": [ { "name": "merkle_root", "status": "pass", "detail": "..." } ]
}

What the verifier checks

The exact set of checks depends on what's available at the target:

• URL mode runs every check that's derivable from the receipt JSON alone: Merkle root recomputation, inclusion proofs, leaf count, timeline ordering, chain linkage. Per-artifact Ed25519 signature checks need the original envelope bytes, which only the local-storage and .treeship package paths have.
• .treeship package mode runs everything URL mode runs plus determinism (the on-disk receipt.json round-trips byte-identical) and any signature checks the package preserves.
• .agent package mode verifies the certificate's Ed25519 signature and requires the issuer key to be pinned in your trust store (kind agent_cert). A certificate is never accepted on its embedded key alone — that would make every certificate self-signed. Fails closed when no trust roots are configured.
• Artifact-ID mode is the original local-storage path: walks the parent chain, verifies every signature, enforces nonce binding on approvals, checks expiry. See the chain-verification guide for full semantics.

The cross-verification path additionally verifies that the receipt's session.ship_id matches the certificate's identity.ship_id, the certificate was valid at verify time (issued_at <= now <= valid_until), and every tool the session called is present in the certificate's capabilities.tools list. See the cross-verification concept for the full semantics.

Approval Authority replay rows (v0.9.10)

When the package contains evidence of consumed ApprovalUse records, verify emits one row per replay level — each row pinned to a specific invariant. The strongest level the package's evidence supports wins; nothing silently downgrades.

Plus four bundle-level integrity rows added in v0.9.10:

The honesty rule

A row reports ✓ only when the matching evidence is present and verified. ✗ only when the evidence is present and a check failed. - (or absent) when the evidence isn't in the package at all — never silent pass. Treeship will physically refuse to print "global single-use enforced" or "replay-hub-org passed" without a real Hub-signed checkpoint that verifies cleanly AND covers every use_id.

Strict mode

treeship package verify --strict <pkg>

Promotes every approval-evidence warning to a hard failure. replay-*, approval-use-record-digest, approval-use-nonce-binding, approval-use-action-binding, and approval-use-chain-continuity all participate. Existing receipt-determinism / event-log warnings stay warnings.

Useful in CI:

treeship package verify --strict ./session.treeship
echo "exit code: $?"   # non-zero on any approval anomaly

For the full ladder and the v0.9.10 bypass paths the binding rows close, see Replay levels and Approval Authority.