CLI Reference¶

PrimeStamp provides a command-line interface built with Typer and Rich. The CLI is available as primestamp (or the short alias ps) after installation.

primestamp --help

Global Usage¶

primestamp [COMMAND] [OPTIONS] [ARGUMENTS]

stamp¶

Create a document stamp.

primestamp stamp FILE [OPTIONS]

Arguments:

Argument	Description
`FILE`	Path to the file to stamp (required)

Options:

Option	Short	Default	Description
`--output`	`-o`	`FILE.stamp.json`	Output stamp file path
`--key`	`-k`	None	Identity key file for signing
`--preset`	`-p`	None	Preset: `casual`, `standard`, `archival`, `maximum`
`--anchors`	`-a`	`bitcoin,ethereum`	Comma-separated anchor types
`--version`	`-v`	`1.0.0`	Semantic version for the document
`--fingerprint`	`-f`	`False`	Generate Prime-Space fingerprint

Examples:

# Basic stamp with default anchors
primestamp stamp document.pdf

# Stamp with identity and preset
primestamp stamp document.pdf -k identity.json -p archival

# Custom anchors and output path
primestamp stamp paper.pdf -a bitcoin,ethereum,rfc3161 -o paper.stamp.json

# Include Prime-Space fingerprint
primestamp stamp thesis.pdf -k identity.json -p archival --fingerprint

# Stamp with version number
primestamp stamp contract.pdf -v 2.1.0 -k identity.json

verify¶

Verify a document stamp's integrity, signature, and optionally check content hash.

primestamp verify STAMP_FILE [OPTIONS]

Arguments:

Argument	Description
`STAMP_FILE`	Path to the stamp file to verify (required)

Options:

Option	Short	Description
`--file`	`-f`	Original document file to verify content hash against

Examples:

# Verify stamp structure and signature only
primestamp verify document.stamp.json

# Verify stamp AND content hash against original file
primestamp verify document.stamp.json -f document.pdf

Output: A table showing signature check, content hash check, trust score, and overall validity.

hash¶

Compute a cryptographic hash of a document.

primestamp hash FILE [OPTIONS]

Arguments:

Argument	Description
`FILE`	Path to the file to hash (required)

Options:

Option	Short	Default	Description
`--algorithm`	`-a`	`sha3-256`	Hash algorithm: `sha3-256`, `sha256`, `blake3`

Examples:

# Default SHA3-256
primestamp hash document.pdf

# BLAKE3 (faster for large files)
primestamp hash document.pdf -a blake3

# SHA-256 (Bitcoin-compatible)
primestamp hash document.pdf -a sha256

info¶

Display detailed information about a stamp.

primestamp info STAMP_FILE [OPTIONS]

Arguments:

Argument	Description
`STAMP_FILE`	Path to the stamp file to inspect (required)

Options:

Option	Description
`--json`	Output raw JSON instead of formatted display

Examples:

# Human-readable summary
primestamp info document.stamp.json

# Raw JSON output (useful for piping)
primestamp info document.stamp.json --json

presets¶

List all available configuration presets with their settings.

primestamp presets

Output: A table showing each preset's name, description, storage mode, encryption, anchors, and trust threshold.

identity generate¶

Generate a new Ed25519 signing identity.

primestamp identity generate [OPTIONS]

Options:

Option	Short	Default	Description
`--output`	`-o`	`identity.json`	Output key file path
`--force`	`-f`	`False`	Overwrite existing file

Examples:

# Generate with default filename
primestamp identity generate

# Custom output path
primestamp identity generate -o ~/.primestamp/my-identity.json

# Overwrite existing
primestamp identity generate -o identity.json --force

Protect your key file

The identity file contains your Ed25519 private key. Anyone with this file can sign stamps as you. Store it securely and back it up.

identity show¶

Display the public key from an identity file.

primestamp identity show KEY_FILE

Arguments:

Argument	Description
`KEY_FILE`	Path to the identity key file (required)

Examples:

primestamp identity show identity.json
primestamp identity show ~/.primestamp/my-identity.json

fingerprint generate¶

Generate a Prime-Space fingerprint for a document.

primestamp fingerprint generate FILE [OPTIONS]

Arguments:

Argument	Description
`FILE`	Path to the file to fingerprint (required)

Options:

Option	Short	Default	Description
`--output`	`-o`	None	Output fingerprint JSON file
`--method`	`-m`	`hierarchical`	Decomposition method: `hierarchical`, `flat`, `content_addressed`, `semantic`

Examples:

# Generate and display summary
primestamp fingerprint generate document.pdf

# Save to file
primestamp fingerprint generate document.pdf -o document.fingerprint.json

# Use flat decomposition
primestamp fingerprint generate document.pdf -m flat

fingerprint compare¶

Compare two documents using their Prime-Space fingerprints.

primestamp fingerprint compare FILE1 FILE2

Arguments:

Argument	Description
`FILE1`	First file to compare (required)
`FILE2`	Second file to compare (required)

Examples:

primestamp fingerprint compare original.pdf revised.pdf

Output: A table showing similarity at each shadow scale (2, 3, 5, 7, 11, 13) with percentage and assessment.

fingerprint shadows¶

Display the shadow transform of a document at a specific scale.

primestamp fingerprint shadows FILE [OPTIONS]

Arguments:

Argument	Description
`FILE`	Path to the file to analyze (required)

Options:

Option	Short	Default	Description
`--scale`	`-s`	`7`	Shadow scale to display (prime number: 2, 3, 5, 7, 11, 13)

Examples:

# Default scale (7)
primestamp fingerprint shadows document.pdf

# Fine-grained scale
primestamp fingerprint shadows document.pdf -s 2

# Coarse scale
primestamp fingerprint shadows document.pdf -s 13

init¶

Initialize PrimeStamp in a directory or git repository.

primestamp init [PATH] [OPTIONS]

Arguments:

Argument	Default	Description
`PATH`	`.` (current directory)	Directory to initialize

Options:

Option	Short	Default	Description
`--preset`		`standard`	Anchoring preset
`--wizard`	`-w`	`False`	Run interactive setup wizard

Examples:

# Initialize in current directory
primestamp init

# Initialize with archival preset
primestamp init --preset archival

# Interactive setup wizard
primestamp init --wizard

When run inside a git repository, this sets up git integration with hooks for automatic stamping.

anchor¶

Submit all pending stamps to blockchain anchors.

primestamp anchor [OPTIONS]

Options:

Option	Short	Description
`--force`	`-f`	Force anchor even if under cost threshold

Examples:

# Anchor with confirmation prompt
primestamp anchor

# Force anchor without prompt
primestamp anchor --force

status¶

Show PrimeStamp status for the current directory.

primestamp status

Displays the configuration, git integration status, pending stamps, and daily cost.

serve¶

Start the PrimeStamp API server with web dashboard.

primestamp serve [OPTIONS]

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8800`	Port to listen on
`--web`	`True`	Serve web dashboard
`--reload`	`False`	Enable auto-reload for development

Examples:

# Start with defaults (localhost:8800)
primestamp serve

# Public access on custom port
primestamp serve --host 0.0.0.0 --port 8080

# Development mode with auto-reload
primestamp serve --reload

After starting, the following endpoints are available:

API: http://host:port
OpenAPI docs: http://host:port/docs
Web dashboard: http://host:port/dashboard

ui¶

Launch the terminal user interface (TUI).

primestamp ui

Requires the textual package. Install with:

pip install 'primestamp[ui]'

vault create¶

Create a new vault for dead man's switch key escrow.

primestamp vault create [OPTIONS]

Options:

Option	Short	Default	Description
`--key-file`	`-k`	required	Path to the encrypted key file to escrow
`--deadline`	`-d`	`72h`	Heartbeat deadline (e.g. `24h`, `7d`, `168h`)
`--content-uri`	`-u`	None	Content URI (repeatable for multiple URIs)
`--manual-release`		`False`	Allow manual release by the vault owner
`--metadata`	`-m`	None	Metadata as `key=value` pairs (repeatable)

Examples:

# Create a vault with 72-hour deadline
primestamp vault create -k secret.key.enc -d 72h

# With multiple content URIs and manual release
primestamp vault create -k secret.key.enc -d 7d \
  -u ipfs://Qm... -u arweave://tx123 --manual-release

# With metadata
primestamp vault create -k secret.key.enc -d 48h -m label=project-keys -m env=production

vault heartbeat¶

Submit a heartbeat to extend a vault's deadline.

primestamp vault heartbeat VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to renew (required)

Options:

Option	Short	Description
`--fee-receipt`	`-r`	Transaction receipt for the mandatory fee

Examples:

primestamp vault heartbeat vault-a1b2c3d4... -r tx_receipt_abc123

vault batch-heartbeat¶

Submit heartbeats for multiple vaults in a single operation.

primestamp vault batch-heartbeat [OPTIONS] VAULT_ID [VAULT_ID...]

Arguments:

Argument	Description
`VAULT_ID`	One or more vault IDs (required)

Options:

Option	Short	Description
`--fee-receipt`	`-r`	Transaction receipt for the mandatory batch fee

Examples:

primestamp vault batch-heartbeat vault-aaa... vault-bbb... vault-ccc... -r tx_receipt_batch456

vault status¶

Display the current status of a vault.

primestamp vault status VAULT_ID

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to inspect (required)

Examples:

primestamp vault status vault-a1b2c3d4...

Output: A table showing the vault state, deadline, last heartbeat time, heartbeat count, content URIs, and metadata.

vault list¶

List vaults belonging to the current identity.

primestamp vault list [OPTIONS]

Options:

Option	Short	Default	Description
`--state`	`-s`	None	Filter by state: `active`, `released`, `burned`, `expired`
`--limit`	`-l`	`50`	Maximum number of results
`--offset`		`0`	Pagination offset
`--json`		`False`	Output raw JSON instead of formatted table

Examples:

# List all vaults
primestamp vault list

# List only active vaults
primestamp vault list -s active

# JSON output for scripting
primestamp vault list --json

vault release¶

Manually release a vault's escrowed key. Only works if the vault was created with --manual-release.

primestamp vault release VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to release (required)

Options:

Option	Short	Description
`--reason`	`-r`	Reason for the release
`--force`	`-f`	Skip confirmation prompt

Examples:

# Release with confirmation prompt
primestamp vault release vault-a1b2c3d4... -r "Project handover"

# Force release without prompt
primestamp vault release vault-a1b2c3d4... -r "Emergency" --force

vault burn¶

Permanently destroy a vault and its escrowed key. This action is irreversible.

primestamp vault burn VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to burn (required)

Options:

Option	Short	Description
`--force`	`-f`	Skip confirmation prompt

Examples:

# Burn with confirmation prompt
primestamp vault burn vault-a1b2c3d4...

# Force burn without prompt
primestamp vault burn vault-a1b2c3d4... --force

vault history¶

Show the heartbeat and event history of a vault.

primestamp vault history VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to inspect (required)

Options:

Option	Short	Default	Description
`--limit`	`-l`	`20`	Maximum number of events to show
`--json`		`False`	Output raw JSON

Examples:

primestamp vault history vault-a1b2c3d4...
primestamp vault history vault-a1b2c3d4... -l 50 --json

vault deadline¶

Show or adjust the heartbeat deadline for a vault.

primestamp vault deadline VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault (required)

Options:

Option	Short	Description
`--set`	`-s`	New deadline duration (e.g. `48h`, `7d`)

Examples:

# Show current deadline
primestamp vault deadline vault-a1b2c3d4...

# Update deadline (requires heartbeat fee)
primestamp vault deadline vault-a1b2c3d4... --set 7d

vault group¶

Manage heartbeat groups for batch vault maintenance.

vault group create¶

primestamp vault group create [OPTIONS] VAULT_ID [VAULT_ID...]

Options:

Option	Short	Description
`--name`	`-n`	Group name (required)
`--interval`	`-i`	Heartbeat interval (e.g. `48h`, `7d`)

Examples:

primestamp vault group create -n production-vaults -i 48h vault-aaa... vault-bbb...

vault group list¶

primestamp vault group list

vault group show¶

primestamp vault group show GROUP_ID

vault group heartbeat¶

Submit a heartbeat for all vaults in a group.

primestamp vault group heartbeat GROUP_ID [OPTIONS]

Options:

Option	Short	Description
`--fee-receipt`	`-r`	Transaction receipt for the mandatory fee

Examples:

primestamp vault group heartbeat group-xyz789... -r tx_receipt_group123

vault fees¶

Display the current vault fee schedule.

primestamp vault fees

Output: A table showing the create fee, heartbeat fee, batch discount, and currency.

node start¶

Start a PrimeStamp vault node for monitoring and indexing.

primestamp node start [OPTIONS]

Options:

Option	Default	Description
`--host`	`127.0.0.1`	Host to bind to
`--port`	`8801`	Port to listen on
`--data-dir`	`~/.primestamp/node`	Node data directory
`--daemon`	`False`	Run as a background daemon

Examples:

# Start in foreground
primestamp node start

# Start as daemon on custom port
primestamp node start --port 9000 --daemon

node stop¶

Stop a running PrimeStamp node daemon.

primestamp node stop

node status¶

Show the status of the local PrimeStamp node.

primestamp node status

Output: Node uptime, number of watched vaults, indexed vaults, and connection status.

node watch¶

Subscribe the node to watch a specific vault for deadline warnings and events.

primestamp node watch VAULT_ID [OPTIONS]

Arguments:

Argument	Description
`VAULT_ID`	ID of the vault to watch (required)

Options:

Option	Short	Default	Description
`--warn-hours`	`-w`	`24`	Hours before deadline to trigger a warning

Examples:

primestamp node watch vault-a1b2c3d4...
primestamp node watch vault-a1b2c3d4... -w 48

node unwatch¶

Stop watching a vault.

primestamp node unwatch VAULT_ID

node index¶

Index all public vaults from the network into the local node database.

primestamp node index [OPTIONS]

Options:

Option	Short	Default	Description
`--full`	`-f`	`False`	Full re-index (otherwise incremental)

Examples:

# Incremental index
primestamp node index

# Full re-index
primestamp node index --full

node stats¶

Display aggregate vault statistics from the local node.

primestamp node stats [OPTIONS]

Options:

Option	Description
`--json`	Output raw JSON

Examples:

primestamp node stats
primestamp node stats --json

Output: Active vaults, total heartbeats, total releases, total burns, and fee totals.