Replay CLI
Preview and replay one bounded Kafka slice at a time.
The current replay engine is intentionally narrow: one topic, one partition, one closed offset range or timestamp window, and one destination topic.
Command Contract
npm run replay:cli -- --source <topic> --destination <topic> --partition <id> --start <offset> --end <offset>npm run replay:cli -- --source <topic> --destination <topic> --partition <id> --start-timestamp <timestamp> --end-timestamp <timestamp>| Flag | Purpose |
|---|---|
--source | Source topic to read from |
--destination | Existing topic to write replayed records into |
--partition | Single source partition for the run |
--start | Inclusive starting offset |
--end | Inclusive ending offset |
--start-timestamp | Inclusive ISO timestamp or epoch milliseconds |
--end-timestamp | Exclusive ISO timestamp or epoch milliseconds |
--messages-per-second | Optional write cap for actual replay execution |
--dry-run | Preview the replay without producing |
--job-id | Stable replay identifier for logs and headers |
--brokers | Override the broker list instead of using KAFKA_BROKERS |
--progress-every | Log every N replayed messages |
Replay Examples
npm run replay:cli -- --source orders --destination orders-replay --partition 0 --start 10 --end 25 --job-id incident-2026-04-28npm run replay:cli -- --source orders --destination orders-replay --partition 0 --start 10 --end 25 --dry-run --job-id incident-2026-04-28npm run replay:cli -- --source orders --destination orders-replay --partition 0 --start 10 --end 25 --messages-per-second 10 --job-id incident-throttled-2026-04-28npm run replay:cli -- --source orders --destination orders-replay --partition 0 --start-timestamp 2026-04-28T14:03:00.000Z --end-timestamp 2026-04-28T14:08:00.000Z --job-id incident-window-2026-04-28Dry-Run Preview
Dry-run validates the replay request, reads the exact range, and prints a per-message preview including the headers that would be written. It does not connect a producer or advance the destination topic offsets.
Timestamp Windows
Timestamp replay resolves the requested window to concrete offsets before consuming records. The start timestamp is inclusive and the end timestamp is exclusive. If the window resolves to no retained messages, the command fails before replay begins.
Replay Throttling
--messages-per-second caps writes to the destination
topic during actual replay execution. Preview stays fast because it
does not produce records.
Replay Headers
| Header | Meaning |
|---|---|
x-replayed | Marks the record as replayed |
x-replay-job-id | Stable run identifier |
x-original-topic | Original topic name |
x-original-partition | Original partition number |
x-original-offset | Original source offset |
Safety Checks
- Source and destination topics must differ.
- Both topics must exist.
- The requested partition must exist on both topics.
- The start offset must not be older than the retained low watermark.
- The end offset must be lower than the source topic's next unread offset.
- Timestamp windows must resolve to a non-empty retained offset range.
- Messages per second, when set, must be a positive integer.