CLI Configuration

The CCTP CLI supports flexible configuration through multiple sources, allowing you to customize defaults, RPC endpoints, and wallet authentication.

Configuration Sources

The CLI uses Viper to load configuration from multiple sources with clear precedence:

Command-line flags

Highest priority - overrides all other sources

cctp transfer --testnet --keystore /custom/path

Environment variables

Second priority - prefix with CCTP_

export CCTP_TESTNET=true
export CCTP_KEYSTORE_PATH=/path/to/keystore

Configuration file

Third priority - ~/.cctp/config.yaml or ./config.yaml

network: testnet
keystore_path: ~/.ethereum/keystore

Default values

Lowest priority - built-in defaults

Configuration File

The CLI looks for configuration files in these locations (in order):

Path specified by --config flag
$HOME/.cctp/config.yaml
./config.yaml (current directory)

Creating a Config File

# Network preference
network: mainnet  # or "testnet"

# Keystore path (optional - uses OS-specific defaults if omitted)
keystore_path: ~/.ethereum/keystore

# Custom RPC endpoints (optional)
rpc_urls:
  Ethereum: https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
  Arbitrum: https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
  Base: https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
  Polygon PoS: https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY

# Default transfer values (optional)
defaults:
  amount: "100"
  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

# Saved addresses for quick access (optional)
saved_addresses:
  - name: "My Wallet"
    address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  - name: "Treasury"
    address: "0x1234567890123456789012345678901234567890"
  - name: "Partner"
    address: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"

Configuration Options

Option	Type	Description	Default
`network`	string	`mainnet` or `testnet`	`mainnet`
`keystore_path`	string	Path to Ethereum keystore directory	OS-specific
`rpc_urls`	map	Custom RPC endpoints by chain name	Built-in defaults
`defaults.amount`	string	Default transfer amount	(none)
`defaults.recipient`	string	Default recipient address	(none)
`saved_addresses`	array	Named addresses for quick access	(none)

Chain names in rpc_urls must match exactly (case-sensitive). Use the full chain names like Ethereum, Arbitrum, OP Mainnet, etc.

Wallet Authentication

The CLI supports two methods for wallet authentication:

1. Private Key (Environment Variable)

The simplest method for programmatic usage or testing:

export PRIVATE_KEY=0x1234567890abcdef...
cctp transfer

Security Warning: Never commit private keys to version control or share them. Use this method only for development or in secure environments.

When to use:

Automated scripts
CI/CD pipelines (with secret management)
Development and testing
Single-account scenarios

2. Keystore File

More secure method using encrypted keystore files with password protection:

cctp transfer --keystore ~/.ethereum/keystore

The CLI will:

List available accounts from the keystore directory
Prompt you to select an account
Ask for the password to decrypt the keystore

When to use:

Production environments
Multiple account management
Enhanced security with password protection
When sharing wallets across applications (e.g., with Geth, Metamask export)

Default Keystore Locations

macOS
Linux
Windows

~/Library/Ethereum/keystore

The CLI automatically checks this location if no --keystore flag is provided.

~/.ethereum/keystore

Standard Geth keystore location on Linux systems.

%APPDATA%\Ethereum\keystore

Typically: C:\Users\<username>\AppData\Roaming\Ethereum\keystore

Setting Up a Keystore

Create keystore directory

mkdir -p ~/.ethereum/keystore

Add keystore files

Copy your existing keystore files to the directory, or create a new one using Geth:

geth account new --keystore ~/.ethereum/keystore

You can also export from MetaMask:

Open MetaMask
Go to Account Details
Export Private Key
Use a tool like MyCrypto to convert to keystore format

Test the keystore

cctp transfer --keystore ~/.ethereum/keystore

The CLI should list your accounts and prompt for a password.

Keystore File Format

Keystore files are JSON files with encrypted private keys. Example structure:

{
  "address": "742d35cc6634c0532925a3b844bc9e7595f0beb",
  "crypto": {
    "cipher": "aes-128-ctr",
    "ciphertext": "...",
    "cipherparams": {
      "iv": "..."
    },
    "kdf": "scrypt",
    "kdfparams": {
      "dklen": 32,
      "n": 262144,
      "p": 1,
      "r": 8,
      "salt": "..."
    },
    "mac": "..."
  },
  "id": "...",
  "version": 3
}

The file is typically named: UTC--<timestamp>--<address>

Environment Variables

Set environment variables with the CCTP_ prefix (uppercased, with underscores):

Available Variables

Variable	Type	Description	Example
`CCTP_TESTNET`	boolean	Use testnet	`true`, `false`
`CCTP_KEYSTORE_PATH`	string	Keystore directory path	`/path/to/keystore`
`PRIVATE_KEY`	string	Private key for wallet	`0x1234...`

Examples

export CCTP_TESTNET=true
export CCTP_KEYSTORE_PATH=~/.ethereum/keystore
export PRIVATE_KEY=0x1234567890abcdef...

# Run transfer
cctp transfer

Never commit .env files containing PRIVATE_KEY to version control. Add .env to your .gitignore.

Custom RPC Endpoints

Override default RPC endpoints to use your own infrastructure or preferred providers.

Configuration File

rpc_urls:
  # Mainnet chains
  Ethereum: https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
  Arbitrum: https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY
  Base: https://base-mainnet.g.alchemy.com/v2/YOUR_KEY
  Polygon PoS: https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY
  Avalanche: https://api.avax.network/ext/bc/C/rpc
  OP Mainnet: https://opt-mainnet.g.alchemy.com/v2/YOUR_KEY
  
  # Testnet chains
  Ethereum Sepolia: https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
  Arbitrum Sepolia: https://arb-sepolia.g.alchemy.com/v2/YOUR_KEY

Chain Names for RPC URLs

Mainnet Chain Names

Use these exact names (case-sensitive):

Ethereum
Avalanche
OP Mainnet
Arbitrum
Base
Polygon PoS
Unichain
Linea
Codex
Sonic
World Chain
Sei
XDC
HyperEVM
Ink
Plume

Testnet Chain Names

Use these exact names (case-sensitive):

Ethereum Sepolia
Avalanche Fuji
OP Sepolia
Arbitrum Sepolia
Base Sepolia
Polygon PoS Amoy
Unichain Sepolia
Linea Sepolia
Codex Testnet
Sonic Testnet
World Chain Sepolia
Sei Testnet
XDC Apothem
HyperEVM Testnet
Ink Testnet
Plume Testnet
Arc Testnet

Popular RPC Providers

Alchemy

Reliable and fast
Free tier available
alchemy.com

Infura

Wide chain support
Enterprise options
infura.io

QuickNode

High performance
Global infrastructure
quicknode.com

Ankr

Public endpoints
Free and premium
ankr.com

LlamaRPC

Community-driven
No registration needed
Free public RPCs

Self-hosted

Full control
Run Geth, Erigon, etc.
Best for privacy

Default Values

Set default values to speed up the transfer process:

defaults:
  amount: "100"  # Default USDC amount
  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"  # Default recipient

How defaults work:

Pre-populate TUI fields (you can still edit them)
Override with command-line flags: --amount 500
Useful for repetitive transfers to the same recipient

Defaults are convenient but optional. The TUI always allows you to modify these values before confirming the transfer.

Saved Addresses

Store frequently used addresses with friendly names:

saved_addresses:
  - name: "My Wallet"
    address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  - name: "Treasury"
    address: "0x1234567890123456789012345678901234567890"
  - name: "Partner Wallet"
    address: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
  - name: "Exchange Deposit"
    address: "0x9876543210987654321098765432109876543210"

While saved addresses are stored in the config, the current TUI version doesn’t automatically present them yet. This feature is planned for future enhancements.

Configuration Examples

Production Setup

# Production configuration
network: mainnet

# Use custom high-performance RPCs
rpc_urls:
  Ethereum: https://eth-mainnet.g.alchemy.com/v2/PROD_KEY
  Arbitrum: https://arb-mainnet.g.alchemy.com/v2/PROD_KEY
  Base: https://base-mainnet.g.alchemy.com/v2/PROD_KEY

# No defaults - require explicit input for safety

Development Setup

# Development configuration
network: testnet
keystore_path: ./dev-keystore

rpc_urls:
  Ethereum Sepolia: https://eth-sepolia.g.alchemy.com/v2/DEV_KEY
  Arbitrum Sepolia: https://arb-sepolia.g.alchemy.com/v2/DEV_KEY

defaults:
  amount: "10"
  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

Multi-Environment

Create separate config files for each environment:config.mainnet.yaml:

network: mainnet
rpc_urls:
  Ethereum: https://eth-mainnet.g.alchemy.com/v2/MAINNET_KEY

config.testnet.yaml:

network: testnet
rpc_urls:
  Ethereum Sepolia: https://eth-sepolia.g.alchemy.com/v2/TESTNET_KEY

Use with:

cctp transfer --config ./config.mainnet.yaml
cctp transfer --config ./config.testnet.yaml

Configuration Precedence Example

Understanding how different sources combine: 1. Config file (~/.cctp/config.yaml):

network: mainnet
keystore_path: ~/.ethereum/keystore

2. Environment variable:

export CCTP_TESTNET=true

3. Command:

cctp transfer --keystore /custom/path

Final configuration:

network: testnet (env var overrides config file)
keystore_path: /custom/path (flag overrides env and config)

Security Best Practices

Protect Private Keys

Never commit PRIVATE_KEY to version control
Use environment variables or secure secret management
Consider using keystore files for better security

Secure Config Files

Don’t commit config files with sensitive data
Set appropriate file permissions:

chmod 600 ~/.cctp/config.yaml

Secure Keystore Files

Use strong passwords for keystore encryption
Store keystore files in secure locations
Backup keystore files securely

Use Testnet First

Always test with testnet before mainnet
Verify recipient addresses carefully
Test with small amounts first

Monitor RPC Endpoints

Use trusted RPC providers
Consider self-hosting for sensitive operations
Rotate API keys regularly

Troubleshooting

No wallet source available

Error: no wallet source available: set PRIVATE_KEY env variable or provide --keystore pathCause: Neither private key nor keystore is configured.Solution:

# Option 1: Use private key
export PRIVATE_KEY=0x...

# Option 2: Use keystore
cctp transfer --keystore ~/.ethereum/keystore

Config file not found

Not an error: Config files are optional. The CLI works fine without one.To suppress the warning: Create an empty config file:

mkdir -p ~/.cctp
touch ~/.cctp/config.yaml

Keystore path does not exist

Error: keystore path does not exist: /path/to/keystoreCause: The specified keystore directory doesn’t exist.Solution:

# Create directory
mkdir -p ~/.ethereum/keystore

# Or use correct path
cctp transfer --keystore /correct/path

Invalid chain name in RPC URLs

Error: Custom RPC not being used.Cause: Chain name doesn’t match exactly (case-sensitive).Solution: Use exact chain names:

rpc_urls:
  Ethereum: https://...        # Correct
  # ethereum: https://...     # Wrong - lowercase
  # ETH: https://...          # Wrong - abbreviation

Environment variable not working

Cause: Missing CCTP_ prefix or not exported.Solution:

# Wrong
TESTNET=true

# Correct
export CCTP_TESTNET=true

# Verify
echo $CCTP_TESTNET

RPC rate limiting

Symptoms: Slow transfers or RPC errors.Cause: Hitting free tier rate limits.Solution:

Upgrade to paid RPC plan
Use multiple RPC providers
Self-host a node

Next Steps

Commands

Learn all available CLI commands and flags

Quick Start

Complete your first cross-chain transfer

SDK Integration

Integrate CCTP into your application

Chain Reference

View all supported chains and capabilities

Getting Started

SDK Guide

CLI Guide

Concepts

Examples

Configuration Sources

Configuration File

Creating a Config File

Configuration Options

Wallet Authentication

1. Private Key (Environment Variable)

2. Keystore File

Default Keystore Locations

Setting Up a Keystore

Environment Variables

Available Variables

Examples

Custom RPC Endpoints

Configuration File

Chain Names for RPC URLs

Popular RPC Providers

Alchemy

Infura

QuickNode

Ankr

LlamaRPC

Self-hosted

Default Values

Saved Addresses

Configuration Examples

Configuration Precedence Example

Security Best Practices

Troubleshooting

Next Steps

Commands

Quick Start

SDK Integration

Chain Reference

Build docs developers (and LLMs) love

Getting Started

SDK Guide

CLI Guide

Concepts

Examples

​Configuration Sources

​Configuration File

​Creating a Config File

​Configuration Options

​Wallet Authentication

​1. Private Key (Environment Variable)

​2. Keystore File

​Default Keystore Locations

​Setting Up a Keystore

​Environment Variables

​Available Variables

​Examples

​Custom RPC Endpoints

​Configuration File

​Chain Names for RPC URLs

​Popular RPC Providers

Alchemy

Infura

QuickNode

Ankr

LlamaRPC

Self-hosted

​Default Values

​Saved Addresses

​Configuration Examples

​Configuration Precedence Example

​Security Best Practices

​Troubleshooting

​Next Steps

Commands

Quick Start

SDK Integration

Chain Reference

Build docs developers (and LLMs) love

Configuration Sources

Configuration File

Creating a Config File

Configuration Options

Wallet Authentication

1. Private Key (Environment Variable)

2. Keystore File

Default Keystore Locations

Setting Up a Keystore

Environment Variables

Available Variables

Examples

Custom RPC Endpoints

Configuration File

Chain Names for RPC URLs

Popular RPC Providers

Default Values

Saved Addresses

Configuration Examples

Configuration Precedence Example

Security Best Practices

Troubleshooting

Next Steps