Crunch Protocol CLI Skill

Translates natural language queries into crunch-cli commands. Supports profiles and output formatting for Slack, Telegram, Discord, or plain text.

Prerequisites

Node.js 18+ with npm
Solana wallet keypair (for on-chain operations)

Package Installation

This skill installs packages via npm (global):

Package	Source	Purpose
`@crunchdao/crunch-cli`	npm	CrunchDAO protocol CLI (coordinators, competitions, staking)

Agent rules for package installation:

Only install @crunchdao/crunch-cli from the official npm registry
No custom registry URLs — no --registry overrides
Ask the user before installing if not already present

Credentials

Solana Wallet Keypair (required for on-chain operations)

What it is: A JSON file containing a Solana private key, used to sign transactions
How it's configured: Set via crunch-cli config set wallet /path/to/wallet.json or -w flag per command
Stored in: User-managed file on disk; path referenced in ~/.crunch/config.json

Agent rules for wallets:

Never create or generate wallet keypairs unless the user explicitly asks and understands the security implications
Never read or display the contents of wallet keypair files
Never commit wallet files to git — always verify .gitignore covers them
Ask the user for the wallet path — never assume or search for keypair files

Profile Config (`~/.crunch/config.json`)

Stores network, wallet path, and RPC URL per profile
Managed via crunch-cli config commands — no need to edit manually
Never modify or delete existing profiles unless explicitly asked

Setup

npm install -g @crunchdao/crunch-cli
crunch-cli --version

Profiles

The CLI has built-in profile management via ~/.crunch/config.json:

crunch-cli config show                    # Show current config
crunch-cli config active                  # Show resolved active values
crunch-cli config list-profiles           # List available profiles
crunch-cli config save-profile <name>     # Save current config as profile
crunch-cli config use <profile>           # Switch profile
crunch-cli config set <key> <value>       # Set config value

Global flags can override config per-command:

Flag	Description
`-n, --network`	Solana network: `mainnet-beta`, `devnet`, `localhost`
`-u, --url`	Custom RPC URL
`-w, --wallet`	Path to Solana keypair
`-o, --output`	Output format: `json`, `table`, `yaml`

Direct Phrase Mapping

User Phrase	CLI Command
`get/show crunch <name>`	`crunch-cli crunch get "<name>"`
`list crunches`	`crunch-cli crunch list`
`get/show coordinator [address]`	`crunch-cli coordinator get [address]`
`list coordinators`	`crunch-cli coordinator list`
`get config`	`crunch-cli coordinator get-config`
`checkpoint for <name>`	`crunch-cli crunch checkpoint-get-current "<name>"`
`create checkpoint <name>`	`crunch-cli crunch checkpoint-create "<name>" prizes.json`
`deposit reward <name> <amount>`	`crunch-cli crunch deposit-reward "<name>" <amount>`
`drain <name>`	`crunch-cli crunch drain "<name>"`
`create/register cruncher`	`crunch-cli cruncher create`
`register for <name>`	`crunch-cli cruncher register "<name>"`
`claim rewards <name>`	`crunch-cli cruncher claim "<name>"`
`show staking positions`	`crunch-cli staking positions`
`stake/deposit <amount>`	`crunch-cli staking deposit <amount>`
`delegate to <coordinator>`	`crunch-cli staking delegate "<coordinator>" <amount>`
`show staking rewards`	`crunch-cli staking rewards`
`claim staking rewards`	`crunch-cli staking claim`
`undelegate from <coordinator>`	`crunch-cli staking undelegate "<coordinator>" <amount>`
`withdraw stake <amount>`	`crunch-cli staking withdraw <amount>`
`init workspace <name>`	`crunch-cli init-workspace "<name>"`
`list scenarios/simulations`	`crunch-cli model list`
`run simulation <scenario>`	`crunch-cli model run "<scenario>"`
`register coordinator <name>`	`crunch-cli coordinator register "<name>"`
`create crunch <name>`	`crunch-cli crunch create "<name>" <amount> [maxModels]`
`start/end crunch <name>`	`crunch-cli crunch start/end "<name>"`

Execution Pattern

Parse — Identify action, target, name/identifier, parameters
Resolve profile — If mentioned, switch profile or use flags
Map — Use phrase mapping table
Execute — Run command
Format — Output for requested medium (Slack/Telegram/Discord/plain)

Error Handling

If command fails, suggest fixes:

Wrong network? Add -n mainnet-beta or -n devnet
Missing wallet? Add -w /path/to/wallet.json
Not found? List available with crunch-cli crunch list --all

Coordinator Node Setup

Scaffolding a local Crunch Workspace

Requires a pip dependency pip install coordinator-node
Prompt the user what type of challenge they are want to build
Instantiate a local crunch environment with a pack that fits best coordinator-node init my-challenge --pack trading
Guide the user through the implementation of the Crunch, asking follow up questions and explaining the context so the user can make good decisions.

Design checklist (collect before coding)

For every new challenge, confirm these points before implementation:

Model interface — tracker class that participants implement
Scoring function — how predictions are scored against actuals
Feed configuration — source, subjects, kind, granularity
Ground truth resolution — how actuals are derived from feed data
Emission config — crunch pubkey, provider wallets, tier distribution

If any are missing, ask follow-up questions before proceeding.

After scaffolding: customize and deploy

cd my-challenge/crunch-node-my-challenge
make deploy
make verify-e2e

Report API at http://localhost:8000

Working in a Coordinator Workspace

When you detect you are inside a coordinator node workspace (look for .agent/ folder, Agent.md file and CrunchConfig), load the project-specific agent context:

These files are the source of truth for how to operate in that workspace. They contain approval gates, allowed operations, and validation requirements specific to the project. Follow them.

Reference

For full CLI documentation: references/cli-reference.md

crunch-coordinate