CLI Reference

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

Table of Contents


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:


Installation

The CLI is built automatically with the Prism workspace:

Or build the CLI specifically:


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:

Environment Variable:


Commands

auth Commands

Manage API keys for authentication and authorization.

auth create

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

Usage:

Options:

Option
Type
Required
Default
Description

-n, --name <NAME>

String

Yes

-

Unique name for the API key

-d, --description <DESC>

String

No

-

Description of the key's purpose

--rate-limit <LIMIT>

Integer

No

100

Maximum tokens in the bucket

--refill-rate <RATE>

Integer

No

10

Tokens refilled per second

--daily-limit <LIMIT>

Integer

No

-

Daily request limit (unlimited if not set)

--expires-in-days <DAYS>

Integer

No

-

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

-m, --methods <METHODS>

String

No

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:

Output:

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:

Options:

Option
Type
Required
Default
Description

--show-expired

Boolean

No

false

Include expired keys in the output

Examples:

Output:

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:

Options:

Option
Type
Required
Default
Description

-n, --name <NAME>

String

Yes

-

Name of the key to revoke

Examples:

Output:

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:

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:

Output:


auth stats

Display usage statistics for API keys (implementation pending).

Usage:

Options:

Option
Type
Required
Default
Description

--days <DAYS>

Integer

No

7

Number of days to analyze

Examples:

Output:


config Commands

Manage and validate Prism configuration files.

config validate

Validate a configuration file for correctness and completeness.

Usage:

Options:

Option
Type
Required
Default
Description

-f, --file <FILE>

String

No

config/config.toml

Path to configuration file

Examples:

Output (Success):

Output (Failure):

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:

Options:

Option
Type
Required
Default
Description

-f, --file <FILE>

String

No

config/config.toml

Path to configuration file

--show-sensitive

Boolean

No

false

Display sensitive values (database URLs, API keys)

Examples:

Output:


config generate

Generate a sample configuration file with sensible defaults.

Usage:

Options:

Option
Type
Required
Default
Description

-o, --output <OUTPUT>

String

No

config/config.toml

Path for generated config file

--force

Boolean

No

false

Overwrite existing file if present

Examples:

Output:

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:


config test-upstreams

Test connectivity to all configured upstream RPC providers.

Usage:

Options:

Option
Type
Required
Default
Description

-f, --file <FILE>

String

No

config/config.toml

Path to configuration file

-t, --timeout <TIMEOUT>

Integer

No

10

Timeout in seconds for each test

Examples:

Output:

Output (with failures):

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:

Options:

Option
Type
Required
Default
Description

-o, --output <FILE>

String

No

config/config.toml

Output file path for endpoint configuration

-c, --chain-id <ID>

Integer

No

-

Filter by chain ID (can be specified multiple times)

--chain-name <NAME>

String

No

-

Filter by chain name (case insensitive)

--https-only

Boolean

No

false

Only include HTTPS endpoints

--wss-only

Boolean

No

false

Only include WSS endpoints

--tracking <LEVEL>

String

No

-

Filter by tracking level (none, limited, yes)

--dry-run

Boolean

No

false

Show output without writing to file

--test-speed

Boolean

No

false

Test response times and order by speed

-l, --limit <LIMIT>

Integer

No

0

Limit number of endpoints per chain (0 = unlimited)

--timeout <SECONDS>

Integer

No

10

Timeout for speed tests in seconds

--concurrency <COUNT>

Integer

No

50

Number of concurrent speed tests

--list-chains

Boolean

No

false

List available chains and exit

Examples:

Output (--list-chains):

Output (Standard):

Output File Format:

Speed Test Details:

When --test-speed is enabled:

  1. Fetches all matching endpoints from Chainlist

  2. Tests each endpoint with an eth_blockNumber request

  3. Measures response time in milliseconds

  4. Filters out non-working endpoints

  5. Sorts by response time (fastest first)

  6. 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

1

Ethereum Mainnet

Production DeFi, NFTs

5

Goerli Testnet

Testing (deprecated)

10

Optimism

L2 scaling

56

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

Monitoring and Maintenance

Multi-Chain Setup

Development vs Production


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:

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:

Database Errors

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

Solution: Ensure the database directory exists:

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:

File Permission Errors

Error: IO error: Permission denied

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

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:


Integration with cargo-make

Prism includes cargo-make tasks for common CLI operations:

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


Best Practices

API Key Management

  1. Use descriptive names: Clearly indicate the purpose of each key

  2. Set expiration dates: Use --expires-in-days for temporary or trial keys

  3. Configure daily limits: Prevent abuse with --daily-limit

  4. Limit methods: Use --methods to restrict access to specific RPC methods

  5. Rotate keys regularly: Create new keys and revoke old ones periodically

  6. Monitor usage: Use prism-cli auth list to track usage patterns

Configuration Management

  1. Validate before deploying: Always run config validate before starting the server

  2. Test upstreams regularly: Use config test-upstreams to verify provider health

  3. Version control: Store configurations in git (exclude sensitive data)

  4. Use environment variables: Store sensitive data in environment variables, not config files

  5. Separate configs: Maintain separate configurations for dev, staging, and production

Endpoint Discovery

  1. Enable speed testing: Use --test-speed to find the fastest providers

  2. Limit endpoints: Use --limit to avoid overwhelming your config with too many providers

  3. Filter by privacy: Use --tracking none if privacy is a concern

  4. Update regularly: Re-run fetch-endpoints monthly to discover new providers

  5. Verify after fetching: Always test fetched endpoints with config test-upstreams


See Also


Next: Learn about Authentication & Authorization or return to Getting Started.

Last updated