truestamp/truestamp-cli

# Truestamp CLI [](https://github.com/truestamp/truestamp-cli/actions/workflows/ci.yml) [](https://github.com/truestamp/truestamp-cli/releases/latest) [](https://pkg.go.dev/github.com/truestamp/truestamp-cli) [](./LICENSE) Standalone Go CLI for cryptographic timestamping with [Truestamp](https://truestamp.com). 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. ## 📖 Documentation - **[EXAMPLES.md](./EXAMPLES.md)** — Hands-on tour of every sub-command with real, copy-pastable examples. Includes pipeline recipes, `--json` / `jq` patterns, CI conventions, and offline / air-gapped usage. **Start here to see what the CLI can do.** - **[CONTRIBUTING.md](./CONTRIBUTING.md)** — Development setup, test categories, and task reference. - **[CHANGELOG.md](./CHANGELOG.md)** — Release notes. - Per-command help: `truestamp --help`. ## Install ### Install script (macOS, Linux) curl -fsSL https://get.truestamp.com/install.sh | sh Pin a specific version: curl -fsSL https://get.truestamp.com/install.sh | TRUESTAMP_VERSION=vX.Y.Z sh Install to a custom directory: curl -fsSL https://get.truestamp.com/install.sh | TRUESTAMP_INSTALL_DIR=~/bin sh Landing page with these same instructions: [get.truestamp.com](https://get.truestamp.com). ### 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](https://github.com/truestamp/truestamp-cli/releases/latest): - `truestamp-cli__darwin_arm64.tar.gz` — Apple Silicon - `truestamp-cli__darwin_amd64.tar.gz` — Intel Mac - `truestamp-cli__linux_amd64.tar.gz` - `truestamp-cli__linux_arm64.tar.gz` - `truestamp-cli__windows_amd64.zip` - `truestamp-cli__windows_arm64.zip` Extract and place `truestamp` somewhere on your `PATH`. ## Verifying a download Every GitHub Release publishes a `checksums.txt` alongside the archives. To verify a download manually: # From the directory containing the downloaded archive and checksums.txt. sha256sum -c checksums.txt --ignore-missing # GNU coreutils # or on macOS without coreutils: shasum -a 256 -c checksums.txt --ignore-missing The `install.sh` installer and Homebrew cask both verify the SHA-256 automatically — this section is only needed if you downloaded the tarball yourself. ## Quick start The three main commands — `create`, `download`, `verify` — form the full lifecycle of a Truestamp item. Commands that talk to the Truestamp API (`create`, `download`) need an API key (`--api-key`, `TRUESTAMP_API_KEY`, or the config file). `verify` works entirely locally by default. ### Create an item Truestamp supports two submission modes. Pick whichever fits the shape of the thing you're timestamping. **External-hash mode** — for files you can keep around. The file never leaves your device; only its SHA-256 is submitted. truestamp create document.pdf Under the hood this computes SHA-256 of the file, uses the filename as the item name, and registers the hash with the Truestamp API so it'll be included in the next block. **Claims-as-source-of-truth mode** — for things that don't have a file. Written statements, invention disclosures, dated facts, release notes. The claims content itself is what gets timestamped, so no file needs to be preserved alongside the proof. truestamp create -n "Invention" \ -d "On this day I claim the following novel approach as my own original work." The server requires the claims content to be meaningful in this mode: at least a 32-character description (or non-empty `--metadata`). The CLI checks this locally before any network round-trip. Other input styles: truestamp create --file document.pdf # External hash: explicit file truestamp create --file # External hash: interactive picker truestamp create -c claims.json # Either mode: claims from JSON file cat claims.json | truestamp create -C # Either mode: claims from stdin truestamp create -n "Q1 Report" --hash abc123... \ # External hash: build from flags -v public -t finance,reports truestamp create -n "Title" --metadata '{"k":"v"}' # Claims-only: metadata satisfies the rule The `--hash` and `--hash-type` flags are co-required: supply both (external-hash mode) or neither (claims-as-source-of-truth mode). Submitting exactly one is rejected. JSON output for scripting: truestamp create document.pdf --json In claims-as-source-of-truth mode the JSON output omits the `hash` and `hash_type` keys; scripts can use `jq 'has("hash")'` to branch on the mode. ### Download a proof bundle After an item has been committed to a block, download its proof by ID. Item IDs are ULIDs; entropy observation IDs are UUIDv7s; the command auto-detects which from the format: truestamp download 01KNN33GX5E470CB9TRWAYF9DD Pick a format and output path: truestamp download -f cbor -o proof.cbor 01KNN33GX5E470CB9TRWAYF9DD truestamp download -o /tmp/proof.json 01KNN33GX5E470CB9TRWAYF9DD Download an entropy proof (UUIDv7 triggers entropy proof mode): truestamp download 019d6a32-13e6-72b0-97e5-3779231ea97b ### Verify a proof truestamp verify proof.json Exit code `0` on success, `1` on failure or structural error. Offline verification (no calls to Truestamp, Stellar, or Bitcoin APIs): truestamp verify proof.json --skip-external Silent mode for scripting: truestamp verify proof.json --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 create [file] Create a new Truestamp item (submit claims / file hash) truestamp download Download a proof bundle for an item or entropy observation truestamp verify [proof] Verify a Truestamp proof bundle truestamp hash [path ...] Compute cryptographic digests (SHA-2 / SHA-3 / BLAKE2 / MD5 / SHA-1) truestamp encode [file] Encode raw bytes into hex / base64 / base64url truestamp decode [file] Decode hex / base64 / base64url into raw bytes truestamp jcs [file] Canonicalize JSON per RFC 8785 truestamp convert time [input] Convert timestamps across zones / Unix formats truestamp convert proof [file] Convert a proof bundle between JSON and CBOR truestamp convert id [value] Extract the embedded timestamp from a ULID or UUIDv7 truestamp convert keyid [pubkey] Derive the 4-byte Truestamp kid from an Ed25519 public key truestamp convert merkle [compact] Decode a compact base64url Merkle proof truestamp upgrade Upgrade the CLI to the latest release (install-method aware) 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 (includes detected install method) truestamp --version Terse one-line version truestamp completion Generate shell completions (bash, zsh, fish) Run `truestamp --help` for per-command flags. ### Composable pipelines # SHA-256 a file, byte-identical to sha256sum / shasum output truestamp hash doc.pdf # Pick a different algorithm (14 supported; see `truestamp hash --list`) truestamp hash -a blake2b-512 doc.pdf truestamp hash -a sha3-256 --style bsd doc.pdf # Recompute a Truestamp claims_hash locally — the flagship use case truestamp hash --prefix 0x11 --jcs -a sha256 --style bare --no-filename < claims.json # equivalently, as an explicit pipeline: truestamp jcs < claims.json | truestamp hash --prefix 0x11 -a sha256 --style bare --no-filename # Round-trip a proof between wire formats and verify end-to-end truestamp convert proof --to cbor proof.json | truestamp verify --skip-external # Derive the 4-byte kid fingerprint from an Ed25519 pubkey truestamp convert keyid CTwMqDZnPd/QTLSq8aTeSD3a+j2DQxKcGfhhIYJQ65Y= # Timezone math without shelling out to `date` truestamp convert time 1700000000 --to-zone America/New_York truestamp convert time "2024-06-15T12:00:00Z" --to-zone Asia/Kolkata # ULID / UUIDv7 timestamp extraction truestamp convert id 01KNN33GX5E470CB9TRWAYF9DD truestamp convert id 019cf813-99b8-730a-84f1-5a711a9c355e --to-zone Local Every command supports `--json` (structured output for scripting) and `-s` / `--silent` (exit code only). `truestamp hash` defaults to GNU `sha256sum`-compatible output, `--style bsd` switches to BSD `shasum --tag` format. **More examples:** [EXAMPLES.md](./EXAMPLES.md) covers every sub-command with copy-pastable recipes, scripting patterns, CI conventions, and offline usage. ## Upgrading The `truestamp upgrade` command is install-method aware — it detects how the binary was installed (Homebrew, `go install`, or install.sh / manual tarball) and does the right thing for each: | Install method | `truestamp upgrade` behavior | | -------------- | ---------------------------- | | Homebrew | Prints `brew upgrade --cask truestamp/tap/truestamp-cli` (does not touch the Homebrew prefix). | | `go install` | Prints `go install github.com/truestamp/truestamp-cli/cmd/truestamp@latest`. | | install.sh / manual | Downloads the latest release tarball, verifies SHA-256 (mandatory, pure Go) and cosign signature (best-effort; required if `TRUESTAMP_REQUIRE_COSIGN=1`; `cosign` is located on `$PATH` by default, or pin an absolute path with `cosign_path` in config or `TRUESTAMP_COSIGN_PATH` env var to defend against `$PATH` hijacking), extracts the binary, atomically replaces the running executable, and clears the macOS quarantine xattr. A `.bak.` backup of the previous binary is kept for 7 days. | | Windows (any method) | Prints `go install ...@latest`. In-place upgrade is not supported on Windows in this release. | Check the detected install method at any time: truestamp version # output includes `install ` Flags: truestamp upgrade --check # only report whether an upgrade is available (does not install) truestamp upgrade --yes # skip the interactive confirmation prompt truestamp upgrade --version v0.4.0 # pin to a specific release tag (also the opt-in path for pre-releases) `--check` exit codes: `0` up-to-date, `1` upgrade available, `2` network error, `3` the latest release is a pre-release (will not auto-install; pass `--version ` to install one explicitly). ### Passive upgrade notices Once every 24 hours (cached at `$XDG_CACHE_HOME/truestamp/upgrade-check.json`), other commands print a one-line note on stderr if a newer release is available. The notice is automatically suppressed in CI environments (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `BUILDKITE`, `JENKINS_HOME`, `TF_BUILD`), when stderr is not a TTY, when the current version is a local `dev` build, and when the resolved latest is a pre-release. To opt out: truestamp --no-upgrade-check verify proof.json # or persistently: export TRUESTAMP_NO_UPGRADE_CHECK=1 The notice is always on stderr, so it never pollutes stdout (`truestamp verify proof.json > out.json` is safe for scripting). ## 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 | Flag | Env var | Default | | ---- | ------- | ------- | | `--config` | | `~/.config/truestamp/config.toml` | | `--api-url` | `TRUESTAMP_API_URL` | `https://www.truestamp.com/api/json` | | `--api-key` | `TRUESTAMP_API_KEY` | | | `--keyring-url` | `TRUESTAMP_KEYRING_URL` | `https://www.truestamp.com/.well-known/keyring.json` | | `--http-timeout` | `TRUESTAMP_HTTP_TIMEOUT` | `10s` | | `--no-color` | `NO_COLOR` | `false` | | `--no-upgrade-check` | `TRUESTAMP_NO_UPGRADE_CHECK` | `false` | | (config file / env only: `cosign_path`) | `TRUESTAMP_COSIGN_PATH` | | `cosign_path` pins the `cosign` binary used by `truestamp upgrade` for release-artifact signature verification. Empty (the default) means "use `$PATH` lookup"; set this to an absolute path (e.g. `/opt/cosign/bin/cosign`) in hardened environments to avoid `$PATH` hijacking. Relative paths are rejected at config load. Setting has no effect unless you actually run `truestamp upgrade`. ### Verify-specific flags | Flag | Env var | Default | | ---- | ------- | ------- | | `--file [path]` | | | | `--url [url]` | | | | `--hash` | | | | `--silent` / `-s` | `TRUESTAMP_VERIFY_SILENT` | `false` | | `--json` | `TRUESTAMP_VERIFY_JSON` | `false` | | `--skip-external` | `TRUESTAMP_VERIFY_SKIP_EXTERNAL` | `false` | | `--skip-signatures` | `TRUESTAMP_VERIFY_SKIP_SIGNATURES` | `false` | ## 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`. ## Exit codes | Code | Meaning | | ---- | ------- | | `0` | Success. For `verify`, the proof is valid. For `upgrade --check`, the CLI is up to date. | | `1` | Error. Failed verification, network failure, invalid input, or any other runtime error. For `upgrade --check`, a newer release is available. | | `2` | Reserved for future use by other commands (usage / flag-parse errors). For `upgrade --check`, a network error prevented the check. | | `3` | For `upgrade --check` only: the latest release is a pre-release and will not auto-install. Pass `--version ` to install one explicitly. | Scripts that branch on specific codes should check only `upgrade --check`'s documented codes; for other commands, treat any non-zero as failure. ## Related projects - [`truestamp/truestamp-v2`](https://github.com/truestamp/truestamp-v2) — the Truestamp service that generates the proofs this CLI verifies. - [`truestamp/homebrew-tap`](https://github.com/truestamp/homebrew-tap) — the Homebrew tap this CLI publishes to. ## License MIT. See [LICENSE](./LICENSE). Copyright (c) 2019-2026 [Truestamp, Inc.](https://truestamp.com) All rights reserved.

标签：EVTX分析