wc-auth

The definitive WalletConnect Auth CLI for Base builders.

wc-auth is a powerful command-line tool designed to act as a "Postman for WalletConnect Auth". It allows developers to test, verify, and benchmark WalletConnect authentication flows directly from the terminal.

🚀 Quick Start

Installation

# Install globally via npm
npm install -g wc-auth

# Or use directly with npx
npx wc-auth

# Install globally via Bun
bun install -g wc-auth

# Or use directly with bunx
bunx wc-auth

Basic Workflow

# 1. Set your WalletConnect Project ID
export WALLETCONNECT_PROJECT_ID="your_project_id_here"

# 2. Request SIWE authentication
wc-auth request:siwe --chain eip155:8453 --domain my-app.com

# 3. Verify a JWT token
wc-auth verify <jwt_token>

# 4. View saved sessions
wc-auth replay

📋 What is wc-auth?

wc-auth is a comprehensive CLI tool for testing and debugging WalletConnect authentication flows. It's perfect for:

🔧 Development: Test authentication flows without building a full dApp
🐛 Debugging: Inspect JWT tokens and Cacao objects
⚡ Performance Testing: Benchmark wallet response times
📚 Learning: Understand WalletConnect Auth protocols (SIWE, CAIP-74)
🎨 Customization: Beautiful themes and multiple output formats

✨ Features

🔐 SIWE (Sign-In with Ethereum): Initiate and verify SIWE requests
🥥 Cacau (CAIP-74): Support for Chain-Agnostic Capability User Authentication
📧 Mock Auth: Simulate Email, Passkey, and Social login flows
🔍 Verify: Decode and inspect JWTs and Cacao objects
📼 Replay: Save and replay authentication sessions
⚡ Benchmark: Measure wallet response latency
🎮 Playground: Interactive mode for testing connections
🎨 Themes: 5 beautiful color schemes (dracula, nord, monokai, solarized, default)
📊 Output Formats: Export data as JSON, YAML, or pretty-printed

📦 Prerequisites

Bun: This project is built exclusively with Bun
WalletConnect Project ID: Get one at cloud.reown.com

🛠️ Installation

Via npm (Recommended)

# Install globally
npm install -g wc-auth

# Or use directly with npx
npx wc-auth

Via Bun

# Install globally
bun install -g wc-auth

# Or use directly with bunx
bunx wc-auth

From Source

# Clone the repository
git clone https://github.com/jeremiah-eth/wc-auth.git
cd wc-auth

# Install dependencies
bun install

# Run locally
bun bin/run.ts

⚙️ Configuration

Environment Variables

Set your WalletConnect Project ID as an environment variable:

# Linux/macOS
export WALLETCONNECT_PROJECT_ID="your_project_id_here"

# Windows (PowerShell)
$env:WALLETCONNECT_PROJECT_ID="your_project_id_here"

# Windows (CMD)
set WALLETCONNECT_PROJECT_ID=your_project_id_here

Save Configuration

You can also save your Project ID using the config command:

wc-auth config projectId --set your_project_id_here

View Current Configuration

wc-auth config show

📚 Command Reference

1. Authentication Requests

Sign-In with Ethereum (SIWE)

Request SIWE authentication from a wallet.

# Basic SIWE request on Base
wc-auth request:siwe --chain eip155:8453 --domain my-app.com

# SIWE with custom statement
wc-auth request:siwe \
  --chain eip155:8453 \
  --domain my-app.com \
  --statement "Sign in to access your account"

# SIWE with specific address
wc-auth request:siwe \
  --chain eip155:1 \
  --domain ethereum-app.com \
  --address 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

# Multiple chains
wc-auth request:siwe \
  --chain eip155:1 \
  --chain eip155:8453 \
  --domain multi-chain-app.com

Options:

--chain, -c: Chain ID (e.g., eip155:8453 for Base)
--domain, -d: Your application domain
--statement, -s: Custom message to display
--address, -a: Specific wallet address to request
--projectId: WalletConnect Project ID (overrides env var)

Cacau (CAIP-74)

Request Chain-Agnostic Capability User Authentication.

# Basic Cacau request
wc-auth request:cacau --chain eip155:1

# Cacau with custom capabilities
wc-auth request:cacau \
  --chain eip155:8453 \
  --capability "wallet:transfer" \
  --capability "wallet:sign"

Options:

--chain, -c: Chain ID
--capability: Requested capabilities (can specify multiple)
--projectId: WalletConnect Project ID

Mock Authentication Flows

Test authentication flows without a real wallet.

Email Authentication:

# Mock email login
wc-auth request:email --email user@example.com

# With custom provider
wc-auth request:email \
  --email user@example.com \
  --provider "Custom Email Service"

Passkey Authentication:

# Mock passkey login
wc-auth request:passkey

# With custom username
wc-auth request:passkey --username "john_doe"

Social Authentication:

# Google login
wc-auth request:social --provider google

# GitHub login
wc-auth request:social --provider github

# Twitter login
wc-auth request:social --provider twitter

# Discord login
wc-auth request:social --provider discord

2. Automated Testing

Run automated authentication scenarios defined in a configuration file.

# Run tests from a file
wc-auth test --file ./examples/auth-test.yaml

# Run tests with JSON config
wc-auth test -f ./tests/suite.json

Configuration Format (YAML):

description: My Auth Test Suite
cases:
  - name: Basic SIWE
    command: wc-auth request:siwe --chain eip155:1
    expectations:
      tokenClaims:
        iss: did:pkh:eip155:1:0x...

3. Deep Linking

Generate deep links for mobile wallet testing.

# Generate a universal link
wc-auth link "wc:..."

# Generate a deep link for a specific wallet
wc-auth link "wc:..." --wallet metamask

# Generate a QR code in the terminal
wc-auth link "wc:..." --qr

4. Token Verification

Decode and inspect JWT tokens and Cacao objects.

# Verify a JWT token
wc-auth verify eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...

# Verify with JSON output
wc-auth verify <jwt_token> --output json

# Verify with YAML output
wc-auth verify <jwt_token> --output yaml

# Verify and save to file
wc-auth verify <jwt_token> --output json > token-details.json

Output includes:

Header information
Payload claims
Signature verification status
Expiration time
Issuer and audience
Issuer and audience
Custom claims

Smart Account Verification (EIP-1271): To verify signatures from Smart Accounts, provide an RPC URL:

wc-auth verify <token> --rpc https://mainnet.infura.io/v3/...

3. Session Management

Save, list, and replay authentication sessions.

# List all saved sessions
wc-auth replay

# View specific session details
wc-auth replay <session_id>

# View session as JSON
wc-auth replay <session_id> --output json

# View session as YAML
wc-auth replay <session_id> --output yaml

# Delete a session
wc-auth replay <session_id> --delete

Session data includes:

Timestamp
Chain information
Wallet address
Authentication method
Request/response details

4. Benchmarking

Measure wallet response times and performance.

# Run 10 benchmark tests
wc-auth benchmark --count 10

# Benchmark with specific chain
wc-auth benchmark --count 10 --chain eip155:8453

# Benchmark with custom timeout
wc-auth benchmark --count 10 --timeout 30000

# Export benchmark results
wc-auth benchmark --count 10 --output json > benchmark-results.json

Metrics measured:

Connection time
QR code generation time
User approval time
Total round-trip time
Success rate
Average, min, max response times

5. Interactive Playground

Start an interactive server for testing WalletConnect connections.

# Start playground on default port (31337)
wc-auth playground

# Start on custom port
wc-auth playground --port 8080

# Start with specific chain
wc-auth playground --chain base

# Start with custom project ID
wc-auth playground --projectId your_project_id

Features:

Real-time connection status
QR code display
Session information
Event logging
Interactive testing

6. Configuration & Themes

Theme Management

# Interactive theme selection
wc-auth config theme

# Set theme directly
wc-auth config theme --set dracula

# Available themes
wc-auth config theme --list

Available Themes:

default - Clean and minimal
dracula - Dark purple theme
nord - Arctic blue theme
monokai - Warm dark theme
solarized - Balanced light/dark theme

Project ID Management

# Save Project ID
wc-auth config projectId --set your_project_id

# View current Project ID
wc-auth config projectId

# Clear Project ID
wc-auth config projectId --clear

View All Configuration

# Show all configuration
wc-auth config show

# Show as JSON
wc-auth config show --output json

7. Output Formats

Most commands support multiple output formats:

# Pretty output (default) - Human-readable with colors
wc-auth verify <jwt> --output pretty

# JSON output - Machine-readable
wc-auth verify <jwt> --output json

# YAML output - Configuration-friendly
wc-auth verify <jwt> --output yaml

🌐 Supported Networks

wc-auth supports all EVM-compatible chains. Common examples:

Network	Chain ID	Example
Ethereum Mainnet	`eip155:1`	`--chain eip155:1`
Base	`eip155:8453`	`--chain eip155:8453`
Optimism	`eip155:10`	`--chain eip155:10`
Arbitrum	`eip155:42161`	`--chain eip155:42161`
Polygon	`eip155:137`	`--chain eip155:137`
Sepolia Testnet	`eip155:11155111`	`--chain eip155:11155111`
Base Sepolia	`eip155:84532`	`--chain eip155:84532`

💡 Use Cases & Examples

Example 1: Testing SIWE Flow for a Base dApp

# 1. Set your Project ID
export WALLETCONNECT_PROJECT_ID="abc123..."

# 2. Request SIWE authentication
wc-auth request:siwe \
  --chain eip155:8453 \
  --domain mybaseapp.com \
  --statement "Sign in to access your Base NFTs"

# 3. Scan QR code with your wallet and approve

# 4. Verify the returned JWT
wc-auth verify <jwt_token_from_wallet>

# 5. Save session for later replay
wc-auth replay

Example 2: Benchmarking Wallet Performance

# Run 20 authentication requests and measure performance
wc-auth benchmark --count 20 --chain eip155:8453 --output json > perf-results.json

# Analyze results
cat perf-results.json | jq '.averageTime'

Example 3: Multi-Chain Authentication

# Request authentication across multiple chains
wc-auth request:siwe \
  --chain eip155:1 \
  --chain eip155:8453 \
  --chain eip155:10 \
  --domain multi-chain-app.com

Example 4: Debugging JWT Tokens

# Decode a JWT to inspect claims
wc-auth verify eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9... --output json | jq '.'

# Check expiration
wc-auth verify <jwt> --output json | jq '.payload.exp'

# Verify signature
wc-auth verify <jwt> --output json | jq '.valid'

Example 5: CI/CD Integration

#!/bin/bash
# test-walletconnect-auth.sh

# Set Project ID from environment
export WALLETCONNECT_PROJECT_ID=$WC_PROJECT_ID

# Run authentication test
wc-auth request:siwe \
  --chain eip155:8453 \
  --domain ci-test.com \
  --output json > auth-result.json

# Verify the result
if [ $? -eq 0 ]; then
  echo "✅ WalletConnect Auth test passed"
  exit 0
else
  echo "❌ WalletConnect Auth test failed"
  exit 1
fi

🔧 Contribution

See CONTRIBUTING.md for detailed contribution documentation.

# Run tests
bun test

# Lint code
bun run lint

# Generate documentation
bun run docs

🆘 Getting Help

Documentation: https://jeremiah-eth.github.io/wc-auth/
Issues: GitHub Issues
WalletConnect Docs: docs.walletconnect.com
Base Docs: docs.base.org

Common Issues

Issue: "WalletConnect Project ID is required"

# Solution: Set your Project ID
export WALLETCONNECT_PROJECT_ID="your_project_id"
# Or save it permanently
wc-auth config projectId --set your_project_id

Issue: "Connection timeout"

# Solution: Increase timeout
wc-auth request:siwe --chain eip155:8453 --timeout 60000

Issue: "Invalid chain ID"

# Solution: Use proper CAIP-2 format
wc-auth request:siwe --chain eip155:8453  # ✅ Correct
wc-auth request:siwe --chain 8453         # ❌ Wrong

📄 License

MIT

🙏 Acknowledgments

Built with:

Bun - Fast all-in-one JavaScript runtime
WalletConnect - Web3 authentication protocol
oclif - CLI framework
Base - Ethereum L2 network

Made for Base builders

Contributing to wc-auth

Thank you for your interest in contributing to wc-auth! This document provides a guide for developers who want to work on the codebase.

🛠 Prerequisites

Bun: This project is built exclusively with Bun. Ensure you have it installed.
Node.js: Required for some underlying dependencies (v18+).
Git: For version control.

🚀 Setup

Clone the repository:

git clone https://github.com/jeremiah-eth/wc-auth.git
cd wc-auth

Install dependencies:
```
bun install
```
Environment Setup: Create a .env file (optional, as you can pass flags) or export variables:
```
export WALLETCONNECT_PROJECT_ID="your_project_id"
```

📂 Project Structure

The project uses the Oclif framework.

wc-auth/
├── bin/
│   └── run.ts          # CLI entry point
├── src/
│   ├── commands/       # Oclif commands (the core logic)
│   │   ├── request/    # Sub-commands for 'request' (siwe, cacau, etc.)
│   │   ├── config.ts   # Configuration command
│   │   └── ...
│   ├── hooks/          # Oclif hooks (e.g., init hook for themes)
│   ├── lib/
│   │   └── auth-client.ts # Singleton wrapper for WalletConnect UniversalProvider
│   └── utils/
│       ├── cleanup.ts      # Graceful shutdown handler
│       ├── config.ts       # Persistent configuration (conf)
│       ├── output-formatter.ts # JSON/YAML/Pretty output logic
│       └── theme-manager.ts    # Color theme logic
├── test/               # Tests (Vitest)
└── package.json

💻 Development Workflow

Running Locally

You can run the CLI directly from the source using bun:

# Run a command
bun bin/run.ts request:siwe --chain eip155:8453

# Run help
bun bin/run.ts --help

Testing

We use Vitest for testing.

# Run all tests
bun test

# Run tests with UI
bun test --ui

Linting & Formatting

# Lint code
bun run lint

🏗 Architecture

AuthClientSingleton (`src/lib/auth-client.ts`)

This is the core of the WalletConnect integration. It ensures a single instance of UniversalProvider is initialized and shared across commands. It handles:

Initialization with Project ID.
Session persistence (via UniversalProvider's internal storage).
Event listeners.

Theme System (`src/utils/theme-manager.ts`)

A centralized theme manager that handles color schemes. It exports a Theme interface and several presets. The init hook loads the user's preferred theme on startup.

Configuration (`src/utils/config.ts`)

Uses the conf library to persist user settings (theme, project ID) to the system's config directory.

📦 Release Process

To release a new version to npm:

Bump Version:
```
npm version patch # or minor/major
```
This updates package.json and creates a git tag.
Publish:
```
npm publish
```
Push Tags:
```
git push --follow-tags
```

🤝 Contributing

Fork the repository.
Create a feature branch (git checkout -b feature/amazing-feature).
Commit your changes (git commit -m 'feat: add amazing feature').
Push to the branch (git push origin feature/amazing-feature).
Open a Pull Request.

Please ensure your code passes linting and tests before submitting!