EDR CLI reference

influxdb3-edr

influxdb3-edr [OPTIONS]

• --config <PATH>—path to the replication config YAML file.
• --data-dir <PATH>—InfluxDB data directory (shared object store).
• --token-store <PATH>—path to the token store directory. Accepts raw token files or server token JSON files containing a token field. Env: INFLUXDB3_EDR_TOKEN_STORE. See Manage tokens.
• --listen <ADDR:PORT>—network listener for the replication protocol (/edr/v1/connect|data|report) and /health. Must be reachable by upstreams. 0.0.0.0:0 for an OS-assigned port. Env: INFLUXDB3_EDR_LISTEN.
• --observability-listen <ADDR:PORT>—loopback by default: the UI, /metrics, and the JSON observability API. Set to 0.0.0.0:<PORT> (or a specific interface) to expose for off-host Prometheus or a remote UI. Env: INFLUXDB3_EDR_OBSERVABILITY_LISTEN.
• --listener-file-path <PATH>—file to write the actual network listener address to (for testing with port 0).
• --state-location <URL/PATH>—state persistence location, independent of --object-store-type. A path or file:// URL is local; s3://bucket/prefix, gs://..., az://... are object storage (credentials and region from the environment). Holds wal_cursor.json, gap_ledger.json, historic_manifest.json. Env: INFLUXDB3_EDR_STATE_LOCATION.
• --poll-interval-ms <MS>—object store polling interval in milliseconds.
• --object-store-type <TYPE>—override the object store type (s3, google, azure). Uses environment variables for credentials.
• --wal-cleanup-enabled—opt-in. With high server WAL retention, this is the supported production pattern. Enables agent-side deletion of already-replicated WAL files from the source object store, so they don’t build up past the replicated journal. Off by default (deleting source WAL is destructive). See Size WAL retention. Env: INFLUXDB3_EDR_WAL_CLEANUP_ENABLED.
• --wal-cleanup-interval-secs <S>—how often the cleanup sweep runs (only when enabled). Env: INFLUXDB3_EDR_WAL_CLEANUP_INTERVAL_SECS.
• --wal-cleanup-snapshot-margin <N>—WAL files to keep below the last snapshotted WAL id, the safety margin behind the snapshot boundary (only when enabled). Env: INFLUXDB3_EDR_WAL_CLEANUP_SNAPSHOT_MARGIN.
• --wal-cleanup-max-destination-hold <D>—fan-out only: a destination whose cursor hasn’t advanced for this long ("7d", "12h", "30m") stops holding the cleanup floor; it recovers the evicted range through gap fill when it returns (over-replication, never loss). Unset means a down destination pins WAL indefinitely. Env: INFLUXDB3_EDR_WAL_CLEANUP_MAX_DESTINATION_HOLD.
• --benchmark <N>—run a bandwidth benchmark against up to N WAL files and exit.

State and index files live wherever you point them. Use durable local storage or object storage for agent state. The state file holds the WAL cursor (what has been replicated); losing it forces re-replication from the snapshot boundary, which is safe but wasteful. The index file is an append-only change-tracking log.

Environment variables

edr-inspect

edr-inspect is a read-only triage CLI shipped alongside the agent.

state works even against a stopped or wedged agent (it reads the journals directly); it also accepts a cloud state-location (s3://, gs://, or az://, credentials from the environment). metrics and topology default to the loopback observability address ($INFLUXDB3_EDR_OBSERVABILITY_LISTEN). edr-inspect needs no --data-dir—it reads only the state journals and the agent’s /metrics, never the object store.

For usage in Docker through docker exec, see Run EDR in Docker.