CLI Guide

The thesislock-cli package verifies anchors from the terminal or a CI pipeline, with no browser or wallet required. It hashes files locally and compares only the SHA-256 digest against on-chain data; files are never uploaded.

Every command also accepts --json for machine-readable output and --quiet for a single essential value, which makes the CLI easy to script.

Installation

The CLI depends on the sibling sdk/ package, so build that first when working from the monorepo:

cd sdk && npm install && npm run build
cd ../cli && npm install && npm run build
node dist/bin/thesislock.js --help

Link the built package to put the thesislock command on your PATH. Once published to the registry, a global install also works:

cd cli && npm link
# or, after publish:
npm install -g thesislock-cli

verify

Check whether a hash is anchored in any contract (single, batch, registry, proof NFT, or group). Exits 0 when anchored and 1 when not, so it works directly as a CI gate.

thesislock verify 9afe6f57ea2af60478ad37b2d44ae8ede492c4f3b7e70bcc7dfea92128585d06

Verified
  Source:    thesislock (single anchor)
  Label:     project
  Owner:     SPMXTB2P571VMJP2ZG812P2H964S1XVTCDC8QNYX
  Block:     8104143
  Timestamp: 2026-05-27T13:13:00.000Z

Batch owners are discovered automatically from registry events, and an explicit owner can be supplied with --owner:

thesislock verify <hash> --owner SP000...

Use --quiet for a bare true or false, or --json for a structured result.

thesislock verify <hash> --quiet
thesislock verify <hash> --json

hash

Compute the SHA-256 digest of one or more files. For each file the CLI prints the filename, size, and 64-character hex hash.

thesislock hash thesis.pdf
thesislock hash chapter1.pdf chapter2.pdf chapter3.pdf

Add --verify to check each digest against the chain in the same step. The exit code is 1 if any file is missing an anchor.

thesislock hash thesis.pdf --verify

status

Protocol overview: contract count and addresses, the latest Stacks block, and Hiro API health. Pass a principal to see how many anchors a wallet has registered.

thesislock status
thesislock status SPMXTB2P571VMJP2ZG812P2H964S1XVTCDC8QNYX

search

Search anchors across all contracts. The query type is auto-detected: 64-hex searches by hash, a Stacks address by wallet, and anything else as a label substring. Results print as a table; add --json for machine-readable output, and --limit to cap the rows.

thesislock search "thesis draft"
thesislock search SPMXTB2P571VMJP2ZG812P2H964S1XVTCDC8QNYX
thesislock search 9afe6f57...585d06 --json
thesislock search SPMXTB2P571VMJP2ZG812P2H964S1XVTCDC8QNYX --limit 5

batch

Hash every file in a directory. For each file the CLI prints the path relative to the scanned directory, size, and hash, then a summary line. Add --recursive to descend into subdirectories, --exclude for comma-separated glob patterns, and --verify to check each hash on chain.

thesislock batch ./papers
thesislock batch ./papers --recursive --exclude "*.log,node_modules"
thesislock batch ./papers --verify --json

Scripting

--quiet emits a single value per command, ideal for shell substitution, and --json pairs well with jq.

HASH=$(thesislock hash thesis.pdf --quiet)
thesislock batch ./papers --verify --json | jq -r '.[] | select(.anchored == false) | .path'

Shell completion

Completion scripts for bash and zsh ship in the completions/ directory of the CLI package and complete every command and flag.

# bash: from your ~/.bashrc
source /path/to/thesislock-cli/completions/thesislock.bash

# zsh: place the script on your fpath, then reload completions
mkdir -p ~/.zsh/completions
cp completions/thesislock.zsh ~/.zsh/completions/_thesislock
# in ~/.zshrc, before compinit:
#   fpath=(~/.zsh/completions $fpath)
#   autoload -U compinit && compinit

Configuration

THESISLOCK_API_URL=https://my-hiro-proxy.example.com thesislock status

CI integration

Use verify or hash --verify as a step that fails when a document is not anchored:

jobs:
  verify-anchor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install ThesisLock CLI
        run: npm install -g thesislock-cli
      - name: Verify the published whitepaper is anchored
        run: thesislock hash docs/whitepaper.pdf --verify

For a packaged step with typed inputs and outputs, the GitHub Action wraps the same verification.