CLI Reference

This reference guide covers all commands, options, and configuration for the EvidentSource server CLI.

Command Structure

The EvidentSource CLI uses a hierarchical command structure:

evidentsource [GLOBAL_OPTIONS] <COMMAND> [COMMAND_OPTIONS] [SUBCOMMAND] [SUBCOMMAND_OPTIONS]

Global Options

These options are available for all commands:

Option	Description
-h, --help	Print help information
-V, --version	Print version information

Top-Level Commands

client

Client CLI functionality (placeholder for future features).

evidentsource client

Status: Not yet implemented. Reserved for future client utilities and operations.

server

Start the EvidentSource server with a specified storage adapter.

evidentsource server [OPTIONS] <ADAPTER>

Server Options

Options available for the server command:

Required Options

Option	Description
-s, --scheme <SCHEME>	Server protocol scheme: http or https

Network Options

Option	Environment Variable	Default	Description
-a, --authority <AUTHORITY>	-	localhost:3000	Server authority (host:port)
--http-port <PORT>	EVIDENT_HTTP_PORT	3000	HTTP server port
--grpc-port <PORT>	EVIDENT_GRPC_PORT	50051	gRPC server port

Runtime Configuration

Option	Environment Variable	Default	Description
--io-worker-threads <N>	EVIDENT_IO_WORKER_THREADS	cores/4 (min 4, max 8)	Number of IO runtime worker threads
--cpu-worker-threads <N>	EVIDENT_CPU_WORKER_THREADS	cores	Number of CPU runtime worker threads
--datafusion-memory-limit <BYTES>	EVIDENT_DATAFUSION_MEMORY_LIMIT	40% of RAM	Memory limit for DataFusion queries
--datafusion-batch-size <SIZE>	EVIDENT_DATAFUSION_BATCH_SIZE	4096	Batch size for DataFusion operations

WebAssembly Configuration

Option	Environment Variable	Default	Description
--wasm-epoch-increment-ms <MS>	WASM_EPOCH_INCREMENT_MS	10	Epoch increment interval in milliseconds
--wasm-epoch-deadline <EPOCHS>	WASM_EPOCH_DEADLINE	100	Number of epochs before yielding

Storage Adapters

in-memory

Run with an in-memory storage adapter (for development and testing only).

evidentsource server --scheme http in-memory

Features:

• Fast startup
• No persistence
• Suitable for development and testing
• Data lost on restart

Example:

# Start server on default ports
evidentsource server --scheme http in-memory

# Custom ports
evidentsource server \
  --scheme http \
  --http-port 8080 \
  --grpc-port 50051 \
  in-memory

dynamo-db

Run with DynamoDB storage adapter and a distributed linearizer.

evidentsource server --scheme http dynamo-db [OPTIONS] <LINEARIZER>

DynamoDB Options

Common options for all DynamoDB configurations:

Option	Environment Variable	Description
-t, --table <TABLE>	-	DynamoDB table name
--s3-bucket <BUCKET>	-	S3 bucket for event storage
--s3-prefix <PREFIX>	-	S3 key prefix (optional)
--sns-topic-arn <ARN>	INDEX_ROOT_SNS_TOPIC_ARN	SNS topic for index updates (optional)
--cache-max-entries <N>	EVIDENT_CACHE_MAX_ENTRIES	Maximum cache entries (default: 500000)
--cache-memory-limit <BYTES>	EVIDENT_CACHE_MEMORY_LIMIT	Cache memory limit (default: 30% of RAM)

Linearizers

DynamoDB adapter requires selecting a transaction linearizer for distributed transaction ordering.

kafka

Use Kafka-based transaction linearizer for distributed transaction ordering.

evidentsource server --scheme http dynamo-db [DYNAMODB_OPTIONS] kafka [KAFKA_OPTIONS]

Kafka Options

Option	Environment Variable	Default	Description
-k, --kafka-brokers <BROKERS>	KAFKA_BOOTSTRAP_SERVERS	-	Kafka bootstrap servers (required)
-n, --node-id <ID>	-	-	Unique node identifier (optional)
--node-host <HOST>	-	-	Host for internal gRPC (required)
--internal-grpc-port <PORT>	-	50052	Internal gRPC port
--transaction-proposals-topic <TOPIC>	KAFKA_TRANSACTION_PROPOSALS_TOPIC	transaction-proposals	Kafka topic for transaction proposals
--database-events-topic <TOPIC>	KAFKA_DATABASE_EVENTS_TOPIC	evidentsource-database-events	Kafka topic for database events
--consumer-group <GROUP>	KAFKA_CONSUMER_GROUP	evidentsource-transaction-linearizer	Kafka consumer group

Kafka Security Options

Option	Environment Variable	Description
--security-protocol <PROTOCOL>	KAFKA_SECURITY_PROTOCOL	Security protocol (e.g., SASL_SSL)
--sasl-mechanism <MECHANISM>	KAFKA_SASL_MECHANISM	SASL mechanism (e.g., PLAIN, SCRAM-SHA-256)
--sasl-username <USERNAME>	KAFKA_SASL_USERNAME	SASL username
--sasl-password <PASSWORD>	KAFKA_SASL_PASSWORD	SASL password

Example

# Basic Kafka configuration
evidentsource server --scheme http \
  dynamo-db \
    --table evidentsource-events \
    --s3-bucket evidentsource-storage \
  kafka \
    --kafka-brokers localhost:9092 \
    --node-host 0.0.0.0

# With SASL authentication
evidentsource server --scheme http \
  dynamo-db \
    --table evidentsource-events \
    --s3-bucket evidentsource-storage \
    --sns-topic-arn arn:aws:sns:us-east-1:123456789012:evidentsource-index-updates \
  kafka \
    --kafka-brokers kafka-1:9092,kafka-2:9092,kafka-3:9092 \
    --node-id node-1 \
    --node-host 10.0.1.100 \
    --security-protocol SASL_SSL \
    --sasl-mechanism SCRAM-SHA-256 \
    --sasl-username evidentsource \
    --sasl-password $KAFKA_PASSWORD

memberlist

Use Memberlist-based transaction linearizer for distributed transaction ordering via gossip protocol.

evidentsource server --scheme http dynamo-db [DYNAMODB_OPTIONS] memberlist [MEMBERLIST_OPTIONS]

Memberlist Options

Option	Default	Description
-n, --node-id <ID>	-	Unique node identifier (required)
--node-host <HOST>	-	Host for memberlist and internal gRPC (required)
--memberlist-port <PORT>	7946	Port for gossip protocol
--internal-grpc-port <PORT>	50052	Port for internal gRPC service

Example

# Basic memberlist configuration
evidentsource server --scheme http \
  dynamo-db \
    --table evidentsource-events \
    --s3-bucket evidentsource-storage \
  memberlist \
    --node-id node-1 \
    --node-host 10.0.1.100

# With custom ports
evidentsource server --scheme http \
  dynamo-db \
    --table evidentsource-events \
    --s3-bucket evidentsource-storage \
    --s3-prefix production/ \
    --sns-topic-arn arn:aws:sns:us-east-1:123456789012:evidentsource-index-updates \
    --cache-max-entries 1000000 \
  memberlist \
    --node-id node-1 \
    --node-host 0.0.0.0 \
    --memberlist-port 7946 \
    --internal-grpc-port 50052

Build Features

The server binary can be built with different feature sets for optimized deployments:

# Default build (includes all features - best for development)
cargo build

# Minimal in-memory only (fast builds, smallest binary)
cargo build --no-default-features --features in-memory

# DynamoDB only
cargo build --no-default-features --features dynamo-db

# Production release with DynamoDB and jemalloc
cargo build --release --no-default-features --features dynamo-db,jemalloc

Environment Variables

Server Configuration

Variable	Default	Description
EVIDENT_HTTP_PORT	3000	HTTP server port
EVIDENT_GRPC_PORT	50051	gRPC server port
EVIDENT_IO_WORKER_THREADS	cores/4	IO worker threads
EVIDENT_CPU_WORKER_THREADS	cores	CPU worker threads
EVIDENT_DATAFUSION_MEMORY_LIMIT	40% RAM	DataFusion memory limit
EVIDENT_DATAFUSION_BATCH_SIZE	4096	DataFusion batch size
EVIDENT_CACHE_MAX_ENTRIES	500000	Maximum cache entries
EVIDENT_CACHE_MEMORY_LIMIT	30% RAM	Cache memory limit

WebAssembly Configuration

Variable	Default	Description
WASM_EPOCH_INCREMENT_MS	10	Epoch increment interval
WASM_EPOCH_DEADLINE	100	Epochs before yielding

Observability

Variable	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4317	OpenTelemetry collector endpoint
OTEL_SERVICE_NAME	evidentsource-server	Service name for telemetry
OTEL_SERVICE_NAMESPACE	default	Service namespace
OTEL_SAMPLING_RATIO	1.0	Trace sampling ratio (0.0 to 1.0)
RUST_LOG	info	Logging level (trace, debug, info, warn, error)

AWS/DynamoDB Configuration

Variable	Description
AWS_REGION	AWS region (e.g., us-east-1)
AWS_ACCESS_KEY_ID	AWS access key
AWS_SECRET_ACCESS_KEY	AWS secret key
AWS_SESSION_TOKEN	AWS session token (for temporary credentials)
INDEX_ROOT_SNS_TOPIC_ARN	SNS topic ARN for index updates

Kafka Configuration

Variable	Default	Description
KAFKA_BOOTSTRAP_SERVERS	-	Kafka bootstrap servers
KAFKA_TRANSACTION_PROPOSALS_TOPIC	transaction-proposals	Topic for transaction proposals
KAFKA_DATABASE_EVENTS_TOPIC	evidentsource-database-events	Topic for database events
KAFKA_CONSUMER_GROUP	evidentsource-transaction-linearizer	Consumer group ID
KAFKA_SECURITY_PROTOCOL	-	Security protocol
KAFKA_SASL_MECHANISM	-	SASL mechanism
KAFKA_SASL_USERNAME	-	SASL username
KAFKA_SASL_PASSWORD	-	SASL password

Common Usage Patterns

Development

# Quick start with in-memory storage
evidentsource server --scheme http in-memory

# With debug logging
RUST_LOG=debug evidentsource server --scheme http in-memory

# Custom ports
evidentsource server \
  --scheme http \
  --http-port 8080 \
  --grpc-port 50051 \
  in-memory

Local AWS Testing (LocalStack)

# Start LocalStack first
# See deployment/local.md for LocalStack setup

# Run with DynamoDB + Kafka
AWS_ENDPOINT_URL=http://localhost:4566 \
KAFKA_BOOTSTRAP_SERVERS=localhost:9092 \
evidentsource server --scheme http \
  dynamo-db \
    --table evidentsource-local \
    --s3-bucket evidentsource-local-storage \
  kafka \
    --kafka-brokers localhost:9092 \
    --node-host 127.0.0.1

Production AWS Deployment

# With Kafka linearizer
evidentsource server --scheme https \
  --http-port 443 \
  --grpc-port 50051 \
  dynamo-db \
    --table evidentsource-prod \
    --s3-bucket evidentsource-prod-storage \
    --s3-prefix production/ \
    --sns-topic-arn arn:aws:sns:us-east-1:123456789012:evidentsource-updates \
  kafka \
    --kafka-brokers kafka-1.prod:9092,kafka-2.prod:9092,kafka-3.prod:9092 \
    --node-id $(hostname) \
    --node-host $(hostname -i) \
    --security-protocol SASL_SSL \
    --sasl-mechanism SCRAM-SHA-256 \
    --sasl-username evidentsource-prod \
    --sasl-password $KAFKA_PASSWORD

Production with Memberlist

# Memberlist linearizer (no Kafka required)
evidentsource server --scheme https \
  --http-port 443 \
  --grpc-port 50051 \
  dynamo-db \
    --table evidentsource-prod \
    --s3-bucket evidentsource-prod-storage \
    --cache-max-entries 1000000 \
  memberlist \
    --node-id $(hostname) \
    --node-host $(ec2-metadata --local-ipv4 | cut -d " " -f 2) \
    --memberlist-port 7946

Performance Tuning

Memory Configuration

# High-memory server (64GB RAM)
evidentsource server \
  --scheme http \
  --datafusion-memory-limit $((64 * 1024 * 1024 * 1024 * 40 / 100)) \
  --cache-memory-limit $((64 * 1024 * 1024 * 1024 * 30 / 100)) \
  --cache-max-entries 2000000 \
  dynamo-db --table events --s3-bucket storage \
  kafka --kafka-brokers kafka:9092 --node-host 0.0.0.0

Thread Configuration

# High-throughput configuration (32 cores)
evidentsource server \
  --scheme http \
  --io-worker-threads 8 \
  --cpu-worker-threads 32 \
  --datafusion-batch-size 8192 \
  dynamo-db --table events --s3-bucket storage \
  kafka --kafka-brokers kafka:9092 --node-host 0.0.0.0

Low-latency Configuration

# Optimized for low latency
evidentsource server \
  --scheme http \
  --datafusion-batch-size 1024 \
  --wasm-epoch-increment-ms 5 \
  --wasm-epoch-deadline 50 \
  dynamo-db --table events --s3-bucket storage \
  kafka --kafka-brokers kafka:9092 --node-host 0.0.0.0

Troubleshooting

Check Version

evidentsource --version

View Available Commands

evidentsource --help
evidentsource server --help
evidentsource server dynamo-db --help
evidentsource server dynamo-db kafka --help

Enable Debug Logging

RUST_LOG=debug evidentsource server --scheme http in-memory

Test Connectivity

# Start server
evidentsource server --scheme http in-memory

# In another terminal, test HTTP endpoint
curl http://localhost:3000/health

# Test gRPC endpoint (requires grpcurl)
grpcurl -plaintext localhost:50051 list

Common Issues

Port already in use:

# Use different ports
evidentsource server \
  --scheme http \
  --http-port 8080 \
  --grpc-port 50052 \
  in-memory

Permission denied:

# Check executable permissions
chmod +x evidentsource

AWS credentials not found:

# Set AWS credentials
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

Kafka connection failed:

# Verify Kafka brokers are reachable
nc -zv localhost 9092

# Check Kafka logs
RUST_LOG=rdkafka=debug evidentsource server --scheme http \
  dynamo-db --table test --s3-bucket test \
  kafka --kafka-brokers localhost:9092 --node-host 0.0.0.0

Next Steps

• Deployment Guide - Deploy to production
• Configuration - Learn about storage adapters
• API Reference - Explore the gRPC API
• Monitoring - Set up observability