Knowledge Base

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. It covers the whole proof lifecycle from a shell: hash a file locally and submit the claim, download the cryptographic proof once the item is committed to a block, and verify any proof. Verification runs fully offline and needs no Truestamp account, so anyone you hand a proof to can check it independently. 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 signed: the installer verifies the release checksum for you, and truestamp upgrade verifies both the checksum and the release signature.

The core commands

Three 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 create hashes a file locally and submits the claim to the Truestamp API. 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 download fetches the cryptographic proof bundle once the item has been committed to a block.
• truestamp verify confirms a proof is authentic and the original data is unchanged, fully offline. What a verifier checks, and in what order, is walked through step by step in verify a proof.

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 and verifies both the SHA-256 checksum and the cosign signature of the new release.

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.26 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 their proofs, the CLI signs you in through your browser instead of asking for credentials in the terminal.

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.

Trust-independent verification

Every proof is a self-contained artifact. Once you download it, it verifies with the open-source CLI offline, without a Truestamp account, and without trusting Truestamp. Even if the item is later deleted from Truestamp, the proof you kept still verifies.

• No account needed. Share a proof with anyone; they can verify it without signing up for Truestamp.
• No network needed. Verification runs completely offline, with no calls to Truestamp servers; see offline verification.
• Open source. The CLI is open source and auditable, so the verifier you run is one you (or anyone) can inspect.

The bundle the CLI checks is documented field by field 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 on isolated networks, behind firewalls, or in regulated environments where nothing may call out.
• Batch and archival. Process many files and export portable binary or JSON proofs.

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.