> ## Documentation Index
> Fetch the complete documentation index at: https://protocol.crunchdao.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation & Global Options

> Install the Crunch Protocol CLI and configure global options for all commands.

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

```bash theme={null}
npm install -g @crunchdao/cli
```

<Info>
  Requires Node.js 16 or higher. For Python model tools, also install `pip install crunch-cli`.
</Info>

## Command Structure

The CLI is organized by functional domains:

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```json theme={null}
{
  "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):

1. **Command-line flags** (e.g., `--network devnet`)
2. **Config file values** (`~/.crunch/config.json`)
3. **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:

```bash theme={null}
crunch-cli config show
```

## Troubleshooting

### Common Issues

**"Insufficient SOL for transaction"**

```bash theme={null}
# 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"**

```bash theme={null}
# Check your configured wallet path
crunch-cli config show

# Validate configuration
crunch-cli config validate
```

### Debug Mode

Enable verbose output to troubleshoot issues:

```bash theme={null}
# 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:

```bash theme={null}
# 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.