FrostDAO CLI Reference

Complete reference for all CLI commands.

Installation

cargo install --path .
frostdao --help

Key Management

btc-keygen

Generate a new Bitcoin Schnorr keypair (BIP340).

frostdao btc-keygen

Output:

Public key (32-byte x-only, hex)
Keypair saved to .frost_state/bitcoin_keypair.json

btc-import-key

Import an existing secret key.

frostdao btc-import-key --secret <hex>

Parameters:

Parameter	Description
`--secret`	32-byte secret key in hex (64 chars)

btc-pubkey

Display the stored public key.

frostdao btc-pubkey

Address Commands

btc-address

Get mainnet Taproot address (bc1p...).

frostdao btc-address

btc-address-testnet

Get testnet Taproot address (tb1p...).

frostdao btc-address-testnet

btc-address-signet

Get signet Taproot address (tb1p...).

frostdao btc-address-signet

dkg-address

Get the DKG group Taproot address on testnet. Without --name, lists all wallets.

frostdao dkg-address [--name <wallet_name>]

Parameters:

Parameter	Description
`--name`	Wallet/session name; optional

Requires: Completed DKG (keygen-finalize)

dkg-balance

Check DKG group wallet balance on testnet. Without --name, lists all wallets.

frostdao dkg-balance [--name <wallet_name>]

Parameters:

Parameter	Description
`--name`	Wallet/session name; optional

Output:

DKG group address
Total/Confirmed balance
UTXO details
Note about threshold signature requirements

Requires: Completed DKG (keygen-finalize)

Transaction Commands

btc-balance

Check testnet balance and UTXOs (single-signer wallet).

frostdao btc-balance

Output:

Network
Address
Total/Confirmed balance
UTXO details

btc-send

Send Bitcoin on testnet.

frostdao btc-send --to <address> --amount <sats> [--fee-rate <sats/vbyte>]

Parameters:

Parameter	Description	Required
`--to`	Recipient Taproot address	Yes
`--amount`	Amount in satoshis	Yes
`--fee-rate`	Fee rate (sats/vbyte)	No (default: recommended)

Example:

frostdao btc-send \
  --to tb1p3e44guscrytuum9q36tlx5kez9zvdheuwxlq9k9y4kud3hyckhtq63fz34 \
  --amount 10000 \
  --fee-rate 2

btc-send-signet

Send Bitcoin on signet.

frostdao btc-send-signet --to <address> --amount <sats> [--fee-rate <sats/vbyte>]

Signing Commands

btc-sign

Sign a UTF-8 message with BIP340 Schnorr.

frostdao btc-sign --message "Hello, Bitcoin!"

btc-sign-hex

Sign a hex-encoded message.

frostdao btc-sign-hex --message <hex_data>

btc-sign-taproot

Sign a Taproot sighash (32 bytes).

frostdao btc-sign-taproot --sighash <hex>

policy-compile

Compile and inspect a Taproot Miniscript policy.

This command is available only with the optional miniscript-policy feature.

cargo run --features miniscript-policy -- policy-compile \
  --policy 'thresh(2,pk(A),pk(B),pk(C))' \
  --internal-key INTERNAL

Output: JSON with normalized policy, Taproot descriptor, descriptor type, SegWit version, sanity-check status, and scope warning.

btc-verify

Verify a BIP340 signature.

frostdao btc-verify \
  --signature <64_byte_hex> \
  --public-key <32_byte_hex> \
  --message "Hello, Bitcoin!"

btc-verify-hex

Verify with hex-encoded message.

frostdao btc-verify-hex \
  --signature <hex> \
  --public-key <hex> \
  --message <hex>

DKG Commands

keygen-round1

Generate polynomial and commitments for DKG.

frostdao keygen-round1 \
  --name <wallet_name> \
  --threshold <t> \
  --n-parties <n> \
  --my-index <i> \
  [--rank <r>] \
  [--hierarchical]

Parameters:

Parameter	Description	Default
`--name`	Wallet/session name (creates folder)	Required
`--threshold`	Minimum signers required	Required
`--n-parties`	Total number of parties	Required
`--my-index`	Your party index (1-based)	Required
`--rank`	HTSS rank (0=highest)	0
`--hierarchical`	Enable HTSS mode	false

Safety: If a wallet with the same name exists, you'll be prompted to confirm replacement.

Examples:

# Standard TSS (2-of-3)
frostdao keygen-round1 --name treasury --threshold 2 --n-parties 3 --my-index 1

# HTSS (3-of-4 with ranks)
frostdao keygen-round1 --name corp_wallet --threshold 3 --n-parties 4 --my-index 1 --rank 0 --hierarchical

keygen-round2

Exchange encrypted shares.

frostdao keygen-round2 --name <wallet_name> --data '<json>' [--encrypt]

Parameters:

Parameter	Description
`--name`	Wallet/session name (must match round1)
`--data`	JSON with all round1 commitments
`--encrypt`	Enable NIP-44 end-to-end encryption for shares

keygen-finalize

Finalize DKG and derive keys.

frostdao keygen-finalize --name <wallet_name> --data '<json>'

Parameters:

Parameter	Description
`--name`	Wallet/session name (must match round1)
`--data`	JSON with all round2 shares

Output:

Group public key
Your secret share
HTSS metadata (if hierarchical)
group_info.json with parties ordered by rank

Threshold Signing Commands

generate-nonce

Generate a signing nonce for a session.

frostdao generate-nonce --session "tx-001"

Important: Never reuse session IDs!

sign

Create a signature share.

frostdao sign \
  --session "tx-001" \
  --message "data to sign" \
  --data '<nonces_json>'

Input Format:

{
  "nonces": [
    {"index": 1, "nonce": "..."},
    {"index": 2, "nonce": "..."}
  ],
  "public_key": "..."
}

combine

Combine signature shares into final signature.

frostdao combine --data '<signature_shares_json>'

verify

Verify a threshold signature.

frostdao verify \
  --signature <hex> \
  --public-key <hex> \
  --message "signed message"

Resharing Commands

reshare-round1

Generate sub-shares for new parties (run by old parties).

frostdao reshare-round1 \
  --source <wallet_name> \
  --new-threshold <t> \
  --new-n-parties <n> \
  --my-index <i>

Parameters:

Parameter	Description
`--source`	Source wallet name
`--new-threshold`	New threshold for reshared wallet
`--new-n-parties`	New total number of parties
`--my-index`	Your party index in the original wallet

reshare-finalize

Combine sub-shares to create new wallet (run by new parties).

frostdao reshare-finalize \
  --source <old_wallet> \
  --target <new_wallet> \
  --my-index <i> \
  [--rank <r>] \
  [--hierarchical] \
  --data '<round1_outputs_json>'

Parameters:

Parameter	Description
`--source`	Source wallet name (for metadata)
`--target`	New wallet name to create
`--my-index`	Your new party index
`--rank`	Your HTSS rank; default `0`
`--hierarchical`	Enable HTSS mode
`--data`	JSON with round1 outputs from old parties

Share Recovery Commands

recover-round1

Helper party generates sub-share for a lost party.

frostdao recover-round1 \
  --name <wallet_name> \
  --lost-index <i>

Parameters:

Parameter	Description
`--name`	Wallet name
`--lost-index`	Index of the party who lost their share

Output: JSON with helper_index, lost_index, sub_share, rank

recover-finalize

Lost party combines sub-shares to recover their share.

frostdao recover-finalize \
  --source <wallet_name> \
  --target <new_wallet> \
  --my-index <i> \
  [--rank <r>] \
  [--hierarchical] \
  --data '<sub_shares_json>'

Parameters:

Parameter	Description	Default
`--source`	Source wallet name (for metadata)	Required
`--target`	New wallet name to create	Required
`--my-index`	Your party index (the one being recovered)	Required
`--rank`	Your HTSS rank	0
`--hierarchical`	Enable hierarchical mode	false
`--data`	JSON with sub-shares from helper parties	Required

Note: For HTSS wallets with mixed ranks, uses Birkhoff interpolation.

DKG Transaction Commands

dkg-build-tx

Build an unsigned transaction for DKG threshold signing.

frostdao dkg-build-tx \
  --name <wallet_name> \
  --to <recipient_address> \
  --amount <satoshis> \
  [--fee-rate <sats_per_vbyte>] \
  [--network testnet|testnet3|testnet4|test4|signet|regtest|local|mainnet]

Parameters:

Parameter	Description	Default
`--name`	DKG wallet name	Required
`--to`	Recipient Taproot address	Required
`--amount`	Amount in satoshis	Required
`--fee-rate`	Fee rate (sats/vbyte)	Auto
`--network`	Bitcoin network. `testnet` means testnet3; `testnet4`/`test4` selects testnet4. For `regtest`/`local`, set `FROSTDAO_REGTEST_MEMPOOL_API` to a local Esplora/mempool API endpoint.	`testnet`

Output: JSON with session_id, sighash, unsigned_tx, and review.

The review object contains the network, source path, source address, destination address, amount, fee, fee rate, and a short sighash_fingerprint for cross-device comparison before signing.

dkg-nonce

Generate a signing nonce for DKG transaction.

frostdao dkg-nonce \
  --name <wallet_name> \
  --session <session_id>

Parameters:

Parameter	Description
`--name`	DKG wallet name
`--session`	Session ID from dkg-build-tx

Output: JSON with nonce data for this party

dkg-sign

Create a signature share for DKG transaction.

frostdao dkg-sign \
  --name <wallet_name> \
  --session <session_id> \
  --sighash <hex> \
  --data '<nonces_json>'

Parameters:

Parameter	Description
`--name`	DKG wallet name
`--session`	Session ID
`--sighash`	Transaction sighash (32-byte hex)
`--data`	JSON array of nonces from all signers

Output: JSON with signature share

dkg-broadcast

Combine signature shares and broadcast transaction.

frostdao dkg-broadcast \
  --name <wallet_name> \
  --session <session_id> \
  --unsigned-tx <hex> \
  --data '<signature_shares_json>' \
  [--network testnet|testnet3|testnet4|test4|signet|regtest|local|mainnet]

Parameters:

Parameter	Description
`--name`	DKG wallet name
`--session`	Session ID
`--unsigned-tx`	Unsigned transaction hex from dkg-build-tx
`--data`	JSON array of signature shares
`--network`	Bitcoin network. `testnet` means testnet3; `testnet4`/`test4` selects testnet4. For `regtest`/`local`, set `FROSTDAO_REGTEST_MEMPOOL_API`

Output: JSON with txid and broadcast status

HD Derivation Commands

dkg-derive-address

Derive a single HD address. The output includes the BIP-86 path, derived address, child x-only public key, and a short child key fingerprint for multi-device comparison.

frostdao dkg-derive-address \
  --name <wallet_name> \
  --index <n> \
  --network <testnet|testnet3|testnet4|test4|signet|regtest|local|mainnet>

dkg-list-addresses

List derived HD addresses. Each row includes a child key fingerprint so signers can confirm the same threshold-controlled child key across devices.

frostdao dkg-list-addresses \
  --name <wallet_name> \
  --count <n> \
  --network <testnet|testnet3|testnet4|test4|signet|regtest|local|mainnet>

dkg-generate-mnemonic

Generate 24-word backup for your local share and print a public backup manifest.

frostdao dkg-generate-mnemonic --name <wallet_name>

The mnemonic is secret. The manifest is public metadata that binds the mnemonic to wallet name, party index, rank, threshold, party-rank map, group public key, public shared-key polynomial, and address fingerprints.

dkg-verify-mnemonic

Verify a written share mnemonic against the local wallet backup manifest.

frostdao dkg-verify-mnemonic --name <wallet_name> --words '<24 words>'

Parameters:

Parameter	Description
`--name`	Wallet name
`--words`	24-word mnemonic in quotes

Checks: BIP-39 checksum, share fingerprint, wallet metadata, party index, rank, party-rank map, group public key, public shared-key polynomial, and backup ID.

This command verifies the written words but does not restore wallet files.

dkg-restore-mnemonic

Restore local wallet files from a 24-word share mnemonic and the public backup manifest.

frostdao dkg-restore-mnemonic --name <wallet_name> --words '<24 words>' --manifest backup-manifest.json

The command refuses to overwrite an existing .frost_state/<wallet_name> directory. It verifies the mnemonic against the manifest, pairs the share against the public FROST polynomial, checks root addresses, and writes the standard local wallet files.

Wallet Management

dkg-list

List all DKG wallets.

frostdao dkg-list

dkg-info

Regenerate group_info.json.

frostdao dkg-info --name <wallet_name>

tui

Launch interactive Terminal UI.

frostdao tui

Storage Locations

DKG wallets stored in ~/.frostdao/wallets/:

~/.frostdao/
└── wallets/
    └── <wallet_name>/
        ├── shared_key.bin           # Group public key
        ├── hd_metadata.json         # HD derivation info
        ├── party1/
        │   ├── paired_secret_share.bin  # Party 1 secret
        │   └── htss_metadata.json       # Party 1 config
        ├── party2/
        │   └── ...
        └── party3/
            └── ...

group_info.json

Generated after keygen-finalize, contains public info sorted by rank:

{
  "name": "treasury",
  "group_public_key": "35a3e7ff...",
  "taproot_address_testnet": "tb1p...",
  "taproot_address_mainnet": "bc1p...",
  "threshold": 2,
  "total_parties": 3,
  "hierarchical": false,
  "parties": [
    {"index": 1, "rank": 0, "verification_share": "..."},
    {"index": 2, "rank": 0, "verification_share": "..."},
    {"index": 3, "rank": 0, "verification_share": "..."}
  ]
}

Exit Codes

Code	Meaning
0	Success
1	Error (see message)

Environment

Keys stored in .frost_state/ (gitignored)
Network API: mempool.space
Testnet faucet: https://bitcoinfaucet.uo1.net/

FilesExpand file tree

CLI.md

Latest commit

History

CLI.md

File metadata and controls

FrostDAO CLI Reference

Installation

Key Management

btc-keygen

btc-import-key

btc-pubkey

Address Commands

btc-address

btc-address-testnet

btc-address-signet

dkg-address

dkg-balance

Transaction Commands

btc-balance

btc-send

btc-send-signet

Signing Commands

btc-sign

btc-sign-hex

btc-sign-taproot

policy-compile

btc-verify

btc-verify-hex

DKG Commands

keygen-round1

keygen-round2

keygen-finalize

Threshold Signing Commands

generate-nonce

sign

combine

verify

Resharing Commands

reshare-round1

reshare-finalize

Share Recovery Commands

recover-round1

recover-finalize

DKG Transaction Commands

dkg-build-tx

dkg-nonce

dkg-sign

dkg-broadcast

HD Derivation Commands

dkg-derive-address

dkg-list-addresses

dkg-generate-mnemonic

dkg-verify-mnemonic

dkg-restore-mnemonic

Wallet Management

dkg-list

dkg-info

tui

Storage Locations

group_info.json

Exit Codes

Environment