Crunch Protocol CLI Skill

This skill translates natural language queries into crunch-cli CLI commands and formats outputs for various mediums.

Setup

Ensure the CLI is installed globally:

npm install -g @crunchdao/crunch-cli

Verify installation:

crunch-cli --version

Profiles

Profiles are stored in profiles.json (next to this file). Each profile maps a short name to a set of CLI flags so users can say things like "list crunches for m-jeremy" instead of typing full addresses every time.

Profile file format

{
  "profiles": {
    "m-jeremy": {
      "url": "https://mainnet.helius-rpc.com/?api-key=...",
      "wallet": "/path/to/keypair.json",
      "multisigAddress": "9WzDXwBbmkg8...",
      "coordinatorWallet": "5abc..."
    },
    "devnet": {
      "url": "devnet",
      "wallet": "/path/to/dev-keypair.json",
      "coordinatorWallet": ""
    }
  }
}

Profile fields → CLI flags

How to resolve a profile

When a user references a profile name:

1. Read profiles.json from the skill directory.
2. Look up the profile by name (case-insensitive match).
3. Map each non-empty field to its CLI flag (see table above).
4. Prepend the flags to whatever command is being built.

Example: User says "list crunches for m-jeremy"

1. Load profile mainnet-proposer → { url: "https://mainnet...", wallet: "/path/...", multisigAddress: "9WzDX..." }
2. Build: crunch-cli -u "https://mainnet..." -w "/path/..." -m "9WzDX..." crunches list

Example: User says "show coordinator for devnet"

1. Load profile devnet → { url: "devnet" }
2. Build: crunch-cli -u devnet coordinator get

Managing profiles

• Users can ask to add, update, or remove profiles. When they do, read the current profiles.json, apply the change, and write it back.
• If profiles.json doesn't exist yet, create it with the structure above.
• When a user says "set profile to m-jeremy" or "use profile m-jeremy", remember it for the rest of the conversation and apply those flags to all subsequent commands automatically.

Command Mapping Rules

IMPORTANT: Direct Phrase Mapping

For speed and consistency, map these phrases directly to CLI commands without LLM interpretation:

Name Extraction Rules

• When a crunch name is provided, wrap it in quotes in the CLI command
• Common competition names: Crunch, Competition, Tournament, Challenge

Execution Pattern

1. Parse the user request to identify:

   • The action (get, create, start, end, list, etc.)
   • The target (crunch, coordinator, checkpoint, etc.)
   • The name/identifier if applicable
   • Any additional parameters

2. Map to CLI command using the direct mapping table above

3. Execute the command:

   crunch-cli [options] <command> [arguments]
   

4. Format The output of the CLI should be kept as close as possible, except if the user told you to post process the data. But map the output for the specified medium (see Output Formatting below as reference to use)

Available Commands Reference

Coordinator Commands

Certificate Commands

Crunch Commands (Competition Management)

Checkpoint Commands

Global Options

• -u, --url <network> - Network: mainnet-beta, devnet, localhost (default: from config)
• -w, --wallet <path> - Wallet keypair file path
• -o, --output json - Output as JSON (useful for parsing)
• -m, --multisig <addr> - Create multisig proposal instead of direct execution

Output Formatting

Medium Detection

Detect output medium from user request:

• "for slack" / "slack format" → Slack
• "for telegram" / "telegram format" → Telegram
• "for discord" / "discord format" → Discord
• Default → Plain text / Markdown

Slack Format

*🏆 Crunch: Synth*
━━━━━━━━━━━━━━━━━
• *Status:* Active
• *Participants:* 142
• *Prize Pool:* 10,000 USDC
• *Checkpoint:* 5
* *Funds:* 3000USDC

Telegram Format

🏆 <b>Crunch: Synth</b>

📊 Status: Active
👥 Participants: 142  
💰 Prize Pool: 10,000 USDC
📍 Checkpoint: 5
💰 Funds: 3000USDC

Discord Format

## 🏆 Crunch: Synth
**Status:** Active
**Participants:** 142
**Prize Pool:** 10,000 USDC
**Checkpoint:** 5

Plain Text / Default

Crunch: Synth
Status: Active
Participants: 142
Prize Pool: 10,000 USDC
Checkpoint: 5
Funds: 3000USDC

Error Handling

If a command fails:

1. Show user-friendly error message
2. Suggest possible fixes:
   • Wrong network? Add -u devnet or -u mainnet-beta
   • Missing wallet? Add -w /path/to/wallet.json
   • Crunch not found? List available crunches with crunches list

Example Workflows

"Get me info about crunch Synth"

crunch-cli crunch get "Synth"

"Show my coordinator on mainnet"

crunch-cli -u mainnet-beta coordinator get

"List all crunches for slack"

crunch-cli crunches list

Then format output for Slack.

"What's the current checkpoint for the Chaos competition?"

crunch-cli crunch checkpoint-get-current "Chaos"

Reference Documentation

For full CLI documentation, see references/cli-reference.md.