This project has been discontinued in favor of official Vultisig tools. Please use the official alternatives below.

A standalone cross-platform Go CLI tool for managing .vult vault file operations, compatible with Vultisig security models.

This tool has been superseded by official Vultisig tools with superior functionality and active support.

Use these official Vultisig tools instead:

Comprehensive Rust CLI with MPC signing capabilities

• Full 2-of-2 threshold signature support
• TypeScript integration packages
• WebSocket daemon architecture
• Production-ready with comprehensive documentation

TypeScript SDK for developers

• Complete API for vault creation and management
• Multi-chain support (40+ blockchains)
• Fast and Secure vault modes
• Full CI/CD implementation

Web-based recovery tool

• GG20 and DKLS support
• Private key reconstruction
• User-friendly web interface
• Equivalent functionality to vultool's recovery features

The following documentation is preserved for reference and educational purposes.

Major Milestone in v0.2.0-dev - August 2025:

• Centralized Address Derivation: Recovery now uses same logic as list-addresses for 100% consistency
• 19-Chain Support: Full recovery for Bitcoin, Ethereum, and all 19 supported blockchain addresses
• Automatic Validation: Every recovery is validated against expected vault addresses
• Perfect Address Match: 19/19 chains pass validation (100% success rate)
• Chain Name Consistency: Standardized naming across all commands and functions
• GG20 TSS Recovery: Full implementation with mathematically correct Lagrange interpolation
• Multi-Algorithm Support: Both ECDSA and EdDSA key reconstruction working
• Production Ready: All recovered addresses match exactly what users see in Vultisig UI

See GG20 Recovery Status » | Technical Documentation »

# Clone and build vultool
git clone https://github.com/rowbotony/vultool.git
cd vultool && make build

# Inspect a vault file (try with our test fixtures)
./vultool inspect -f test/fixtures/testGG20-part1of2.vult --summary

# Export vault metadata to JSON
./vultool inspect -f your-vault.vult --export vault-metadata.json

Sample Output:

Vault: Test private key vault
File: test/fixtures/testGG20-part1of2.vult
Encrypted: false
Version: 0
Local Party: Pixel 5a-a9b
ECDSA Public Key: 0267db81657a956f364167c3986a426b448a74ac0db2092f6665c4c202b37f6f1d
Key Shares: 2

Vultool is a standalone command-line interface that focuses specifically on .vult file operations. It provides a clean, focused tool for inspecting, validating, and working with Vultisig vault files.

• Vault Inspection: Parse and display vault metadata
• Validation: Comprehensive vault file validation
• Export: Export vault data to JSON and YAML formats
• Vault Comparison: Compare two vault files with detailed diff output
• TSS Key Recovery: Reconstruct private keys from threshold shares (NEW!)
• Multi-Chain Support: Bitcoin, Ethereum, Solana, THORChain key formats
• Command Aliases: Quick shortcuts for common operations
• Encryption Support: Handle both encrypted and unencrypted vaults
• Security: Built-in path validation and safety checks

Tip for debugging: to enable verbose internal logs, set VULTOOL_DEBUG=1 (default output is concise).

Requirements: Go 1.21+ (tested with Go 1.21-1.23)

go install will never work with vultool due to Go's security model. The Cosmos/TSS ecosystem requires replace directives to resolve upstream dependency conflicts, and Go prohibits go install on any module containing replace directives.

# Clone and build from source (recommended)
git clone https://github.com/rowbotony/vultool.git
cd vultool

# Linux/macOS - using make
make build

# Linux/macOS - using build script
./build.sh

# Windows - using PowerShell
.\build.ps1

# Or build manually with version injection
# Linux/macOS:
go build -ldflags "-X main.version=$(cat VERSION)" -o vultool ./cmd/vultool

# Windows PowerShell:
go build -ldflags "-X main.version=$(Get-Content VERSION)" -o vultool.exe ./cmd/vultool

# Verify installation
./vultool --version

This is the standard workflow in Cosmos development. The ecosystem has well-known upstream dependency conflicts that require replace directives. Rather than fighting Go's security boundaries, we embrace the professional approach used throughout the Cosmos ecosystem.

# Show concise vault information (alias for inspect --summary)
vultool info -f path/to/vault.vult

# Decode vault to JSON or YAML format
vultool decode -f path/to/vault.vult
vultool decode -f path/to/vault.vult --yaml

# Verify vault integrity (alias for inspect --validate)
vultool verify -f path/to/vault.vult

# Compare two vault files (New in v0.0.8)
vultool diff vault1.vult vault2.vult

# Inspect a vault file (shows summary by default)
vultool inspect -f path/to/vault.vult

# Show detailed summary
vultool inspect -f path/to/vault.vult --summary

# Show key share information
vultool inspect -f path/to/vault.vult --show-keyshares

# Validate vault structure
vultool inspect -f path/to/vault.vult --validate

# Or use the quick alias
vultool verify -f path/to/vault.vult

# Export vault metadata to JSON
vultool inspect -f path/to/vault.vult --export output.json

# Output JSON directly to stdout
vultool decode -f path/to/vault.vult

# Output YAML directly to stdout
vultool decode -f path/to/vault.vult --yaml

# Compare two vault files
vultool diff vault1.vult vault2.vult

# Compare with password support for encrypted vaults
vultool diff --password mypass vault1.vult vault2.vult

# List all blockchain addresses derived from vault
vultool list-addresses --vault path/to/vault.vult

# Show addresses in JSON format
vultool list-addresses --vault path/to/vault.vult --json

# Filter specific chains only
vultool list-addresses --vault path/to/vault.vult --chains Bitcoin,Ethereum

# Export to CSV format
vultool list-addresses --vault path/to/vault.vult --csv

# Show common derivation paths for supported chains
vultool list-paths

# Show paths in JSON format for integration
vultool list-paths --json

# Filter paths for specific chains
vultool list-paths --chains bitcoin,ethereum,solana

Note: In human-readable output, UTXO chains (Bitcoin, Litecoin, Dogecoin, Dash, Zcash, Bitcoin Cash) include chain-specific WIF plus a brief wallet import hint. JSON/CSV outputs remain unchanged.

EdDSA wallet imports (Solana/SUI): please read the limitations and workflows in TSS Wallet Limitations — seed‑based wallets may reject TSS keypairs or show a different address.

Note: In human-readable output, UTXO chains (Bitcoin, Litecoin, Dogecoin, Dash, Zcash, Bitcoin Cash) include chain-specific WIF plus a brief wallet import hint. JSON/CSV outputs remain unchanged.

# Recover private keys from threshold shares (with automatic validation)
# Optional: verify private keys match addresses
vultool recover share1.vult share2.vult --threshold 2 --verify-private-keys
vultool recover share1.vult share2.vult --threshold 2

# Recovery automatically validates all 19 chains against list-addresses:
# bitcoin address validation passed: bc1qvn203p8pp30fk945eywrjey937qpaanha8hc4r
# ethereum address validation passed: 0x55a7ea16a40f8c908cbc935d229ebe4c6658e90d
# GG20 recovery validation passed - all 19 addresses match list-addresses

# Recover only specific blockchain keys
vultool recover share*.vult --threshold 2 --chain bitcoin

# Export recovered keys to JSON file with full validation
vultool recover share*.vult --threshold 2 --output keys.json

# Recover with password-protected vaults
vultool recover encrypted*.vult --threshold 2 --password mypassword

Recovery Features:

• 100% Address Accuracy: All recovered addresses match exactly what list-addresses shows
• Automatic Validation: Every recovery is validated against expected vault addresses
• 19-Chain Support: Bitcoin, Ethereum, BSC, Avalanche, Polygon, Arbitrum, Optimism, Base, Blast, ZkSync, THORChain, Litecoin, Dogecoin, Dash, Zcash, Bitcoin Cash, Solana, SUI
• Wallet Import Formats: Solana JSON array format, SUI base64 format, comprehensive wallet compatibility documentation
• TSS Wallet Integration: See TSS Wallet Limitations Guide for wallet import workflows and solutions
• Centralized Logic: Uses same address derivation as list-addresses for perfect consistency

# Interactive password prompt
vultool inspect -f encrypted-vault.vult

# Provide password as parameter
vultool inspect -f encrypted-vault.vult --password mypassword

Vultool can also be used as a Go library:

package main

import (
    "fmt"
    "github.com/rowbotony/vultool/pkg/client"
)

func main() {
    vaultInfo, err := client.ParseVaultFile("path/to/vault.vult")
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Vault: %s\n", vaultInfo.Name)
    fmt.Printf("Encrypted: %t\n", vaultInfo.IsEncrypted)
}

• cmd/vultool/: CLI entry point
• internal/vault/: Core vault parsing and validation logic
• pkg/client/: Public API for library usage

• Vultisig commondata: Official protobuf schemas
• Cobra: CLI framework (industry standard)
• Go crypto libraries: AES-GCM encryption support

# Clone and build
git clone https://github.com/rowbotony/vultool.git
cd vultool

# Initialize submodules (required for test fixtures)
git submodule init
git submodule update

# Install dependencies
go mod tidy

# Install development tools (required for linting and CI)
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0

# Ensure Go bin directory is in your PATH (add to ~/.bashrc, ~/.zshrc, etc.)
export PATH=$PATH:$(go env GOPATH)/bin

# Build using make (Linux/macOS)
make build

# Build using scripts
./build.sh              # Linux/macOS
.\build.ps1            # Windows PowerShell

# Build manually
# Linux/macOS:
go build -ldflags "-X main.version=$(cat VERSION)" -o vultool ./cmd/vultool

# Windows PowerShell:
go build -ldflags "-X main.version=$(Get-Content VERSION)" -o vultool.exe ./cmd/vultool

# Test with shared fixtures
./vultool inspect -f test/fixtures/testGG20-part1of2.vult --summary

# Run tests
go test ./...

Robust automated pipeline with multi-platform builds and comprehensive quality gates:

• Platforms: Linux (amd64/arm64), macOS (amd64/arm64), Windows (amd64)
• Security: gosec, govulncheck, CodeQL, automated dependency updates
• Quality: Tests across Go 1.21-1.23, comprehensive linting, automated fixture validation
• Reliability: Zero-intervention CI with encrypted test file handling

# Run full CI locally (includes all checks)
make ci-local

# Individual components
make lint          # Code quality checks
make security-scan # Security vulnerability scanning  
make validate      # Test fixture validation (handles encrypted files automatically)

# Create release (automated binary builds)
echo "1.0.0" > VERSION && git tag v1.0.0 && git push --tags

New in v0.1.0: CI pipeline now handles encrypted test fixtures automatically without hanging, ensuring reliable automated builds and deployments.

Note: Linting is temporarily disabled in CI (v0.2.0-dev) to maintain development velocity. All linting issues will be resolved in v0.2.1-dev before pushing to origin.

See docs/CI-CD.md for details.

Vultool includes several security features:

• Path validation to prevent directory traversal
• Safe output path validation
• Secure handling of encrypted vaults
• Memory-safe cryptographic operations

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

We welcome contributions!

To get started:

1. Read our Contributing Guidelines for detailed setup and workflow information
2. Check existing Issues for tasks that need help

Quick Start for Contributors:

git clone https://github.com/YOUR_USERNAME/vultool.git
cd vultool && git submodule update --init
make ci-local  # Run full test suite

For major changes, please open an issue first to discuss what you would like to change.

New to OSS? We're happy to help! Look for issues labeled good first issue.