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:
npm install -g @tova/cli| Environment variable | Default | Description |
|---|---|---|
TOVA_API_URL | http://127.0.0.1:37402 | Base 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 }.
tova statustova vault
Inspects Shielded Ring Vaults and their encrypted notes.
| Command | Flags | Description |
|---|---|---|
tova vault [list] | --principal <pubkey> | Lists vaults, optionally filtered by principal address |
tova vault get <vaultAddress> | none | Prints VaultDetail including merkleRoot, noteCount, and notes[] |
tova vault list --principal 7xKXt...
tova vault get 9pQwR...tova mandate
Inspects Shielded Mandates and their active status, ceilings, and epoch state.
| Command | Flags | Description |
|---|---|---|
tova mandate [list] | --vault <vaultPda>, --agent <agentPubkey> | Lists mandates with optional vault or agent filters |
tova mandate get <mandateAddress> | none | Prints a single MandateItem |
tova mandate list --vault 9pQwR...
tova mandate get 4mNvZ...tova provider
Inspects registered TEE providers, attestation expiry slots, and capacity utilization.
| Command | Flags | Description |
|---|---|---|
tova provider [list] | none | Lists all registered providers |
tova provider get <providerAddress> | none | Prints a single ProviderItem by PDA or providerPubkey |
tova provider list
tova provider get 6rTyU...tova settle
Lists Atomic 402 Escrows or runs a live shielded HTTP 402 settlement via TovaClient.pay402().
| Command | Flags | Description |
|---|---|---|
tova settle [list] | none | Lists 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"
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().
| Command | Flags | Description |
|---|---|---|
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.
tova decrypt eyJhbW91bnRMYW1wb3J0cyI6IjUwMDAwMDAwIn0= --key <64-hex-char-viewing-key>