Skip to main content

​
Overview

This page provides a comprehensive reference for all CLI parameters and flags available in Chainbench’s start command.

​
Usage

chainbench start [METHOD] [OPTIONS]

​
Core Parameters

​
Target Configuration

​
--target
string
required
The blockchain node endpoint URL to test against.
chainbench start --target https://eth-mainnet.example.com
Required for initializing test data. If running in Web UI mode, you can change it later, but it must match the blockchain type of the initialized test data.
​
--ref-url
string
Reference node URL for retrieving test data before the test starts.If not specified, the target URL is used for test data generation.
chainbench start --target https://test-node --ref-url https://archive-node

​
Profile Selection

​
method
string
A specific RPC method to test (positional argument).
chainbench start eth_blockNumber --users 50 --workers 2
When using the method argument, --profile and --profile-dir options are ignored.
Use chainbench list methods to see all available methods.
​
-p, --profile
string
Profile to run. Profiles contain multiple methods with configured weights.
chainbench start --profile ethereum.general --target https://eth-node
Use chainbench list profiles to see all available profiles.
​
-d, --profile-dir
path
Custom directory containing profiles. Supports up to one level of subdirectories.
chainbench start --profile-dir /path/to/profiles --profile custom.profile
​
--profile-path
path
Full path to a specific profile locustfile.This overrides both --profile and --profile-dir options.
chainbench start --profile-path /path/to/my-profile.py --target https://node

​
Load Configuration

​
-u, --users
integer
default:"100"
Target number of concurrent simulated users.
chainbench start --users 200 --profile evm.light
​
-r, --spawn-rate
integer
default:"10"
Number of users spawned per second during ramp-up.
chainbench start --users 100 --spawn-rate 5
​
-w, --workers
integer
default:"8"
Number of worker processes to run.More workers can generate higher load but consume more system resources.
chainbench start --workers 4 --profile bsc.general
​
-t, --test-time
string
default:"5m"
Duration of the test run. Accepts time formats like 30s, 5m, 2h, 12h.
chainbench start --test-time 1h --profile evm.light
​
-s, --shape
string
Load pattern shape to use. Controls how load is distributed over time.Available shapes: step, spike
chainbench start --shape step --users 100 --spawn-rate 10
Use chainbench list shapes to see all available shapes. See Load Shapes for details.

​
Execution Mode

​
--headless
boolean
default:"false"
Run in headless mode without the web UI.
chainbench start --headless --profile evm.light --target https://node
Required for running on remote servers or in automated environments.
​
--autoquit
boolean
default:"false"
Automatically quit after the test completes.
chainbench start --headless --autoquit --test-time 1h
Useful for automated testing and CI/CD pipelines.

​
Network Configuration

​
-H, --host
string
default:"127.0.0.1"
Host address for the Locust master process.
chainbench start --host 0.0.0.0 --port 8089
​
-P, --port
string
default:"5557"
Port for the Locust master process.
chainbench start --port 5558

​
Test Data Configuration

​
--size
string
default:"S"
Size of test data to generate. Determines how many blocks are used.Available values:
  • XS: 10 blocks
  • S: 100 blocks (default)
  • M: 1,000 blocks
  • L: 10,000 blocks
  • XL: 100,000 blocks
chainbench start --size M --profile ethereum.general
Larger data sizes result in longer test data generation time before the test starts.
​
--use-latest-blocks
boolean
default:"false"
Use the latest blocks for test data generation and continuously update test data.
chainbench start --use-latest-blocks --size S --target https://node
Recommended for nodes running in sync modes that don’t have access to full blockchain history (e.g., nodes that only keep the last 128 blocks).
​
--start-block
integer
Starting block number for generating test data.Must be used together with --end-block.
chainbench start --start-block 1000000 --end-block 1001000
Ignored if --use-latest-blocks is set.
​
--end-block
integer
Ending block number for generating test data.Must be greater than --start-block.
chainbench start --start-block 1000000 --end-block 1001000

​
Task Filtering

​
--debug-trace-methods
boolean
default:"false"
Enable execution of tasks tagged with debug or trace.
chainbench start --debug-trace-methods --profile evm.heavy
By default, debug and trace methods are excluded from tests.
​
-E, --exclude-tags
string[]
Exclude tasks with specific custom tags from the test.Can be specified multiple times for different tags.
chainbench start -E slow -E experimental --profile custom

​
Batch Mode

​
--batch
boolean
default:"false"
Run tests in batch mode for JSON-RPC methods.Makes requests in batches instead of individual calls.
chainbench start --batch --batch-size 20 --profile evm.light
​
--batch-size
integer
default:"10"
Number of requests per batch for JSON-RPC methods.Only used when --batch flag is set.
chainbench start --batch --batch-size 25

​
Results and Logging

​
--results-dir
path
default:"results"
Directory to save test results.Results are saved to {results-dir}/{profile_or_method_name}/{timestamp}/
chainbench start --results-dir /data/benchmarks --profile evm.light
​
--run-id
string
Custom identifier for the test run.When specified, results are saved to {results-dir}/{run-id}/ instead of using a timestamp.
chainbench start --run-id experiment-001 --profile custom
​
--log-level
string
default:"INFO"
Logging level for test execution.Available values: DEBUG, INFO, WARNING, ERROR, CRITICAL
chainbench start --log-level DEBUG --profile evm.light

​
Monitoring

​
-m, --monitor
string[]
Add monitors to collect additional data or metrics during the test.Can be specified multiple times for different monitors. Only works in headless mode.Available monitors:
  • sync-lag-monitor: Tracks how much the node lags behind current time
chainbench start --headless -m sync-lag-monitor --profile evm.light
​
--notify
string
Topic name for ntfy.sh notifications when the test starts and finishes.
chainbench start --notify my-test-topic --headless --autoquit
Notifications are sent to https://ntfy.sh/{topic}

​
TimescaleDB Export

​
--timescale
boolean
default:"false"
Export test data to PostgreSQL with TimescaleDB extension.Requires all PG connection parameters.
chainbench start --timescale --pg-host localhost --pg-port 5432 \
  --pg-username postgres --pg-password secret
​
--pg-host
string
Hostname of PostgreSQL instance with TimescaleDB extension.Required when --timescale is enabled.
​
--pg-port
integer
default:"5432"
Port of PostgreSQL instance with TimescaleDB extension.
​
--pg-username
string
default:"postgres"
PostgreSQL username for authentication.
​
--pg-password
string
PostgreSQL password for authentication.Required when --timescale is enabled.

​
Examples

​
Basic Test

Run a simple test with default settings: 
chainbench start eth_blockNumber --target https://eth-node --headless --autoquit

​
Production-Like Load Test

Run a comprehensive test with high load: 
chainbench start --profile ethereum.general \
  --users 500 \
  --spawn-rate 50 \
  --workers 8 \
  --test-time 6h \
  --target https://eth-mainnet-node \
  --headless \
  --autoquit \
  --size L \
  --results-dir /data/benchmarks \
  -m sync-lag-monitor

​
Custom Block Range

Test with a specific block range: 
chainbench start --profile evm.light \
  --start-block 18000000 \
  --end-block 18001000 \
  --target https://eth-node \
  --headless

​
Batch Mode Testing

Test with batch requests: 
chainbench start --profile evm.light \
  --batch \
  --batch-size 50 \
  --users 100 \
  --target https://eth-node \
  --headless

​
Remote Server Deployment

Run in the background on a remote server: 
nohup chainbench start --profile bsc.general \
  --workers 4 \
  --users 200 \
  --test-time 12h \
  --target https://bsc-node \
  --headless \
  --autoquit \
  --notify my-benchmark-alerts &

Build docs developers (and LLMs) love

Get started for freeTalk to us