Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

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.

Open resource

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 create submits 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 shows claims_jcs, the claims in canonical form as Truestamp keeps them, and claims_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 --type names 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. --constructions chooses how the proof carries its constructions text (full, reference or none), and --to-file names the file after the subject (<CODE>.proof.json for 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 labelled verified, internally-consistent, supplied-keyring, unattributed or failed, and its exit code is 0 only for verified. 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 schema describes 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/callback and http://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 reach verified. A run whose keyring read fails binds no key and fails with keyring_unavailable.
  • Offline when you ask. With --offline it 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 is internally-consistent: the proof is intact and signed, and no window is drawn. See offline verification.
  • Your own keyring. --keyring FILE checks the signer’s key against a keyring you supply, and --no-keyring checks 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 --offline on 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

  1. RFC 8252: OAuth 2.0 for Native Apps. The loopback-redirect authorization-code pattern the CLI sign-in follows.
  2. RFC 7636: Proof Key for Code Exchange (PKCE). The per-flow secret used in place of a client secret.