CLI Reference

The ToldYa CLI (@toldya/cli) lets developers and power users create, reveal, and verify predictions from the terminal. It supports scripting and automation workflows.

Installation#

Build from source (the CLI is part of the ToldYa monorepo):

pnpm install
pnpm --filter @toldya/cli build
node packages/cli/dist/index.js --help

Or link it globally for the toldya command:

cd packages/cli && pnpm link --global

Global Options#

These flags apply to all commands:

--url <rpc-url>       RPC endpoint (default: $SOLANA_RPC_URL or mainnet)
--keypair <path>      Keypair file (default: ~/.config/solana/id.json)
--output json|text    Output format (default: text)
--dry-run             Build transaction but don't send

Commands#

commit#

Create a prediction commitment. The salt and message are saved locally for later reveal.

toldya commit --message "BTC hits 100k by 2025"

reveal#

Reveal a committed prediction using saved metadata from ~/.toldya/commits/.

toldya reveal <commit-pda>

close#

Close a commitment account and reclaim rent.

toldya close <commit-pda>

verify#

Verify a reveal payload offline. With --url, also checks on-chain state.

# Offline preimage verification
toldya verify payload.json

# Full on-chain verification
toldya verify payload.json --url https://api.devnet.solana.com

inspect#

Decode and display an on-chain ToldYa account (config or commit).

toldya inspect <address> --url https://api.devnet.solana.com
toldya inspect <address> --type config --output json

stake#

Stake against an existing commitment. Requires two keypairs: yours (--keypair) and the original committer (--committer-keypair).

toldya stake <commit-pda> --amount 1000000000 --committer-keypair ~/committer.json

vote#

Cast a resolution vote on a staked prediction.

toldya vote <escrow-pda> --vote self

resolve#

Execute resolution on a stake escrow after voting is complete (permissionless).

toldya resolve <escrow-pda> --counter-creator <addr> --committer <addr>

Commit-Reveal Workflow#

The typical workflow for a prediction:

# 1. Create commitment
toldya commit --message "ETH flips BTC by 2030" \
  --url https://api.devnet.solana.com

# 2. When ready, reveal the prediction
toldya reveal <commit-pda> --url https://api.devnet.solana.com

# 3. Share the reveal payload for verification
toldya verify ~/.toldya/commits/<id>-reveal.json \
  --url https://api.devnet.solana.com

Local Storage#

Commitment metadata (salt, message, PDA) is stored in ~/.toldya/commits/ as JSON files. Each file contains the secret preimage data needed to reveal the prediction later. Back up this directory — if you lose these files, you cannot reveal your commitments.