Skip to content

Query the ledger quickly

Four read commands answer most questions. They never write, and they work on a ledger of tens of thousands of entries in well under a second (summary on 10,000 entries takes about as long as one verify-ledger).

What was done, and are the results honest?

protocolith summary
ledger OK  entries=3  head seq=2 hash=6c46d744...
entries: freeze 1, record 1, deviation 0, issue 1
results: PASSED_UNDER_PROTOCOL 1
PROTOCOL         VERSIONS  LATEST  RECORDS  LATEST_STATUS          DEVIATIONS  CARDS
QUICKSTART_D001  1         1       1        PASSED_UNDER_PROTOCOL  0           1
problems: none

The first line is the verification verdict and the head. Then come the counts by entry type and by result status, one row per protocol (all its versions, the latest version, records, the status of the latest record, deviations and issued cards) and the problems found. If the ledger does not verify, summary still prints what it could read, lists the violations under problems and exits with 1. --protocol ID limits it to one protocol; --json prints canonical JSON.

Filter the log

protocolith log --protocol QUICKSTART_D001 --type record
protocolith log --status BLOCKED_SOURCE          # only records with that status
protocolith log --tail 5                         # the last five entries
protocolith log --type issue --tail 1 --json

Filters combine. An unknown protocol is an error (UNKNOWN_PROTOCOL) rather than an empty list.

Look at one entry

protocolith show 1

It prints the entry, the protocol it belongs to (and the seq where that protocol was frozen), the entries it points at (for a record: its deviations; for an issue: its record) and the entries that point at it.

Capture the environment and inputs

protocolith capture --file results.txt --env
{"environment":{"machine":"arm64","platform":"darwin","protocolith":"0.6.0","python":"3.13.1"},"inputs":[{"path":"results.txt","sha256":"60ff5e00...","size":34}]}

Paste the fragment into the outcome object of your record. It runs nothing, reads no environment variable values, and only hashes files inside the current directory (with relative paths).

See the formats

protocolith schema record

prints the JSON Schema of a record body; protocolith schema prints all of them. They are generated from the same rules the verifier uses.

Start a store, and read errors

protocolith init creates an empty store and prints its path; repeating it changes nothing. Errors end with a one-line hint saying what to do, for example hint (NO_LEDGER): run protocolith freeze FILE ....

From Python: core.summary(store), core.log(store, type="record", tail=5), core.show(store, 1). From an agent: the tools and resources in the MCP reference.