truestamp-cli

Truestamp CLI

Standalone Go CLI for cryptographic timestamping with Truestamp. Verifies Truestamp proof bundles end to end — user claims, hash chains, Merkle inclusion, Ed25519 signatures, and public-blockchain commitments — with no dependency on the Truestamp service.

Ships as a single static binary. No runtime required.

Install

Homebrew (macOS and Linux)

brew install truestamp/tap/truestamp-cli

Upgrades:

brew upgrade truestamp/tap/truestamp-cli

Go install

go install github.com/truestamp/truestamp-cli/cmd/truestamp@latest

Produces a binary at $GOBIN/truestamp (default ~/go/bin/truestamp). Requires Go 1.22 or newer.

The /cmd/truestamp suffix is required so the go toolchain names the binary truestamp rather than truestamp-cli (Go derives the binary name from the package path's last element).

Direct download

Grab the archive for your platform from the Releases page:

• truestamp-cli_<version>_darwin_arm64.tar.gz — Apple Silicon
• truestamp-cli_<version>_darwin_amd64.tar.gz — Intel Mac
• truestamp-cli_<version>_linux_amd64.tar.gz
• truestamp-cli_<version>_linux_arm64.tar.gz
• truestamp-cli_<version>_windows_amd64.zip
• truestamp-cli_<version>_windows_arm64.zip

Extract and place truestamp somewhere on your PATH. Verify checksums.txt with sha256sum -c before running.

Quick start

truestamp verify proof.json

Exit code 0 on success, 1 on failure or structural error.

Offline verification (no network calls to Truestamp, Stellar, or Bitcoin APIs):

truestamp verify proof.json --skip-external

Silent mode for scripting:

truestamp verify proof.json --output silent && echo valid || echo invalid

Other input sources:

truestamp verify https://example.com/proof.json   # URL
truestamp verify --file                            # Interactive file picker
truestamp verify --url                             # Interactive URL prompt
cat proof.json | truestamp verify                  # stdin pipe

Commands

truestamp verify [proof]     Verify a Truestamp proof bundle
truestamp config path        Print the config file path
truestamp config show        Print the resolved configuration (API key masked)
truestamp config init        Create a default config file
truestamp version            Print detailed build and runtime info
truestamp --version          Terse one-line version
truestamp completion <shell> Generate shell completions (bash, zsh, fish)

Run truestamp <command> --help for per-command flags.

Configuration

Settings are resolved in this order (later overrides earlier):

1. Compiled defaults
2. Config file (~/.config/truestamp/config.toml by default)
3. Environment variables (TRUESTAMP_*)
4. CLI flags

Global flags

Verify-specific flags

What gets verified

1. Signing key against the published keyring
2. Proof structure (required fields, block reference)
3. Subject hash — claims hash (0x11), timestamp validation, item hash (0x13)
4. RFC 6962 Merkle inclusion proof against the block root
5. Block hash (0x32) derivation
6. Epoch proofs: block hash → each public-blockchain commitment root
7. Ed25519 proof signature over the binary payload
8. Temporal ordering (item submission before block)
9. Stellar commitment via Horizon API (memo + ledger)
10. Bitcoin commitment via local crypto (OP_RETURN, txid, partial Merkle tree) plus optional Blockstream API

Skipped selectively with --skip-external and --skip-signatures.

Development

This repo uses mise for tool versions and Task for the developer workflow.

mise install                 # Installs Go and GoReleaser from .tool-versions
task build                   # Build for current platform → build/truestamp
task test                    # Run all tests
task precommit               # fmt + vet + test + build-all
task release-snapshot        # Local GoReleaser dry-run → dist/

The Go module path is github.com/truestamp/truestamp-cli; releases are tagged vX.Y.Z and drive both the GitHub Release and the Homebrew Cask publication to truestamp/homebrew-tap via GoReleaser.

Related projects

• truestamp/truestamp-v2 — the Truestamp service that generates the proofs this CLI verifies.
• truestamp/homebrew-tap — the Homebrew tap this CLI publishes to.

License

MIT. See LICENSE.