Configuration overview

Learn how to configure Erst CLI using files, environment variables, and command-line flags

Erst CLI offers flexible configuration through multiple methods, with a clear precedence order to give you control at every level.

Configuration hierarchy

Configuration values are loaded in the following order, with later sources overriding earlier ones:

1. Default values - Built-in sensible defaults
2. Configuration files - TOML files on disk
3. Environment variables - System environment settings
4. Command-line flags - Direct CLI arguments

Command-line flags always take precedence over all other configuration methods.

Configuration files

Erst searches for TOML configuration files in these locations (in order):

1. .erst.toml in the current directory
2. ~/.erst.toml in your home directory
3. /etc/erst/config.toml system-wide configuration

Example configuration file

Copy erst.example.toml to one of the locations above:

~/.erst.toml

# RPC URL for the Stellar network (single URL)
rpc_url = "https://soroban-testnet.stellar.org"

# Multi-RPC URLs for automatic fallback (array syntax)
# rpc_urls = ["https://rpc1.stellar.org", "https://rpc2.stellar.org"]

# Network: public, testnet, futurenet, or standalone
network = "testnet"

# Path to the ERST simulator (optional)
# simulator_path = "/path/to/simulator"

# Log level: trace, debug, info, warn, error
log_level = "info"

# Cache directory for storing traces and snapshots
# cache_path = "~/.erst/cache"

# Request timeout in seconds (1-300)
# request_timeout = 15

# Opt-in anonymous crash reporting
# crash_reporting = false

Core configuration options

Network connection

rpc_url · string · default: "https://soroban-testnet.stellar.org"

Single RPC endpoint URL for connecting to the Stellar network.

rpc_urls · array

Array of RPC URLs for automatic fallback. Use this for high availability setups.

rpc_urls = ["https://rpc1.stellar.org", "https://rpc2.stellar.org"]

network · string · default: "testnet"

Network identifier. Valid values:

• public - Mainnet (https://soroban.stellar.org)
• testnet - Testnet (https://soroban-testnet.stellar.org)
• futurenet - Futurenet (https://soroban-futurenet.stellar.org)
• standalone - Local development (http://localhost:8000)

network_passphrase · string

Custom network passphrase for private networks. Required when using custom networks.

Standard passphrases:

• Mainnet: Public Global Stellar Network ; September 2015
• Testnet: Test SDF Network ; September 2015

Simulator settings

simulator_path · string

Custom path to the erst-sim binary. If not set, Erst searches:

1. Current directory (./erst-sim)
2. Development path (./simulator/target/release/erst-sim)
3. System PATH

Logging and debugging

log_level · string · default: "info"

Unified log level for both Go CLI and Rust simulator.

Valid values: trace, debug, info, warn, error

Storage and caching

cache_path · string · default: "~/.erst/cache"

Directory for storing transaction traces and snapshots.

Request settings

request_timeout · number · default: "15"

HTTP request timeout in seconds. Must be between 1 and 300.

rpc_token · string

Authentication token for RPC endpoints that require authorization.

Crash reporting

crash_reporting · boolean · default: "false"

Enable anonymous crash reporting to help improve Erst.

When enabled, fatal panics send minimal reports (error message, stack trace, OS/arch, version) to maintainers.

No transaction data or personal information is ever included.

crash_endpoint · string · default: "https://crash.erst.dev/v1/report"

Custom endpoint for crash reports. Only used when crash_reporting is enabled and no Sentry DSN is set.

crash_sentry_dsn · string

Sentry DSN for crash reporting. Obtain from your Sentry project settings.

crash_sentry_dsn = "https://<key>@<org>.ingest.sentry.io/<project>"

Configuration validation

Erst validates your configuration on startup and provides clear error messages:

Required fields

• rpc_url cannot be empty (unless using a named network)

Network validation

• network must be one of: public, testnet, futurenet, standalone

Request timeout validation

• request_timeout must be between 1 and 300 seconds

Default values

When no configuration is provided, Erst uses these defaults:

{
  "rpc_url": "https://soroban-testnet.stellar.org",
  "network": "testnet",
  "log_level": "info",
  "cache_path": "~/.erst/cache",
  "request_timeout": 15,
  "crash_reporting": false
}

Advanced configurations

Multi-RPC fallback

For production environments, configure multiple RPC endpoints:

rpc_urls = [
  "https://primary.stellar.org",
  "https://backup.stellar.org",
  "https://fallback.stellar.org"
]
network = "public"

Development setup

rpc_url = "http://localhost:8000/soroban/rpc"
network = "standalone"
log_level = "debug"
simulator_path = "./simulator/target/debug/erst-sim"

Production security

rpc_url = "https://soroban.stellar.org"
rpc_token = "your-api-token"
network = "public"
log_level = "warn"
crash_reporting = true
crash_sentry_dsn = "https://[e-mail]/project"

Configuration storage

Erst stores additional configuration data in:

• ~/.erst/config.json - General configuration (JSON format)
• ~/.erst/networks.json - Custom network profiles
• ~/.erst/cache/ - Transaction traces and snapshots

All configuration files use restricted permissions (0600) and directories use 0700 for security.

Viewing current configuration

Use the erst config command to view your current configuration:

erst config show

Next steps

Environment variables

Configure Erst using environment variables

Custom networks

Set up private and local Stellar networks