CLI Reference

Complete reference for the Prism CLI tool, which provides utilities for managing API keys, validating configurations, and fetching RPC endpoints.

Overview

The Prism CLI (prism-cli) is a command-line tool for managing and configuring the Prism RPC Aggregator. It provides three main command groups:

auth: API key management (create, list, revoke, update)
config: Configuration management (validate, show, generate, test)
fetch-endpoints: Automated RPC endpoint discovery from Chainlist

Binary Location

After building Prism, the CLI binary is located at:

Development: target/debug/cli
Release: target/release/cli

For convenience, you can create an alias or add it to your PATH:

# Add to ~/.bashrc or ~/.zshrc
alias prism-cli='/path/to/prism/target/release/cli'

Installation

The CLI is built automatically with the Prism workspace:

# Development build
cargo make build

# Production build (recommended)
cargo make build-release

Or build the CLI specifically:

# Build CLI only
cargo build --release --bin cli

Global Options

Global options apply to all commands and must be specified before the command name.

`--database <PATH>`

Specify a custom database path for authentication commands.

Type: String (optional) Default: Environment variable DATABASE_URL or sqlite://db/auth.db

Example:

prism-cli --database sqlite://custom/path/auth.db auth list

Environment Variable:

export DATABASE_URL="sqlite://custom/auth.db"
prism-cli auth list

Commands

auth Commands

Manage API keys for authentication and authorization.

`auth create`

Create a new API key with configurable rate limits and permissions.

Usage:

prism-cli auth create [OPTIONS]

Options:

Option

Type

Required

Default

Description

-n, --name <NAME>

String

Yes

Unique name for the API key

-d, --description <DESC>

String

Description of the key's purpose

--rate-limit <LIMIT>

Integer

100

Maximum tokens in the bucket

--refill-rate <RATE>

Integer

10

Tokens refilled per second

--daily-limit <LIMIT>

Integer

Daily request limit (unlimited if not set)

--expires-in-days <DAYS>

Integer

Number of days until expiration (never expires if not set)

-m, --methods <METHODS>

String

Default set

Comma-separated list of allowed RPC methods

Default Allowed Methods (when --methods is not specified):

eth_blockNumber
eth_getBlockByNumber
eth_getBlockByHash
eth_getTransactionByHash
eth_getTransactionReceipt
eth_getLogs

Examples:

# Create a key with default settings
prism-cli auth create \
  --name "production-key" \
  --description "Main production API key"

# Create a key with custom rate limits
prism-cli auth create \
  --name "high-volume-key" \
  --rate-limit 500 \
  --refill-rate 50 \
  --daily-limit 100000

# Create a temporary key that expires in 30 days
prism-cli auth create \
  --name "trial-key" \
  --expires-in-days 30 \
  --daily-limit 10000

# Create a key with limited method access
prism-cli auth create \
  --name "read-only-key" \
  --methods "eth_blockNumber,eth_getBlockByNumber,eth_getLogs"

Output:

✅ API Key created successfully!
Name: production-key
Key: prism_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
⚠️  Save this key securely - it cannot be retrieved later!

Important Notes:

The API key is displayed only once during creation
Keys are hashed before storage using Argon2id
Blind index is computed for timing-attack resistant lookups
Save the key immediately in a secure location

`auth list`

List all API keys with their current status and usage statistics.

Usage:

prism-cli auth list [OPTIONS]

Options:

Option

Type

Required

Default

Description

--show-expired

Boolean

false

Include expired keys in the output

Examples:

# List active keys only
prism-cli auth list

# List all keys including expired ones
prism-cli auth list --show-expired

Output:

+------------------+--------+-------------+--------------+------------+------------+-----------------+
| Name             | Active | Rate Limit  | Daily Limit  | Used Today | Expires    | Last Used       |
+------------------+--------+-------------+--------------+------------+------------+-----------------+
| production-key   | ✓      | 100/10/s    | ∞            | 4,567      | Never      | 2025-12-05 14:30|
| trial-key        | ✓      | 100/10/s    | 10000        | 1,234      | 2026-01-04 | 2025-12-05 12:15|
| read-only-key    | ✓      | 100/10/s    | ∞            | 89         | Never      | 2025-12-04 18:45|
+------------------+--------+-------------+--------------+------------+------------+-----------------+

Column Descriptions:

Name: Unique identifier for the API key
Active: Whether the key is currently active (✓/✗)
Rate Limit: Format is max_tokens/refill_rate/s
Daily Limit: Maximum daily requests (∞ for unlimited)
Used Today: Number of requests made today
Expires: Expiration date or "Never"
Last Used: Last request timestamp or "Never"

`auth revoke`

Revoke an API key, making it immediately unusable.

Usage:

prism-cli auth revoke [OPTIONS]

Options:

Option

Type

Required

Default

Description

-n, --name <NAME>

String

Yes

Name of the key to revoke

Examples:

# Revoke a key by name
prism-cli auth revoke --name "trial-key"

Output:

✅ API Key 'trial-key' has been revoked

Important Notes:

Revocation is immediate and cannot be undone
Revoked keys remain in the database but are marked as inactive
All subsequent requests using this key will be rejected

`auth update-limits`

Update rate limits for an existing API key.

Usage:

prism-cli auth update-limits [OPTIONS]

Options:

Option

Type

Required

Default

Description

-n, --name <NAME>

String

Yes

Name of the key to update

--rate-limit <LIMIT>

Integer

Yes

New maximum token count

--refill-rate <RATE>

Integer

Yes

New refill rate (tokens/second)

Examples:

# Increase rate limits for high-volume usage
prism-cli auth update-limits \
  --name "production-key" \
  --rate-limit 500 \
  --refill-rate 50

# Decrease rate limits to throttle usage
prism-cli auth update-limits \
  --name "trial-key" \
  --rate-limit 50 \
  --refill-rate 5

Output:

✅ Rate limits updated for key 'production-key'
New limits: 500 tokens, 50 tokens/s

`auth stats`

Display usage statistics for API keys (implementation pending).

Usage:

prism-cli auth stats [OPTIONS]

Options:

Option

Type

Required

Default

Description

--days <DAYS>

Integer

7

Number of days to analyze

Examples:

# Show stats for the last 7 days
prism-cli auth stats

# Show stats for the last 30 days
prism-cli auth stats --days 30

Output:

📊 Usage statistics for the last 7 days
(Implementation in progress - queries api_key_usage table)

config Commands

Manage and validate Prism configuration files.

`config validate`

Validate a configuration file for correctness and completeness.

Usage:

prism-cli config validate [OPTIONS]

Options:

Option

Type

Required

Default

Description

-f, --file <FILE>

String

config/config.toml

Path to configuration file

Examples:

# Validate default config
prism-cli config validate

# Validate a specific config file
prism-cli config validate --file config/production.toml

Output (Success):

ℹ️  Loading configuration from config/config.toml...
ℹ️  Validating configuration...
✅ Configuration is valid!
📊 Configuration Summary:
  Server: 127.0.0.1:3030
  Upstreams: 2 providers
  Cache: enabled
  Auth: enabled
  Metrics: enabled

Output (Failure):

❌ Configuration error: At least one upstream provider must be configured

Validation Checks:

File exists and is readable
Valid TOML syntax
Required fields are present
At least one upstream provider configured
URLs are properly formatted
Numeric values are within valid ranges
Cache configuration is consistent
Authentication database URL is valid

`config show`

Display the current configuration with all resolved values.

Usage:

prism-cli config show [OPTIONS]

Options:

Option

Type

Required

Default

Description

-f, --file <FILE>

String

config/config.toml

Path to configuration file

--show-sensitive

Boolean

false

Display sensitive values (database URLs, API keys)

Examples:

# Show config with sensitive values hidden
prism-cli config show

# Show complete config including sensitive data
prism-cli config show --show-sensitive

# Show config from custom file
prism-cli config show --file config/production.toml

Output:

📋 Configuration from config/config.toml:

[Server]
  Bind Address: 127.0.0.1
  Bind Port: 3030
  Max Concurrent Requests: 100
  Request Timeout: 30s

[Upstreams] (2 providers)
  alchemy-mainnet: https://eth-mainnet.g.alchemy.com/v2/... (chain 1)
    WebSocket: wss://eth-mainnet.g.alchemy.com/v2/...
  infura-mainnet: https://mainnet.infura.io/v3/... (chain 1)
    WebSocket: wss://mainnet.infura.io/ws/v3/...

[Cache]
  Enabled: true
  TTL: 300s
  Retain Blocks: 1000

[Authentication]
  Enabled: true
  Database URL: [hidden - use --show-sensitive to reveal]

[Metrics]
  Enabled: true
  Prometheus Port: 9090

[Logging]
  Level: info
  Format: pretty

`config generate`

Generate a sample configuration file with sensible defaults.

Usage:

prism-cli config generate [OPTIONS]

Options:

Option

Type

Required

Default

Description

-o, --output <OUTPUT>

String

config/config.toml

Path for generated config file

--force

Boolean

false

Overwrite existing file if present

Examples:

# Generate config at default location
prism-cli config generate

# Generate config at custom location
prism-cli config generate --output config/my-config.toml

# Overwrite existing config
prism-cli config generate --force

Output:

✅ Sample configuration generated: config/config.toml
ℹ️  Remember to:
ℹ️    1. Replace YOUR_API_KEY placeholders with real API keys
ℹ️    2. Configure additional upstream providers as needed
ℹ️    3. Adjust cache and rate limiting settings for your use case

Generated File Contents: The generated file includes:

Server configuration with sensible defaults
Two example upstream providers (Infura and Alchemy)
Complete cache configuration with all subsystems
Authentication disabled by default
Metrics enabled with Prometheus
Logging set to info level

Error Handling:

# If file exists without --force
❌ Configuration error: File config/config.toml already exists. Use --force to overwrite.

`config test-upstreams`

Test connectivity to all configured upstream RPC providers.

Usage:

prism-cli config test-upstreams [OPTIONS]

Options:

Option

Type

Required

Default

Description

-f, --file <FILE>

String

config/config.toml

Path to configuration file

-t, --timeout <TIMEOUT>

Integer

10

Timeout in seconds for each test

Examples:

# Test upstreams with default timeout
prism-cli config test-upstreams

# Test with custom timeout
prism-cli config test-upstreams --timeout 30

# Test a specific config
prism-cli config test-upstreams --file config/production.toml

Output:

ℹ️  Testing 2 upstream providers...
Testing alchemy-mainnet: ✅ OK (45ms)
Testing infura-mainnet: ✅ OK (52ms)

📊 Test Results:
  ✅ Successful: 2
  ❌ Failed: 0

✅ All upstream providers are working correctly!

Output (with failures):

ℹ️  Testing 3 upstream providers...
Testing alchemy-mainnet: ✅ OK (45ms)
Testing infura-mainnet: ❌ Failed: Connection timeout
Testing quicknode-mainnet: ❌ HTTP 401

📊 Test Results:
  ✅ Successful: 1
  ❌ Failed: 2

❌ Some upstream providers are not responding correctly
ℹ️  Check your API keys and network connectivity

Test Method: Each upstream is tested with a simple eth_blockNumber JSON-RPC request. The test:

Measures response time
Verifies HTTP status code
Validates JSON-RPC response format
Reports success or failure with details

fetch-endpoints

Fetch and configure RPC endpoints from Chainlist, with optional speed testing and filtering.

Usage:

prism-cli fetch-endpoints [OPTIONS]

Options:

Option

Type

Required

Default

Description

-o, --output <FILE>

String

config/config.toml

Output file path for endpoint configuration

-c, --chain-id <ID>

Integer

Filter by chain ID (can be specified multiple times)

--chain-name <NAME>

String

Filter by chain name (case insensitive)

--https-only

Boolean

false

Only include HTTPS endpoints

--wss-only

Boolean

false

Only include WSS endpoints

--tracking <LEVEL>

String

Filter by tracking level (none, limited, yes)

--dry-run

Boolean

false

Show output without writing to file

--test-speed

Boolean

false

Test response times and order by speed

-l, --limit <LIMIT>

Integer

0

Limit number of endpoints per chain (0 = unlimited)

--timeout <SECONDS>

Integer

10

Timeout for speed tests in seconds

--concurrency <COUNT>

Integer

50

Number of concurrent speed tests

--list-chains

Boolean

false

List available chains and exit

Examples:

# List all available chains
prism-cli fetch-endpoints --list-chains

# Fetch Ethereum Mainnet endpoints
prism-cli fetch-endpoints --chain-id 1 --output config/mainnet.toml

# Fetch multiple chains
prism-cli fetch-endpoints \
  --chain-id 1 \
  --chain-id 137 \
  --chain-id 42161

# Fetch and test speed (recommended)
prism-cli fetch-endpoints \
  --chain-id 1 \
  --test-speed \
  --limit 5 \
  --output config/fastest-endpoints.toml

# Filter by chain name (less precise than chain-id)
prism-cli fetch-endpoints --chain-name "ethereum"

# Filter by privacy level (no tracking)
prism-cli fetch-endpoints \
  --chain-id 1 \
  --tracking none

# HTTPS endpoints only
prism-cli fetch-endpoints \
  --chain-id 1 \
  --https-only

# Preview without writing
prism-cli fetch-endpoints \
  --chain-id 1 \
  --dry-run

# Production setup: fetch fastest endpoints with strict filtering
prism-cli fetch-endpoints \
  --chain-id 1 \
  --https-only \
  --tracking none \
  --test-speed \
  --limit 3 \
  --timeout 5 \
  --concurrency 100 \
  --output config/production-endpoints.toml

Output (--list-chains):

🔗 Available Chains:
┌──────────┬────────────────────────┬───────────┐
│ Chain ID │ Name                   │ RPC Count │
├──────────┼────────────────────────┼───────────┤
│ 1        │ Ethereum Mainnet       │ 45        │
│ 10       │ Optimism               │ 12        │
│ 56       │ BNB Smart Chain        │ 28        │
│ 100      │ Gnosis Chain           │ 8         │
│ 137      │ Polygon                │ 35        │
│ 250      │ Fantom                 │ 15        │
│ 42161    │ Arbitrum One           │ 18        │
│ 43114    │ Avalanche C-Chain      │ 22        │
└──────────┴────────────────────────┴───────────┘

... and 245 more chains (showing first 50)

💡 Common Chain IDs:
  1   - Ethereum Mainnet
  137 - Polygon
  56  - BNB Smart Chain
  42161 - Arbitrum One
  10  - Optimism
  43114 - Avalanche C-Chain
  250 - Fantom
  100 - Gnosis Chain

🔍 Use --chain-name to filter by name, then use specific chain IDs

Output (Standard):

🔄 Fetching RPC endpoints from Chainlist...
📊 Found 253 chains
✅ Processed 45 endpoints
🚀 Testing response times...
✅ Speed testing complete: 38/45 endpoints are working

🏆 Top 10 Fastest Working Endpoints:
┌──────────┬──────────────────┬─────────────┬───────────────┬─────────┬────────────────────────────────┐
│ Chain ID │ Chain Name       │ Domain      │ Response Time │ Status  │ URL                            │
├──────────┼──────────────────┼─────────────┼───────────────┼─────────┼────────────────────────────────┤
│ 1        │ Ethereum Mainnet │ cloudflare  │ 12ms          │ ✅ Working │ https://cloudflare-eth.com     │
│ 1        │ Ethereum Mainnet │ publicnode  │ 18ms          │ ✅ Working │ https://ethereum-rpc.publicnode.com │
│ 1        │ Ethereum Mainnet │ ankr        │ 24ms          │ ✅ Working │ https://rpc.ankr.com/eth       │
└──────────┴──────────────────┴─────────────┴───────────────┴─────────┴────────────────────────────────┘

📝 Limited to 5 endpoints per chain
📝 Endpoints written to: config/fastest-endpoints.toml

📋 Summary:
  Output file: config/fastest-endpoints.toml
  Chain IDs: [1]
  Chain name filter: none
  Protocol filter: all
  Tracking filter: all
  Speed testing: enabled
  Limit per chain: 5
  Total endpoints: 5
  Working endpoints: 5

Output File Format:

# RPC Endpoints from Chainlist
# Generated on: 2025-12-05 14:30:00 UTC
# Format: CHAIN_ID|NAME|HTTPS|WSS,CHAIN_ID|NAME2|HTTPS2|WSS2,...
# Endpoints are sorted by response time (fastest first)
# Only working endpoints are included

RPC_UPSTREAMS="1|cloudflare|https://cloudflare-eth.com|wss://cloudflare-eth.com # 12ms
1|publicnode|https://ethereum-rpc.publicnode.com|wss://ethereum-rpc.publicnode.com # 18ms
1|ankr|https://rpc.ankr.com/eth|wss://rpc.ankr.com/eth # 24ms
"

# Example usage in your application:
# The RPC_UPSTREAMS variable contains comma-separated entries in the format:
# CHAIN_ID|NAME|HTTPS_URL|WSS_URL,CHAIN_ID|NAME2|HTTPS_URL2|WSS_URL2,...
#
# Each entry provides:
# - CHAIN_ID: The blockchain network ID
# - NAME: Extracted domain name (with suffixes for duplicates)
# - HTTPS_URL: The HTTP RPC endpoint
# - WSS_URL: The WebSocket RPC endpoint (auto-generated from HTTPS)
#
# Endpoints are ordered by response time (fastest first)
# Response times are included as comments for reference

Speed Test Details:

When --test-speed is enabled:

Fetches all matching endpoints from Chainlist
Tests each endpoint with an eth_blockNumber request
Measures response time in milliseconds
Filters out non-working endpoints
Sorts by response time (fastest first)
Applies --limit per chain if specified

Filtering Logic:

--chain-id: Multiple values are combined with OR (any match)
--chain-name: Fuzzy match on chain name (less precise)
--https-only and --wss-only: Mutually exclusive protocol filters
--tracking: Exact match on tracking level
All filters are combined with AND logic

Duplicate Handling:

If multiple endpoints share the same domain name, they are suffixed with _1, _2, etc.

Example:

infura (first occurrence)
infura_1 (second occurrence)
infura_2 (third occurrence)

Common Chain IDs:

Chain ID

Network

Common Use

Ethereum Mainnet

Production DeFi, NFTs

Goerli Testnet

Testing (deprecated)

Optimism

L2 scaling

BNB Smart Chain

Low-cost transactions

100

Gnosis Chain

Stable payments

137

Polygon

High-throughput L2

250

Fantom

Fast finality

42161

Arbitrum One

L2 scaling

43114

Avalanche C-Chain

High-performance DeFi

8453

Base

Coinbase L2

Examples

Complete Workflow: Setting Up a New Prism Instance

# 1. Generate sample config
prism-cli config generate --output config/my-config.toml

# 2. Fetch fastest endpoints for Ethereum Mainnet
prism-cli fetch-endpoints \
  --chain-id 1 \
  --test-speed \
  --limit 3 \
  --output config/endpoints.env

# 3. Manually edit config/my-config.toml to add the endpoints

# 4. Validate configuration
prism-cli config validate --file config/my-config.toml

# 5. Test upstream connectivity
prism-cli config test-upstreams --file config/my-config.toml

# 6. Create API keys
prism-cli auth create \
  --name "admin-key" \
  --description "Administrative access" \
  --rate-limit 1000 \
  --refill-rate 100

prism-cli auth create \
  --name "app-key" \
  --description "Application access" \
  --rate-limit 100 \
  --refill-rate 10 \
  --daily-limit 50000 \
  --expires-in-days 90

# 7. Verify keys were created
prism-cli auth list

# 8. Start the server with the new config
PRISM_CONFIG=config/my-config.toml cargo run --release --bin server

Monitoring and Maintenance

# Check current API keys and usage
prism-cli auth list

# Revoke compromised key
prism-cli auth revoke --name "compromised-key"

# Update rate limits during high traffic
prism-cli auth update-limits \
  --name "app-key" \
  --rate-limit 500 \
  --refill-rate 50

# Verify configuration after changes
prism-cli config validate

# Test upstreams after provider maintenance
prism-cli config test-upstreams --timeout 5

Multi-Chain Setup

# Fetch endpoints for multiple chains
prism-cli fetch-endpoints \
  --chain-id 1 \
  --chain-id 137 \
  --chain-id 42161 \
  --chain-id 10 \
  --test-speed \
  --limit 2 \
  --output config/multi-chain-endpoints.env

# This creates a single file with the fastest 2 endpoints per chain

Development vs Production

# Development: Use public endpoints without speed testing
prism-cli fetch-endpoints \
  --chain-id 1 \
  --limit 3 \
  --output config/dev-endpoints.env

# Production: Strict filtering and speed testing
prism-cli fetch-endpoints \
  --chain-id 1 \
  --https-only \
  --tracking none \
  --test-speed \
  --limit 5 \
  --timeout 3 \
  --concurrency 200 \
  --output config/prod-endpoints.env

Error Handling

Common Errors and Solutions

Configuration Errors

Error: Configuration error: File not found: config/config.toml

Solution: Ensure the configuration file exists or specify the correct path:

prism-cli config validate --file path/to/your/config.toml

Error: Configuration error: At least one upstream provider must be configured

Solution: Add at least one upstream provider to your configuration file or generate a sample config:

prism-cli config generate

Database Errors

Error: Failed to connect to database: unable to open database file

Solution: Ensure the database directory exists:

mkdir -p db
prism-cli auth create --name "test-key"

Error: Database error: UNIQUE constraint failed

Solution: An API key with this name already exists. Choose a different name or revoke the existing key first.

Network Errors

Error: Failed to fetch data from Chainlist

Solution: Check your internet connection and try again. Chainlist may be temporarily unavailable.

Error: Testing alchemy-mainnet: ❌ Failed: Connection timeout

Solution: Verify your API key is correct and the provider is operational. Increase timeout:

prism-cli config test-upstreams --timeout 30

File Permission Errors

Error: IO error: Permission denied

Solution: Ensure you have write permissions to the output directory:

chmod +w config/
prism-cli config generate

Exit Codes

The CLI returns the following exit codes:

Code

Meaning

0

Success

1

General error (configuration, IO, network)

101

Configuration error

102

Database error

103

Network error

Verbose Output

For debugging, run commands with RUST_LOG environment variable:

# Debug level logging
RUST_LOG=debug prism-cli config validate

# Trace level logging (very verbose)
RUST_LOG=trace prism-cli fetch-endpoints --chain-id 1

Integration with cargo-make

Prism includes cargo-make tasks for common CLI operations:

# Validate configuration
cargo make cli-config-validate

# Show configuration
cargo make cli-config-show

# Test upstreams
cargo make cli-test-upstreams

# Generate sample config
cargo make cli-config-generate

# Create API key (interactive)
cargo make cli-auth-create

# List API keys
cargo make cli-auth-list

See Makefile.toml for all available tasks and their definitions.

Best Practices

API Key Management

Use descriptive names: Clearly indicate the purpose of each key
Set expiration dates: Use --expires-in-days for temporary or trial keys
Configure daily limits: Prevent abuse with --daily-limit
Limit methods: Use --methods to restrict access to specific RPC methods
Rotate keys regularly: Create new keys and revoke old ones periodically
Monitor usage: Use prism-cli auth list to track usage patterns

Configuration Management

Validate before deploying: Always run config validate before starting the server
Test upstreams regularly: Use config test-upstreams to verify provider health
Version control: Store configurations in git (exclude sensitive data)
Use environment variables: Store sensitive data in environment variables, not config files
Separate configs: Maintain separate configurations for dev, staging, and production

Endpoint Discovery

Enable speed testing: Use --test-speed to find the fastest providers
Limit endpoints: Use --limit to avoid overwhelming your config with too many providers
Filter by privacy: Use --tracking none if privacy is a concern
Update regularly: Re-run fetch-endpoints monthly to discover new providers
Verify after fetching: Always test fetched endpoints with config test-upstreams

Good afternoon

CLI Reference

Table of Contents

Overview

Binary Location

Installation

Global Options

`--database <PATH>`

Commands

auth Commands

`auth create`

`auth list`

`auth revoke`

`auth update-limits`

`auth stats`

config Commands

`config validate`

`config show`

`config generate`

`config test-upstreams`

fetch-endpoints

Examples

Complete Workflow: Setting Up a New Prism Instance

Monitoring and Maintenance

Multi-Chain Setup

Development vs Production

Error Handling

Common Errors and Solutions

Configuration Errors

Database Errors

Network Errors

File Permission Errors

Exit Codes

Verbose Output

Integration with cargo-make

Best Practices

API Key Management

Configuration Management

Endpoint Discovery

See Also