nats stream: Manage JetStream Streams
nats stream add <name> creates a JetStream stream that durably stores messages on its subjects, unlike fire-and-forget core NATS.
JetStream adds persistence to NATS. If your test relies on messages surviving until a consumer reads them, you need a stream, and nats stream is how you create and inspect one.
What it does
nats stream manages JetStream streams. add creates a stream capturing one or more subjects with a retention and storage policy; ls lists streams; info shows message count and state; rm deletes one. JetStream must be enabled on the server (nats-server -js or a config flag).
Common usage
# create a stream capturing orders.* subjects
nats stream add ORDERS \
--subjects 'orders.*' --storage file \
--retention limits --max-msgs=-1 --max-bytes=-1 \
--max-age=1h --defaults -s nats://localhost:4222
nats stream ls -s nats://localhost:4222
nats stream info ORDERS -s nats://localhost:4222Options
| Flag / sub | What it does |
|---|---|
| add <name> | Create a stream |
| --subjects <subj> | Subjects the stream captures |
| --storage file|memory | Where messages are stored |
| --retention limits|interest|work | Retention policy |
| --defaults | Accept defaults for unspecified prompts |
| ls / info / rm | List, inspect, or delete streams |
In CI
Pass --defaults (and the limits explicitly) so nats stream add does not drop into interactive prompts and hang. Use --storage memory for tests so nothing persists between runs, and create the stream before producing so JetStream captures your messages.
Common errors in CI
"nats: error: JetStream not enabled" or "context deadline exceeded" means the server was started without JetStream; run nats-server -js. "nats: error: stream name already in use" means the stream exists; use info or a fresh name. "no servers available for connection" is the server being down on 4222.