CLI reference
CLI overview
Full command surface for the treeship CLI.
Installation
curl -fsSL https://www.treeship.dev/install | shAll commands
# Identity
treeship init # set up a new Treeship
treeship status # show state, keys, hub status
# Sessions
treeship session start [--name NAME] # start a new session
treeship session status # show current session state
treeship session close [--summary TEXT] # close the active session
# Attestation
treeship wrap -- <cmd> # attest any command execution
treeship attest action # record an action
treeship attest decision # record an LLM decision
treeship attest approval --allowed-action <label> # record an approval (needs a scope flag)
treeship attest handoff # record a handoff
treeship attest endorsement # record an endorsement
treeship attest receipt # record a receipt
# Approvals
treeship pending # list pending approval requests
treeship approve [N] # approve a pending request
treeship deny [N] # deny a pending request
# Verification
treeship verify <id> # verify an artifact or chain, exit 0/1
treeship verify <id> --format json # machine-readable output
treeship verify <id> --no-chain # verify single artifact, skip chain walk
# Log
treeship log [--tail N] # list recent receipts
treeship log --follow # stream receipts in real time
# Bundle
treeship bundle create # create a bundle from artifacts
treeship bundle export <id> # export a chain as a .treeship file
treeship bundle import <file> # import a .treeship file locally
# Hub connections (treeship.dev Hub)
treeship hub attach # connect to Hub (or reconnect)
treeship hub attach --name acme-corp # named hub for separate workspace
treeship hub detach # disconnect active hub (keeps keys)
treeship hub ls # list all known hub connections
treeship hub status # show active hub details
treeship hub use <name> # switch active hub connection
treeship hub push <id> # push artifact to active hub
treeship hub push <id> --hub <name> # push to specific hub
treeship hub push <id> --all # push to all hubs
treeship hub pull <id> # pull artifact from Hub
treeship hub open # open workspace in browser
treeship hub kill <name> # remove a hub connection
# Daemon
treeship daemon start [--foreground] # start the background watcher
treeship daemon stop # stop the daemon
treeship daemon status # check daemon state
# Merkle tree
treeship checkpoint # seal a signed Merkle root
treeship merkle proof <id> # generate inclusion proof
treeship merkle verify <proof.json> # verify proof offline
treeship merkle status # tree state and checkpoints
treeship merkle publish # push checkpoint + proofs to Hub
# Terminal UI
treeship ui # interactive dashboard
# Shell hooks
treeship install # install shell hooks
treeship uninstall # remove shell hooks
# Keys and trust roots
treeship keys list # show key fingerprints
treeship keys export [KEY] # print a key's public half + the trust add lines
treeship trust list # show pinned trust roots
treeship trust add <key> <pub> --kind <kind> # pin one power (agent_cert, cert_issuer, ...)
treeship trust remove <key> # remove a pin (all kinds)
# Agent identity, provenance, and discovery
treeship onboard <agent> --tools <list> # register agent + mint card + trust bundle, one command (or --from-harness/--tools-json/--from-a2a)
treeship resolve <agent> [--hub URL] # resolve to a verifiable bundle, re-derived verdicts
treeship publish <agent> # push cards + cert chain + revocations to the hub
treeship audit <agent> --hub <url> # re-verify a hub's transparency log offline
treeship history <agent> [--hub URL] # signed session.v1 work records, re-verified
treeship profile <agent> [--attest] # checkpoint-pinned recomputable track record
treeship verify-profile <id> # recompute an attested profile: checked or MISMATCH
treeship match --hub <url> --exercised <glob> # find agents by verified evidence
treeship present <agent> [--disclose] # package proof for offline handoff (+ selective disclosure)
treeship verify-presentation <file> # verify a presentation against YOUR roots
treeship verify-capability <card-id> # verify a capability card + scope cross-check
treeship revoke-capability <card-id> # revoke a capability card
# Portable receipts
treeship receipt export <id> # message/signature/key triple, verifiable by any Ed25519 lib
# OpenTelemetry (in the default build; set TREESHIP_OTEL_ENDPOINT)
treeship otel test # verify OTLP connectivity
treeship otel status # show OTel config
treeship otel export <id> # export artifact as span
treeship otel enable # enable export
treeship otel disable # disable export
# Diagnostics
treeship doctor # run 9 health checksGlobal flags
| Flag | Description |
|---|---|
--config <path> | Config file (default: ~/.treeship/config.json) |
--format <text|json> | Output format (default: text) |
--quiet | Suppress all output except errors |
--no-color | Disable color output |
Environment variables
| Variable | Description |
|---|---|
TREESHIP_PARENT | Default parent artifact ID for chain linking (wrap, session, attest, hook). Priority: explicit --parent flag > TREESHIP_PARENT > the .last file |
NO_COLOR | Disable color output |
TREESHIP_ACTOR and TREESHIP_DISABLE are read by the @treeship/mcp bridge, not by this CLI; TREESHIP_DEBUG isn't read anywhere in the codebase. There is no TREESHIP_LAST env var -- the CLI tracks the most recent artifact id itself in a local .last file, and the literal string last works as an artifact-id argument wherever one is expected (treeship verify last, treeship hub push last, treeship prove last, and so on).
wrap auto-chains to the previous artifact with no flag or env var needed: it resolves the parent in priority order (explicit --parent > TREESHIP_PARENT > the .last file), so a plain treeship wrap -- <cmd> after another attestation already chains onto it.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. For a verifier, the verdict is pass |
| 1 | Error, or the verdict is fail. The default for anything that went wrong |
| 2 | The argument parser rejected the call (unknown command, missing argument). Also judge --enforce when the judge said deny, and verify --certificate when the receipt and certificate do not agree (cross-verification failed) |
| 3 | Not initialized: run treeship init first. Also judge --enforce when the judge said ask, and verify <url> when the fetch failed (a network error) |
| 4 | The command itself refused the call as written (a missing value such as judge --resolve <id> with no --by, or an impossible combination such as session countersign with neither a participant id nor --pending). Distinct from 2: this is the command's own check, after argument parsing already succeeded |
| 5 | Not compiled into this build: prove, prove-chain and verify-proof without --features zk; otel without the otel feature |
| 6 | The signature verifies, but its signer is not a pinned trust root here: merkle verify on a checkpoint whose signer you have not pinned as hub_checkpoint. A trust decision, not a broken signature; confirm the key out of band before pinning it. An invalid signature is still 1 |
Every failure exits nonzero. A command that cannot do what was asked never exits 0 with a warning. The code comes from the error's type, not from words in its message. The contract test in packages/cli/tests/contract.rs pins each row.