npm package: @polymerdao/polymer-cli
Description: Command-line interface for interacting with Polymer's proof API and blockchain verification
Author: Polymer Labs
Latest version: 0.3.0

# Polymer CLI

Command-line interface for interacting with Polymer's proof API and blockchain verification. Request proofs of blockchain events, query proof status, verify cryptographic proofs, and manage cross-chain execution requests.

[![npm version](https://badge.fury.io/js/@polymerdao%2Fpolymer-cli.svg)](https://www.npmjs.com/package/@polymerdao/polymer-cli)

## 🚀 Installation

```bash
# Install globally
npm install -g @polymerdao/polymer-cli

# Or use without installing
npx @polymerdao/polymer-cli
```

## 🎯 Quick Start

```bash
# Set your API key
export POLYMER_API_KEY=your_api_key_here

# Request a proof for a blockchain event
polymer proof request --chain ethereum --global-log-index 12345 --block-number 19000000

# Check the status of a proof request
polymer proof query --job-id 123

# Verify a proof locally (no API key needed)
polymer proof verify --proof <base64_proof_data> --parse

# List connected blockchain chains
polymer info chains

# Get help
polymer --help
```

## 📋 Commands

### Proof Operations

**Request a proof:**
```bash
polymer proof request --chain <chain_name> --global-log-index <index> --block-number <number> [options]

# Examples
polymer proof request -c ethereum -i 12345 -n 19000000 -k API_KEY
polymer proof request --chain polygon --global-log-index 54321 --block-number 20000000
```

**Query proof status:**
```bash
polymer proof query --job-id <job_id> [options]

# Examples  
polymer proof query --job-id 123 --api-key API_KEY
polymer proof query -j 456 -k API_KEY
```

**Verify proof locally:**
```bash
polymer proof verify --proof <proof_data> [options]

# Examples
polymer proof verify --proof base64_proof_data --parse
polymer proof verify -p proof_data --from-file proof.json
```

### Cross-Chain Execution

**Submit execution request:**
```bash
polymer execute request --execute-envelope <envelope> [options]

# Examples
polymer execute request --execute-envelope envelope.json --from-file
polymer execute request -e envelope_data -k API_KEY
```

**Query execution status:**
```bash
polymer execute query --job-id <job_id> [options]
```

### Chain Information

**List connected chains:**
```bash
polymer info chains [options]

# Examples
polymer info chains --api-key API_KEY --output json
polymer info chains -k API_KEY -o table
```

**Get chain status:**
```bash
polymer info status [options]
```

### Backward Compatibility

Legacy commands are still supported:

```bash
# These map to the new command structure
polymer chains     # → polymer info chains
polymer verify     # → polymer proof verify  
polymer status     # → polymer proof query
```

## ⚙️ Configuration

### API Key

Set your Polymer API key in one of these ways:

1. **Environment variable (recommended):**
   ```bash
   export POLYMER_API_KEY=your_api_key_here
   ```

2. **Command line flag:**
   ```bash
   polymer proof request --api-key your_api_key_here [other_options]
   ```

### Global Options

```bash
polymer [command] [options]

Global Options:
  -k, --api-key <key>          Polymer API key
  -b, --api-base <url>         Polymer API base URL (default: https://api.polymer.zone/v1)
  -v, --verbose                Log API requests and responses
      --skip-payment-confirmation  Skip x402 payment confirmation prompts
  -s, --signer-pubkey <key>    Public signing key for proof verification (default: 0x4632e987c6f31d6351e39324dec6f1404af56209)
  --polymer-chain-id <id>      Polymer chain ID for verification (default: 444)
  -o, --output <format>        Output format: json|table|raw (default: table)
  --help                       Show help
  --version                    Show version
```

## 📤 Output Formats

The CLI supports multiple output formats:

**Table (default):**
```bash
polymer info chains --output table
```

**JSON:**
```bash
polymer info chains --output json
```

**Raw:**
```bash
polymer info chains --output raw
```

## 🛠️ Development

### Building from Source

```bash
# Clone the monorepo
git clone https://github.com/polymerdao/mcp-polymer.git
cd mcp-polymer/packages/cli

# Install dependencies  
npm install

# Build
npm run build

# Run locally
node dist/cli.js --help
```

### Running Tests

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage
```

### Project Structure

```
src/
├── cli.ts                    # Main CLI entry point
├── commands/                 # Command implementations
│   ├── proof/               # Proof-related commands
│   │   ├── request.ts       # proof request
│   │   ├── query.ts         # proof query  
│   │   └── verify.ts        # proof verify
│   ├── execute/             # Cross-chain execution commands
│   ├── info/                # Information commands
│   └── [legacy commands]    # Backward compatibility
├── utils/                   # Utility functions
│   ├── config.ts           # Configuration management
│   └── version.ts          # Dynamic version resolution
└── __tests__/              # Test suites
```

## 🔧 API Integration

The CLI uses the `@polymerdao/polymer-api-client` package for API interactions:

```typescript
import { PolymerOpenRpcClient } from '@polymerdao/polymer-api-client';

const client = new PolymerOpenRpcClient(apiKey, apiBase);
```

## 📚 Examples

### Complete Proof Workflow

```bash
# 1. Request a proof
PROOF_JOB=$(polymer proof request -c ethereum -i 12345 -n 19000000 -k $API_KEY --output json | jq -r '.jobId')

# 2. Check status (repeat until completed)
polymer proof query --job-id $PROOF_JOB -k $API_KEY

# 3. Get completed proof and verify
polymer proof query --job-id $PROOF_JOB -k $API_KEY --output json | jq -r '.proof' | \
polymer proof verify --from-file --parse
```

### Cross-Chain Execution

```bash
# 1. Prepare execution envelope (JSON file)
cat > execute.json << 'EOF'
{
  "proof": "base64_proof_data",
  "executeRequest": { 
    "chainId": 1,
    "payload": "0x..."
  }
}
EOF

# 2. Submit execution request
polymer execute request --execute-envelope execute.json --from-file -k $API_KEY
```

## 🐛 Troubleshooting

**API Key Issues:**
```bash
# Verify API key is set
echo $POLYMER_API_KEY

# Test API connectivity
polymer info chains -k $POLYMER_API_KEY
```

**Command Not Found:**
```bash
# Check installation
which polymer

# Reinstall if needed
npm install -g @polymerdao/polymer-cli
```

**Permission Issues:**
```bash
# Use npx instead of global install
npx @polymerdao/polymer-cli --help
```

## 🤝 Contributing

See the [main repository README](../../README.md) for contribution guidelines.

### Adding New Commands

1. Create command file in `src/commands/`
2. Implement using the yargs command structure
3. Add tests in `src/__tests__/`
4. Update this README

## 📄 License

Apache 2.0 License - see [LICENSE](../../LICENSE) for details.