Truestamp CLI
The open-source truestamp CLI, a single static binary for macOS, Linux, and Windows that submits items, downloads proofs and verifies them online or offline from the terminal, inspects a proof and describes itself, installs via curl, Homebrew, or Go, and signs in with browser-based OAuth 2.1 PKCE.
Overview
The truestamp command-line interface (CLI) is Truestamp’s open-source terminal
client: a single static binary for macOS, Linux, and Windows with no runtime
dependencies. From a shell it submits items, downloads the proofs Truestamp serves,
and verifies a proof file. Verifying needs no Truestamp account, so anyone you hand a
proof to can check it. By default a verification reads Truestamp’s published keyring,
the public chains and the entropy sources the proof names, and draws the submission
window from what they answer; with --offline it reads nothing and shows only that the
proof is intact and signed. The product page at
www.truestamp.com/cli carries the install
instructions, and the source, README, and examples live in the
truestamp-cli GitHub repository.
Releases are published with SHA-256 checksums and a cosign signature over them: the
installer verifies the checksum for you, and truestamp upgrade verifies the checksum
and, when cosign is installed, the signature.
The core commands
A few commands cover the main flow. More are available for scripting and advanced
use; run truestamp help to explore the complete command set, and see the
repository’s README.md and EXAMPLES.md for a full suite of usage examples.
truestamp items createsubmits an item. Given a file, it computes the file’s SHA-256 locally and submits only the hash, with the file’s name as the item’s name; the file never leaves your machine. Claim flags build the claims instead, and a claims file (--claims) or claims on standard input (--claims-stdin) is sent exactly as given. The output showsclaims_jcs, the claims in canonical form as Truestamp keeps them, andclaims_hash. As everywhere in Truestamp, what this records is that your data was submitted within a verifiable window, not when it was authored; see what a Truestamp proof proves. The other ways to submit an item (web form, APIs, console, MCP) are covered in submit an item.truestamp proofs get <id-code-or-hash>downloads the proof Truestamp serves of an item, a block, a beacon or an entropy observation, its bytes exactly as served: one JSON proof bundle, signed by Truestamp. A subject is named by its UUIDv7 id, and an item also by its item code or its item hash. A code names only an item, so it needs no--type; an item hash needs--type item; a UUIDv7 is resolved with the server unless--typenames the subject type. An item’s proof is checked before anything is written: the record it carries must have the id given, or give the code or the item hash given, and otherwise the run writes nothing. A proof exists once the subject’s block has a final commitment on a public chain.--constructionschooses how the proof carries its constructions text (full,referenceornone), and--to-filenames the file after the subject (<CODE>.proof.jsonfor an item).truestamp verify <proof>verifies a proof file, a URL or standard input, making the steps of the verification specification in order: the environment, the signer’s key against the keyring, the signature, the shape, every recomputed hash and inclusion proof, then, online, each chain and entropy source read, and the submission window. Its report is labelledverified,internally-consistent,supplied-keyring,unattributedorfailed, and its exit code is 0 only forverified. What a verifier checks, and in what order, is walked through step by step in verify a proof.truestamp inspect <proof>prints every member a proof carries, beside the values a verification recomputes from it, without verifying anything: it checks no key or signature, reads no chain or source, and gives no verdict.truestamp schemadescribes the binary itself: its command tree, its hash algorithms, and verify’s reason codes and exit codes.
Install and upgrade
Pick a method; all paths ship the same static binary.
curl (recommended for macOS and Linux)
A one-line install that verifies the release’s SHA-256 checksum automatically:
curl -fsSL https://get.truestamp.com/install.sh | sh
Later, upgrade in place with:
truestamp upgrade
The upgrade command is install-method aware. For an install made with the script, it
downloads the new release, verifies its SHA-256 checksum, and verifies its cosign
signature when cosign is installed, before it replaces the binary. For a Homebrew or
Go install it prints the command to run instead.
Homebrew (macOS and Linux)
brew install truestamp/tap/truestamp-cli
On macOS, run this once after each install or upgrade:
xattr -cr "$(brew --caskroom)/truestamp-cli"
The binary is not yet Apple-signed, so Gatekeeper would otherwise block it;
clearing the quarantine attribute lets it launch without a dialog. This step is not
needed on Linux. Upgrade with brew upgrade truestamp/tap/truestamp-cli.
Go (build from source)
With Go 1.27.3 or newer:
go install github.com/truestamp/truestamp-cli/cmd/truestamp@latest
This installs to $GOBIN (default ~/go/bin). Re-run the same command to update
to the latest release.
Signing in from the terminal
Verifying a proof never requires signing in. For commands that act on your account, such as submitting items and downloading proofs, the CLI signs you in through your browser instead of asking for credentials in the terminal; an API key also works, for headless and CI use.
The CLI is a pre-registered, first-party OAuth 2.1 client of Truestamp’s authorization server. Its well-known client id ships baked into the binary, so unlike third-party agent connectors it never has to register itself. The sign-in is the authorization-code flow with PKCE, the standard pattern for a native command-line app:
- There is no client secret; the per-flow PKCE verifier is the only secret, and the authorization server accepts only the SHA-256 challenge method.
- The CLI opens your system browser to the Truestamp consent screen, where you approve the client and the exact scopes before any token is issued.
- The sign-in redirect returns to a small listener the CLI starts on a local
loopback address. Two loopback callbacks are registered for the client,
http://127.0.0.1:8976/callbackandhttp://127.0.0.1:8765/callback, and the CLI binds them in that order. The authorization server matches a registered callback exactly, with one exception: on a loopback address the port may vary, the standard accommodation for native command-line apps. - The client is registered for delegated read and write access to the API and
console surfaces (scopes
api:read,api:write,console:read,console:write) and for refresh tokens, so a signed-in CLI renews its access silently without repeating the consent step.
Verifying a proof you hold
A proof is one self-contained signed document, and truestamp verify checks it with no
Truestamp account. Deleting the item from Truestamp later does not change the proof
you kept. It still verifies online while Truestamp’s published keyring answers and
still holds the key that signed it (a key Truestamp revokes stops binding at once), or
against a keyring you saved and pass with --keyring FILE; offline it shows the proof
intact and signed.
- No account needed. Share a proof with anyone; they can verify it without signing up for Truestamp.
- Online by default. A verification reads Truestamp’s published keyring from
https://www.truestamp.com/.well-known/keyring.json, which binds the signer’s key, and reads the public chains and entropy sources the proof names, from public servers or servers you name. Those reads draw the submission window, and only a run that makes them can reachverified. A run whose keyring read fails binds no key and fails withkeyring_unavailable. - Offline when you ask. With
--offlineit reads nothing outside the file: no Truestamp server, chain or source. It binds the key against the keys built into the CLI, still checks the signature, recomputes every hash it compares and walks every inclusion proof, and reports each read as skipped, so its best label isinternally-consistent: the proof is intact and signed, and no window is drawn. See offline verification. - Your own keyring.
--keyring FILEchecks the signer’s key against a keyring you supply, and--no-keyringchecks the signature only against the key the proof carries, for that run only. - Open source. The CLI is open source and auditable, so the verifier you run is one you (or anyone) can inspect.
The document the CLI checks is described member by member in the proof bundle format.
Where the CLI fits
- CI/CD pipelines. Script attestation in GitHub Actions, GitLab, and any shell-driven pipeline.
- Air-gapped environments. Verify with
--offlineon isolated networks, behind firewalls, or in regulated environments where nothing may call out; the result shows the proof intact and signed. A later online run draws the window when the signing key still binds and the chains and sources still hold the records the proof points to. - Batch and archival. Process many files, and keep their proofs as portable JSON files.
For building an integration in the language of your choice, Truestamp’s REST and GraphQL APIs provide programmatic access from any platform. For connecting an LLM agent such as Claude Code, use the MCP server instead of shelling out to the CLI.
Citations
- RFC 8252: OAuth 2.0 for Native Apps. The loopback-redirect authorization-code pattern the CLI sign-in follows.
- RFC 7636: Proof Key for Code Exchange (PKCE). The per-flow secret used in place of a client secret.