CLI & env vars

How it works

Startup sequence. main() registers a signal.NotifyContext on SIGINT/SIGTERM (cmd/erpc/main.go:L72), builds a CLI app via github.com/urfave/cli/v3, and calls cmd.Run. For the start/default action, baseCliAction calls getConfig then erpc.Init. erpc.Init (erpc/init.go:L19) runs in order:

1. Set zerolog global level from cfg.LogLevel.
2. Log the final config as JSON at INFO (may contain redacted secrets).
3. Install histogram buckets and label filter.
4. Register a global network-alias resolver for metrics label consistency.
5. Init EVM JSON-RPC cache if configured (failures are warnings, not fatal).
6. Init shared-state registry if configured (same warn-on-fail pattern).
7. Build ERPC core: tracing, rate limiters, proxy pool, shared-state fallback, vendors registry, projects registry.
8. Call erpcInstance.Bootstrap(appCtx) — eager network bootstrap in background goroutines.
9. Start HTTP server goroutine.
10. Optionally start a standalone gRPC server if gRPC is enabled and does not share the HTTP v4 port.
11. Start Prometheus metrics server.
12. Block on <-appCtx.Done(), then sleep server.waitAfterShutdown before returning.

Config file search order. When --config and a positional argument are both absent and --require-config is not set, getConfig probes (cmd/erpc/main.go:L279-L293):

1. ./erpc.yaml
2. ./erpc.yml
3. ./erpc.ts
4. ./erpc.js
5. /erpc.yaml
6. /erpc.yml
7. /erpc.ts
8. /erpc.js
9. /root/erpc.yaml
10. /root/erpc.yml
11. /root/erpc.ts
12. /root/erpc.js

First path where fs.Stat succeeds wins. If none match and no --endpoint flag was supplied, eRPC starts with a synthetic main project using public RPC providers.

YAML loading. LoadConfig reads the file, runs os.ExpandEnv on raw bytes (common/config.go:L102), then decodes with gopkg.in/yaml.v3 in strict mode (KnownFields(true) — unknown keys are fatal). After decode: legacy migration hook (LegacyTranslateFn, wired to legacy.TranslateFromConfig at cmd/erpc/main.go:L36) fires first, potentially emitting zerolog Warn messages for deprecated fields, then SetDefaults, then Validate. Tests that exercise legacy YAML must set LegacyTranslateFn manually.

TypeScript/JS loading. loadConfigFromTypescript (common/config.go:L2686):

1. esbuild compiles the file as an IIFE bundle (Bundle:true, Format:IIFE, Target:ES2020, Platform:Node, GlobalName:"exports").
2. The tsLoaderWalker JS fragment is appended — it depth-first walks exports.default, assigns IDs (fn_0, fn_1, …) to every function-typed leaf, registers them in globalThis.__erpcFns[id], and stamps fn.__erpcFnId = id.
3. Combined source is compiled to a sobek.Program (userScript) and run in a temporary runtime.
4. JSON.stringify with a replacer converts functions to "__ts_fn__:fn_<n>" sentinels; functions not reached by the walker are dropped silently.
5. The resulting JSON is decoded through yaml.Decoder with KnownFields(true).
6. cfg.UserScript is set; the policy-engine pool re-runs this program in each acquired sobek runtime to reconstruct live __erpcFns references — no .toString() round-trip, closures preserved.

validate subcommand. Loads config, calls erpc.GenerateValidationReport which builds a resource tree and checks for orphan rate-limit budgets, public endpoints, and static-analysis issues. Output is JSON (default) or Markdown. Exits 0 when errors is empty, 1 otherwise. All zerolog output is silenced via zerolog.SetGlobalLevel(zerolog.Disabled) before getConfig — no warnings from SetDefaults or Validate appear on stderr.

dump subcommand. Loads config, calls policy.ResolveEffectiveSelectionPolicies to fill in the effective selectionPolicy per network as the engine would derive it, then marshals to YAML (default) or JSON. Useful for verifying what a TypeScript config actually produces. Log output is also suppressed.

Graceful shutdown. On SIGINT/SIGTERM: signal.NotifyContext cancels appCtx. The HTTP server's goroutine wakes, sleeps server.waitBeforeShutdown (default 10 s — gives Kubernetes time to mark the pod NotReady), then calls srv.Shutdown(30 s budget). The metrics server shuts down with a 5 s budget. The OTel tracer provider shuts down in a goroutine with a 5 s budget. erpc.Init blocks on <-appCtx.Done() then sleeps server.waitAfterShutdown (default 10 s) before returning, allowing in-flight requests to drain.

pprof. A //go:build pprof file registers standard net/http/pprof routes and starts a listener at 0.0.0.0:<port> (default 6060; override with ERPC_PPROF_PORT). Mutex and block profiling are enabled at rate 1. The standard binary does not include pprof — build with -tags pprof to activate.

Config schema

CLI subcommands — cmd/erpc/main.go:L200-244

CLI flags — cmd/erpc/main.go:L76-94

--set / -s is not available. Commented out at cmd/erpc/main.go:L86-90. Passing it produces a framework-level flag error before any application code runs.

Top-level Config fields — common/config.go:L38-68

Environment variables

Instance-identity priority chain. Two functions resolve instance ID:

• Shared-state: INSTANCE_ID → POD_NAME → HOSTNAME → os.Hostname() → "unknown". Whitespace is trimmed at each step. data/shared_state_registry.go:L82-98
• Consensus: same env-var priority order but final fallback is SHA-256(unixNano+pid) truncated to 8 hex chars (computed once via sync.Once). Characters problematic for filenames (:, /, \, , *, ?, ") are sanitized to _ before the value is used as the {instanceId} token in dispute-log filenames. consensus/export_utils.go:L26-48

Setting INSTANCE_ID explicitly avoids both failure modes.

validate command output schema (JSON):

{
  "errors":   [],
  "warnings": [],
  "notices":  [],
  "resources": {
    "totals": { "projectsTotal": 0, "networksTotal": 0, "upstreamsTotal": 0, "rateLimitBudgetsTotal": 0 },
    "tree": {
      "projects":     [{ "id": "", "networks": [{ "id": "", "upstreams": [{ "id": "" }] }] }],
      "rateLimiters": { "budgets": [{ "id": "", "rulesCount": 0 }] }
    }
  }
}

Exit 0 if errors is empty, exit 1 otherwise.

Exit codes — util/exit.go:L7-10

• 1001 (ExitCodeERPCStartFailed) — CLI/config load failure or erpc.Init error.
• 1002 (ExitCodeHttpServerFailed) — HTTP or gRPC server fatal error.

Worked examples

All patterns below are distilled from real production fleets; comments explain the non-obvious choices.

1. CI validation gate before deploy. Production deployments run erpc validate in the pipeline before any image build or Helm upgrade. Exit code 0 means no errors; pipe through jq .errors for a clean failure message in CI logs without JSON noise:

# exits 0 when errors=[], exits 1 when errors is non-empty
erpc validate --config ./erpc.yaml --format json | jq '.errors'
 
# Markdown for PR comments or human-readable output in CI
erpc validate --config ./erpc.yaml --format md

2. Production log level: error in prod, info in staging, info in dev. Real fleets keep logLevel: error in production (high-QPS internal workloads) to suppress routine health-check noise, info in staging and dev where visibility matters. LOG_LEVEL=debug at runtime (without a deploy) is the escape hatch when diagnosing live issues:

# Production — suppress routine INFO chatter; errors surfaced by structured loglogLevel: error
# Staging / dev — info gives bootstrap/network visibility without trace flood# logLevel: info

3. Tuned metrics for multi-region fleet. Production edge deployments drop the user and composite histogram labels (high-cardinality from many API keys and composite request patterns) and set explicit bucket boundaries that match real p50/p99 latencies observed in the fleet. errorLabelMode: compact is always used in production to keep Prometheus cardinality bounded:

metrics:  enabled: true  port: 4001  hostV4: "0.0.0.0"  # Bucket edges aligned to observed p50 (~100ms) and p99 (~3s) latencies.  # Coarser than the default to keep time-series count down on large fleets.  histogramBuckets: "0.020,0.100,0.300,0.500,1,3,6,10"  # compact keeps error labels bounded; verbose creates a label value per  # error class — too many on multi-upstream deployments.  errorLabelMode: compact  # Drop high-cardinality labels from histograms only; counters keep them.  histogramDropLabels:    - user    - composite

4. Graceful shutdown for Kubernetes rolling deploys. Both Kubernetes and PaaS production deployments use 30s for both shutdown windows. waitBeforeShutdown gives Kubernetes time to update endpoints before the server starts refusing connections; waitAfterShutdown lets in-flight requests drain. INSTANCE_ID via the downward API prevents UpdatedBy collisions across pods in shared-state writes:

server:  # Allow Kubernetes to mark the pod NotReady before traffic stops arriving.  # Without this, rolling deploys produce connection errors during the gap.  waitBeforeShutdown: 30s  # Drain in-flight requests before the process exits.  waitAfterShutdown: 30s

Kubernetes pod spec fragment for the downward API:

env:
  - name: INSTANCE_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.name   # stable pod name; avoids UpdatedBy = "unknown"

5. Per-environment clusterKey for shared-state isolation. Each deployment uses a distinct clusterKey so prod, staging, and dev never share lock state. The top-level key propagates automatically unless database.sharedState.clusterKey is set explicitly:

database:  sharedState:    # Unique per deployment — prod/stage/dev must not share lock state.    # If this key collides across two fleets, they race each other's locks.    clusterKey: prod-us-east-1    connector:      driver: redis      redis:        uri: ${SHARED_STATE_REDIS_URL}

6. Quick smoke-test with a bare endpoint, no config file. Spin up eRPC against a single node to verify routing — no YAML required. Useful for local testing before writing a full config:

erpc --endpoint https://mainnet.infura.io/v3/$INFURA_KEY
# equivalent: erpc start --endpoint https://mainnet.infura.io/v3/$INFURA_KEY

7. Inspect the effective config produced by a TypeScript config. TypeScript arrow functions in selectionPolicy.evalFunc show up as __ts_fn__:fn_N sentinels; everything else renders as plain YAML. Use this to verify closures were detected by the walker:

erpc dump --config ./erpc.ts --format yaml
# or JSON for programmatic diffing:
erpc dump --config ./erpc.ts --format json | jq .

Request/response behavior

The CLI layer itself does not process JSON-RPC requests. The behaviors below govern how the bootstrap interacts with the process environment.

• .env file in os.Getwd() is loaded in init() before main() runs; values are available for YAML $VAR substitution. Non-existence is silently ignored; other errors are logged at ERROR. [cmd/erpc/main.go:L42-46]
• LOG_LEVEL env var overrides cfg.LogLevel after config load; a config-file logLevel: error can be trumped by LOG_LEVEL=debug without editing the file. [cmd/erpc/main.go:L354-363]
• validate and dump suppress all log output. zerolog.SetGlobalLevel(zerolog.Disabled) is called before getConfig runs (validate: cmd/erpc/main.go:L109; dump: cmd/erpc/main.go:L156); LOG_LEVEL has no effect during these commands.
• YAML strict-mode rejects unknown fields (KnownFields(true)); this applies to the JSON round-trip from TypeScript configs too. [common/config.go:L103]
• Shorthand upstream URLs (alchemy://KEY, infura://KEY, etc.) are converted to ProviderConfig and removed from p.Upstreams at SetDefaults time; after load they appear in p.Providers, not p.Upstreams. [common/defaults.go:L1164-1172]
• Key validation rules enforced by Config.Validate(): server.maxTimeout must be non-zero; each project needs at least one upstream or provider; selectionPolicy.evalTimeout must be strictly less than evalInterval; onlyNetworks and ignoreNetworks on a provider are mutually exclusive; database.sharedState.lockMaxWait and updateMaxWait must each be less than fallbackTimeout; database.sharedState.lockTtl must be at least as long as fallbackTimeout; connector-level failsafe may not use consensus or hedge.quantile. [common/validation.go:L15]

Best practices

• Run erpc validate --config ./erpc.yaml in every CI pipeline before shipping config changes — it catches unknown field typos, missing rate-limit budget references, and selectionPolicy compile errors without starting a server.
• Use erpc dump --config ./erpc.ts --format yaml when debugging TypeScript configs to see what the engine actually sees; TS function sentinels (__ts_fn__:fn_N) confirm functions were detected correctly.
• Always quote YAML values that may contain env vars with special characters: password: "${REDIS_PASSWORD}" not password: ${REDIS_PASSWORD} — a : in the expanded value will break YAML parsing silently.
• Set INSTANCE_ID (or POD_NAME via the Kubernetes downward API) explicitly in every deployment — without it, shared-state UpdatedBy falls back to "unknown" and collides across pods; consensus dispute-log filenames get unique hashes but shared-state writes do not.
• Do not build with -tags pprof in production unless you immediately firewall-restrict ERPC_PPROF_PORT — the listener binds 0.0.0.0, not localhost.
• Set LOG_WRITER=console only for local development; JSON output is required by every log-aggregation platform (Datadog, Grafana Loki, etc.) and the env var cannot be changed at runtime.
• In Kubernetes, add a preStop hook or rely on server.waitBeforeShutdown (default 10 s) to let the pod reach NotReady before requests stop arriving — skip this and you will see connection errors during rolling deploys.

Edge cases & gotchas

1. --config sets requireConfig=true implicitly. If the specified path does not exist, the process exits 1001 with no fallback to auto-discovery. [cmd/erpc/main.go:L300-302]
2. Positional argument works in all subcommands. erpc validate ./config.yaml and erpc dump ./config.yaml both work — first positional arg is treated as a config path with requireConfig=true. [cmd/erpc/main.go:L303-305]
3. YAML strict-mode rejects unknown fields. A typo in any YAML key is a fatal error — this also applies to the JSON round-trip from TypeScript configs.
4. Quoted YAML values required for env vars that may contain special chars. password: "${REDIS_PASSWORD}" is safe; password: ${REDIS_PASSWORD} is not if the value contains : or {.
5. TypeScript default-export must be the last statement. If a later expression overwrites exports.default, the earlier config object is lost. Error: "config object must be default exported from TypeScript code AND must be the last statement in the file". [common/config.go:L2715-2717]
6. TS functions in bare arrays are not walked. The tsLoaderWalker only descends into object properties, not bare array function elements. In practice selectionPolicy functions are always object values so this rarely matters.
7. Orphaned TS function silently dropped. A function not reached by the walker is dropped by the JSON.stringify replacer — the config field will be absent with no error. [common/config.go:L2736-2739]
8. validate/dump suppress all log output. zerolog.SetGlobalLevel(zerolog.Disabled) is called before getConfig. Warnings from SetDefaults, legacy migration, and validation do not appear. Use jq .errors on the JSON output. LOG_LEVEL has no effect here.
9. LOG_WRITER=console must be set before process start. Configured in init(), not hot-reloadable. In log-aggregation environments keep the default JSON writer.
10. pprof binds 0.0.0.0. All interfaces, not localhost-only. Firewall-restrict or avoid -tags pprof in production.
11. ERPC_NOMETRICS=1 is irreversible. Swaps the Prometheus default registry process-wide; cannot be undone within the same process.
12. INSTANCE_ID not stable across restarts = orphaned shared-state locks. Use a deployment-stable value (pod name, container ID).
13. dump --format csv (or any unknown format) exits 1 via a distinct code path. A marshal failure means config loaded but serialisation failed; an unsupported-format failure means serialisation was never attempted. Valid values: yaml, yml, json.
14. Shared-state falls back to "unknown" while consensus generates a hash. In environments with no env vars and os.Hostname() failing, shared-state UpdatedBy is "unknown" (collides across pods). Consensus dispute-log filenames get a unique 8-char hash. [data/shared_state_registry.go:L82-98] [consensus/export_utils.go:L26-48]
15. Provider endpoint env expansion runs after YAML-level expansion. Pipeline: (1) os.ExpandEnv on raw YAML bytes → YAML decode → SetDefaults (providers registered). Then at request time: (2) provider's GenerateConfigs builds endpoint strings → expandEnvVars calls os.ExpandEnv. Double-expansion is possible if the vendor builds an endpoint that itself contains $VAR literals. [thirdparty/provider.go:L67-71]
16. --set / -s is not implemented. The flag was planned as a Helm-style dot-path override but is commented out. Passing -s or --set produces "flag provided but not defined: -s" from the CLI framework. [cmd/erpc/main.go:L86-90]
17. Metrics server disabled in test builds. MetricsConfig.SetDefaults sets Enabled=true only when !util.IsTest(). Tests that need metrics must set metrics.enabled: true explicitly. [common/defaults.go:L750-752]
18. gRPC shares the HTTP handler when both addresses resolve to the same port. No separate grpcServer.Start goroutine runs. [erpc/init.go:L125]
19. Eager network bootstrap runs on appCtx; novel chains trigger the lazy path. Novel chain IDs arriving before bootstrap finishes block the request until init completes or the request context times out. [erpc/networks_registry.go:L195-212]
20. TypeScript process.env is a snapshot, not a live view. Built once when the sobek runtime is created from os.Environ(); a restart-less env var change requires all policy engine runtimes to be recreated.

Observability

The bootstrap/CLI layer emits no Prometheus metrics of its own. Key structured log messages (zerolog JSON unless LOG_WRITER=console):

Source code entry points

• cmd/erpc/main.go:L72-L305 (opens in a new tab) — signal handling, CLI command definitions, getConfig, auto-discovery, --endpoint injection
• erpc/init.go:L19-L180 (opens in a new tab) — Init(ctx, cfg): full startup + graceful drain sequence
• common/config.go:L95-L110 (opens in a new tab) — LoadConfig: os.ExpandEnv, YAML decode, legacy migration, SetDefaults, Validate
• common/config.go:L2686-L2740 (opens in a new tab) — loadConfigFromTypescript: esbuild, tsLoaderWalker, sobek eval, sentinel lifecycle
• common/defaults.go:L49-L176 (opens in a new tab) — Config.SetDefaults: full defaults cascade, synthetic main project injection
• common/validation.go:L15 (opens in a new tab) — Config.Validate: exhaustive validation rules
• cmd/erpc/pprof.go (opens in a new tab) — build-tag pprof: init() registering pprof routes and starting 0.0.0.0:<port> listener
• cmd/erpc/initflags.go (opens in a new tab) — build-tag !test: ERPC_NOLOGS and ERPC_NOMETRICS init hooks
• util/exit.go:L7-L10 (opens in a new tab) — exit codes 1001 (start failed) and 1002 (HTTP/gRPC server fatal)
• erpc/config_analyzer.go (opens in a new tab) — GenerateValidationReport, RenderValidationReportJSON, RenderValidationReportMarkdown
• common/runtime.go (opens in a new tab) — NewRuntime(): creates a sobek runtime, populates process.env map and env array from os.Environ(); used for TypeScript selection-policy evaluation
• common/compiler.go (opens in a new tab) — CompileTypeScript (esbuild IIFE bundle), CompileFunction (sobek single-function eval), CompileProgram (sobek.Compile with paren-wrap)

Related pages

• HTTP server — server bind addresses, timeouts, and graceful shutdown knobs.
• Deployment — Docker and Kubernetes deployment patterns, including POD_NAME downward API setup.
• Projects — the config structure that start and validate both load.
• Rate limiters — budget IDs that validation checks for orphan references.
• Observability — Prometheus metrics exposed on metrics.port.