The Crunch Protocol CLI (@crunchdao/cli) is a unified command-line interface for the Crunch Protocol, covering Coordinator management, Cruncher operations, competition lifecycle, staking, and model tools.
Installation
npm install -g @crunchdao/cli
Requires Node.js 16 or higher. For Python model tools, also install pip install crunch-cli.
Command Structure
The CLI is organized by functional domains:
crunch-cli <domain> <command> [options] [arguments]
| Domain | Description |
|---|
coordinator | Coordinator registration & management |
crunch | Competition (crunch) lifecycle management |
cruncher | Participant operations (registration, models, claiming) |
staking | Token staking, delegation, and rewards |
model | Python model & simulation tools (requires crunch-cli Python package) |
config | Global configuration management |
Global Options
These options can be used with any command and override configuration file values:
Network & Connection
| Option | Description | Default |
|---|
-n, --network <network> | Solana network (mainnet-beta, testnet, devnet, localhost) | devnet |
-u, --url <url> | Custom RPC URL (overrides --network) | — |
-w, --wallet <path> | Path to wallet keypair file | — |
-m, --multisig <address> | Squads multisig address for proposals | — |
Output & Logging
| Option | Description | Default |
|---|
-o, --output <format> | Output format (json, table, yaml) | table |
-v, --verbose | Enable verbose logging | false |
-q, --quiet | Suppress non-essential output | false |
Execution Control
| Option | Description | Default |
|---|
--dry-run | Preview what would be executed without running | false |
--timeout <seconds> | Command timeout in seconds | 60 |
-c, --config <path> | Path to custom config file | — |
Usage Examples
# Use default configuration
crunch-cli coordinator register "My Organization"
# Override network for a single command
crunch-cli coordinator register "My Organization" --network devnet
# Use JSON output
crunch-cli crunch list --output json
# Use custom RPC endpoint
crunch-cli coordinator get --url https://my-rpc.example.com
# Execute with multisig proposal
crunch-cli coordinator register "My Org" --multisig 7x8yF...3k9L
# Dry run to preview
crunch-cli crunch create "my_competition" 1000 --dry-run
Configuration
The CLI stores global configuration at ~/.crunch/config.json. Use the config commands to manage settings instead of passing flags every time.
Config Commands
# Set default network
crunch-cli config set network devnet
# Set default wallet
crunch-cli config set wallet ~/.config/solana/devnet.json
# Set custom RPC URL
crunch-cli config set rpc-url https://my-rpc.example.com
# Set default output format
crunch-cli config set output json
# View current configuration
crunch-cli config show
# Validate configuration
crunch-cli config validate
# Remove a config value
crunch-cli config unset wallet
# Reset all config to defaults
crunch-cli config reset --confirm
Default Configuration
{
"network": "devnet",
"output": "table",
"timeout": 60,
"verbose": false
}
Valid Network Values
| Network | Endpoint | Use Case |
|---|
localhost | http://127.0.0.1:8899 | Local development and testing |
devnet | https://api.devnet.solana.com | Staging and integration testing |
testnet | https://api.testnet.solana.com | Pre-production testing |
mainnet-beta | https://api.mainnet-beta.solana.com | Production deployment |
Option Precedence
Configuration values are resolved in this order (highest to lowest priority):
- Command-line flags (e.g.,
--network devnet)
- Config file values (
~/.crunch/config.json)
- Built-in defaults
Security Considerations
Wallet Security
- Store keypair files in secure, encrypted locations
- Use appropriate file permissions:
chmod 600 wallet.json
- Never commit wallet files to version control
- Use different wallets for different environments
Network Verification
Always verify your configuration before critical operations:
Troubleshooting
Common Issues
“Insufficient SOL for transaction”
# Check wallet balance
solana balance --keypair path/to/wallet.json
# Airdrop SOL on devnet
solana airdrop 2 --keypair path/to/wallet.json --url devnet
# Check your configured wallet path
crunch-cli config show
# Validate configuration
crunch-cli config validate
Debug Mode
Enable verbose output to troubleshoot issues:
# Temporary verbose mode
crunch-cli coordinator get-config --verbose
# Permanent verbose mode
crunch-cli config set verbose true
Python Model Bridge
The model domain delegates to the Python crunch-cli companion:
# Install Python companion
pip install crunch-cli
# Use model commands
crunch-cli model list
crunch-cli model run baseline
crunch-cli model validate scenario.yaml
crunch-cli model commands will prompt you to install it. 
