Installation & Global Options - Crunch Protocol Documentation

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:

crunch-cli config show

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

“Wallet file not found”

# 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

If the Python CLI is not installed, crunch-cli model commands will prompt you to install it.

​Installation

​Command Structure

​Global Options

​Network & Connection

​Output & Logging

​Execution Control

​Usage Examples

​Configuration

​Config Commands

​Default Configuration

​Valid Network Values

​Option Precedence

​Security Considerations

​Wallet Security

​Network Verification

​Troubleshooting

​Common Issues

​Debug Mode

​Python Model Bridge

Installation

Command Structure

Global Options

Network & Connection

Output & Logging

Execution Control

Usage Examples

Configuration

Config Commands

Default Configuration

Valid Network Values

Option Precedence

Security Considerations

Wallet Security

Network Verification

Troubleshooting

Common Issues

Debug Mode

Python Model Bridge