Orphograph Empirical Notary

Docs · Command line

A folder, a terminal, a receipt.

The command line exists for the work nobody wants to do by hand: a nightly job over a working directory, an intake script that stamps a batch on arrival, a verification run against a folder somebody handed you on a drive. Every invocation writes one line of JSON to standard output and sets an exit code, which is all a shell script needs to make a decision.

The command ships inside the Python SDK. If you would rather call the service directly, the HTTP API covers the same ground, and the SDK reference covers the library form.

Install

The package is not on PyPI yet, so it installs from source. Git and pip are the only prerequisites; the library itself pulls no third-party dependencies and targets Python 3.9 or newer.

pip install "git+https://github.com/Orphograph/Orphograph#subdirectory=sdk-python"

That registers an orphograph executable on your path. Confirm it:

$ orphograph --help
usage: orphograph [-h] [--server-url SERVER_URL] [--api-key API_KEY]
                  {anchor,verify,inclusion-proof} ...

Anchor folders to Bitcoin via the Orphograph service.

The three subcommands

orphograph anchor <folder>

orphograph anchor /path/to/folder --label "Case file 2026-05-20"

Walks the folder, hashes every file in place, and submits a single Merkle root. File bytes are not transmitted — only the manifest of paths, per-file digests, leaf hashes, and the thirty-two-byte root. Returns the receipt id and root. --label is an optional short client label; --exclude GLOB is repeatable.

orphograph verify <folder> <receipt_id>

orphograph verify /path/to/folder XwTULwlh76PcCst9

Re-walks the folder, recomputes the root, and compares it against the receipt. Exit code zero on a match, non-zero on a mismatch — which is what makes it usable as a gate in a shell script or a CI step.

orphograph inclusion-proof <receipt_id> <path>

orphograph inclusion-proof XwTULwlh76PcCst9 sub/photo.jpg

Fetches the Merkle path proving that one named file was part of the anchored set, without revealing the rest of the folder. Useful when you must show that a single document was covered by an anchor and nothing more.

On --exclude. Supplying any --exclude replaces the default deny-list rather than extending it. On verify it applies only to manifests without a recorded scope block — a manifest's own scope.exclude is authoritative. The rule is stated in full in VERIFIER_SPEC §4.2.

Configuration

Two options apply to every subcommand, and each has an environment-variable form so scripts need not carry secrets on the command line.

--server-url · ORPHO_SERVER_URL

Base URL of the service. Defaults to https://orphograph.com. Point it elsewhere to run against your own deployment.

--api-key · ORPHO_API_KEY

Optional. Anchoring works without a key on the free tier, which is rate-limited by IP; a key on an active plan associates anchors with your account and lifts that limit. Prefer the environment variable — a key on the command line lands in your shell history.

A nightly job, in full

The shape most people want. Anchor a working directory, record the receipt id, and fail loudly if the anchor did not take.

#!/bin/sh
set -eu
export ORPHO_API_KEY="$(cat ~/.config/orphograph/key)"

orphograph anchor "$HOME/working-set" --label "nightly" \
  | tee -a "$HOME/.local/state/orphograph-receipts.jsonl"

Because the output is one JSON object per line, the log file is itself a ledger: every anchor you have ever taken, in order, ready to be replayed through verify. The receipts remain checkable with this service switched off — see verifying a receipt for the offline path.

Further reading

The SDKs expose the same operations as library calls. The HTTP API is the layer beneath both. Folder anchoring by Merkle root explains what the root commits to and, just as importantly, what it does not.