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/cliRelease:
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>
--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
auth createCreate a new API key with configurable rate limits and permissions.
Usage:
Options:
-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_blockNumbereth_getBlockByNumbereth_getBlockByHasheth_getTransactionByHasheth_getTransactionReceipteth_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
auth listList all API keys with their current status and usage statistics.
Usage:
Options:
--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/sDaily 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
auth revokeRevoke an API key, making it immediately unusable.
Usage:
Options:
-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
auth update-limitsUpdate rate limits for an existing API key.
Usage:
Options:
-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
auth statsDisplay usage statistics for API keys (implementation pending).
Usage:
Options:
--days <DAYS>
Integer
No
7
Number of days to analyze
Examples:
Output:
config Commands
Manage and validate Prism configuration files.
config validate
config validateValidate a configuration file for correctness and completeness.
Usage:
Options:
-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
config showDisplay the current configuration with all resolved values.
Usage:
Options:
-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
config generateGenerate a sample configuration file with sensible defaults.
Usage:
Options:
-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
config test-upstreamsTest connectivity to all configured upstream RPC providers.
Usage:
Options:
-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:
-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:
Fetches all matching endpoints from Chainlist
Tests each endpoint with an
eth_blockNumberrequestMeasures response time in milliseconds
Filters out non-working endpoints
Sorts by response time (fastest first)
Applies
--limitper 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-onlyand--wss-only: Mutually exclusive protocol filters--tracking: Exact match on tracking levelAll 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:
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:
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
Use descriptive names: Clearly indicate the purpose of each key
Set expiration dates: Use
--expires-in-daysfor temporary or trial keysConfigure daily limits: Prevent abuse with
--daily-limitLimit methods: Use
--methodsto restrict access to specific RPC methodsRotate keys regularly: Create new keys and revoke old ones periodically
Monitor usage: Use
prism-cli auth listto track usage patterns
Configuration Management
Validate before deploying: Always run
config validatebefore starting the serverTest upstreams regularly: Use
config test-upstreamsto verify provider healthVersion 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-speedto find the fastest providersLimit endpoints: Use
--limitto avoid overwhelming your config with too many providersFilter by privacy: Use
--tracking noneif privacy is a concernUpdate regularly: Re-run
fetch-endpointsmonthly to discover new providersVerify after fetching: Always test fetched endpoints with
config test-upstreams
See Also
Configuration Reference: Detailed configuration options
Authentication Guide: In-depth authentication and authorization
Getting Started: Initial setup and first steps
API Reference: JSON-RPC API documentation
Next: Learn about Authentication & Authorization or return to Getting Started.
Last updated