Command reference for the usertrust CLI — init, inspect, health, verify, snapshot, tb.

All CLI commands are available via npx usertrust.

usertrust init

Creates the .usertrust/ vault directory with default config, policy rules, and audit chain.

npx usertrust init

Creates:

.usertrust/
├── usertrust.config.json
├── audit/
│   ├── events.jsonl
│   └── index.json
├── policies/
│   └── default.yml
├── patterns/
│   └── memory.json
├── leases.json
├── snapshots/
├── dlq/
│   └── dead-letters.jsonl
└── tigerbeetle/

usertrust inspect

Shows a vault bank statement — budget, spend, remaining balance, recent transactions.

npx usertrust inspect
npx usertrust inspect --json   # machine-readable output

usertrust health

Entropy diagnostics with 6 signals, scoring 0-100:

npx usertrust health
npx usertrust health --json

6 entropy signals measured for governance health diagnostics.

usertrust verify

Verifies the integrity of the SHA-256 hash-chained audit trail:

npx usertrust verify
npx usertrust verify --json

Checks:

Every event's hash covers the previous event's hash
Chain starts from GENESIS_HASH (64 zeros)
No gaps or tampering in the sequence

usertrust snapshot

Create and restore vault state checkpoints:

npx usertrust snapshot           # create a snapshot
npx usertrust snapshot --list    # list available snapshots
npx usertrust snapshot --restore <name>  # restore from snapshot

usertrust tb

TigerBeetle process management:

npx usertrust tb start    # NOT YET IMPLEMENTED — prints the manual command below
npx usertrust tb stop     # NOT YET IMPLEMENTED — prints the manual command below
npx usertrust tb status   # works: reports whether a TigerBeetle process is running

tb start and tb stop are stubs today. They exit without managing anything and print the manual command instead — process lifecycle management is a future version. tb status is real: it checks for a running tigerbeetle process.

Start and stop TigerBeetle yourself:

mkdir -p ./data   # format writes the file, not the directory above it
tigerbeetle format --cluster=0 --replica=0 --replica-count=1 --development ./data/0_0.tigerbeetle
tigerbeetle start --addresses=3001 --cache-grid=256MiB ./data/0_0.tigerbeetle
kill $(pgrep tigerbeetle)

Two things this block gets right that are easy to get wrong:

mkdir -p ./data first. usertrust init creates the .usertrust/ vault, not ./data, and tigerbeetle format exits error: FileNotFound when the parent directory is missing.
Port 3001, not 3000. With the generated config, the SDK dials 127.0.0.1:3001 — tigerbeetle.addresses is not written by init, so the schema default in packages/core applies. The tb start stub still prints --addresses=3000, which predates that default; bind 3001 as above, or set tigerbeetle.addresses in .usertrust/usertrust.config.json to whatever you did bind.

See the TigerBeetle quick start for installation and for running it in Docker.

usertrust completions

Generate shell completion scripts:

# Bash
npx usertrust completions bash > ~/.local/share/bash-completion/completions/usertrust

# Zsh
npx usertrust completions zsh > "${fpath[1]}/_usertrust"

# Fish
npx usertrust completions fish > ~/.config/fish/completions/usertrust.fish

Global Options

--json — Machine-readable JSON output for all commands

CLI Reference

Installation