Reference

tova CLI

Command reference for the tova CLI (@tova/cli): inspecting vaults, mandates, providers, running live 402 settlements, and decrypting receipts.

Installation and configuration

Install @tova/cli globally or in your workspace to expose the tova binary:

bash
npm install -g @tova/cli
Environment variableDefaultDescription
TOVA_API_URLhttp://127.0.0.1:37402Base URL of the Tova REST API targeted by every command

All commands write structured JSON to stdout on success, or print the error message to stderr and exit with code 1 on failure. Running tova with no arguments prints the command summary.

tova status

Fetches /health and /v1/protocol/stats in parallel and prints { health, stats }.

bash
tova status

tova vault

Inspects Shielded Ring Vaults and their encrypted notes.

CommandFlagsDescription
tova vault [list]--principal <pubkey>Lists vaults, optionally filtered by principal address
tova vault get <vaultAddress>nonePrints VaultDetail including merkleRoot, noteCount, and notes[]
bash
tova vault list --principal 7xKXt...
tova vault get 9pQwR...

tova mandate

Inspects Shielded Mandates and their active status, ceilings, and epoch state.

CommandFlagsDescription
tova mandate [list]--vault <vaultPda>, --agent <agentPubkey>Lists mandates with optional vault or agent filters
tova mandate get <mandateAddress>nonePrints a single MandateItem
bash
tova mandate list --vault 9pQwR...
tova mandate get 4mNvZ...

tova provider

Inspects registered TEE providers, attestation expiry slots, and capacity utilization.

CommandFlagsDescription
tova provider [list]noneLists all registered providers
tova provider get <providerAddress>nonePrints a single ProviderItem by PDA or providerPubkey
bash
tova provider list
tova provider get 6rTyU...

tova settle

Lists Atomic 402 Escrows or runs a live shielded HTTP 402 settlement via TovaClient.pay402().

CommandFlagsDescription
tova settle [list]noneLists settlements with commitments, nullifiers, and claim/refund status
tova settle pay402--url <endpoint>, --prompt <text>Executes a live shielded 402 call using the first available vault and active mandate, verifying the TEE receipt

Defaults for tova settle pay402:

  • --url: ${TOVA_API_URL}/api/demo-provider/infer
  • --prompt: "Summarize shielded 402 receipt verification"
bash
tova settle list
tova settle pay402 --prompt "Verify shielded HTTP 402 execution receipt"

tova decrypt

Decrypts a base64-encoded vault note or settlement encryptedReceipt locally using decryptViewingPayload().

CommandFlagsDescription
tova decrypt <ciphertextBase64>--key <viewingKeyHex32>, --ciphertext <base64>Prints the decrypted JSON payload to stdout

If --key is omitted, tova decrypt defaults to 64 zero hex characters (00...00) for localnet fixture receipts.

bash
tova decrypt eyJhbW91bnRMYW1wb3J0cyI6IjUwMDAwMDAwIn0= --key <64-hex-char-viewing-key>