ironflow stream

Manage entity streams for event sourcing.

ironflow stream <subcommand> [flags]

Entity streams store domain events per entity with optimistic concurrency control.

ironflow stream append

Append a domain event to an entity stream.

ironflow stream append <entity-id> [flags]

Arguments:

Argument	Required	Description
entity-id	Yes	The entity ID to append the event to

Flags:

Flag	Short	Type	Default	Description
--type		string		Entity type (e.g., Order, User)
--event		string		Event name (required)
--data	-d	string		Event data as JSON string
--data-file	-f	string		Path to JSON file with event data (- reads stdin)
--expected-version		int64	-1	Expected stream version (-1=skip, 0=new, N=exact)
--version		int	1	Event schema version
--idempotency-key		string		Idempotency key for deduplication
--json		bool	false	Output as JSON
--server	-s	string	$IRONFLOW_SERVER_URL or http://localhost:9123	Server URL

Data input follows the same rules as emit (flag or file, --data-file - for stdin, error on conflict).

An append publishes the event to the entity topic and to the events topic that projections read. Do not run ironflow emit for the same fact after an append. Projections then receive the fact twice.

Examples:

# Append an event
ironflow stream append order-1 --type Order --event order.placed --data '{"amount": 100}'

# Append from file
ironflow stream append order-1 --type Order --event order.paid --data-file payment.json

# With optimistic concurrency
ironflow stream append order-1 --type Order --event order.shipped --expected-version 2

# Pipe from stdin
echo '{"status": "done"}' | ironflow stream append order-1 --type Order --event order.completed --data-file -

Output:

Event appended: evt_01HN8K3X5Y
Entity:         order-1
Version:        3

ironflow stream read

Read events from an entity stream.

ironflow stream read <entity-id> [flags]

Arguments:

Argument	Required	Description
entity-id	Yes	The entity ID to read

Flags:

Flag	Short	Type	Default	Description
--from-version		int64	0	Start reading from this version
--limit		int32	100	Maximum number of events to return
--direction		string	forward	Read direction (forward or backward)
--json		bool	false	Output as JSON
--server	-s	string	$IRONFLOW_SERVER_URL or http://localhost:9123	Server URL

Output:

VERSION  NAME           DATA                           TIMESTAMP
1        order.placed   {"amount":100}                 2025-01-15 12:00:05
2        order.paid     {"payment_id":"pay_123"}       2025-01-15 12:01:30

Examples:

ironflow stream read order-1
ironflow stream read order-1 --limit 10
ironflow stream read order-1 --from-version 5 --direction backward
ironflow stream read order-1 --json

ironflow stream info

Get metadata about an entity stream.

ironflow stream info <entity-id> [flags]

Arguments:

Argument	Required	Description
entity-id	Yes	The entity ID to inspect

Flags:

Flag	Short	Type	Default	Description
--json		bool	false	Output as JSON
--server	-s	string	$IRONFLOW_SERVER_URL or http://localhost:9123	Server URL

Output:

Entity ID:   order-1
Entity Type: Order
Version:     3
Events:      3
Created:     2025-01-15T12:00:05Z
Updated:     2025-01-15T12:01:30Z

ironflow stream list

List entity streams with optional filtering by type.

ironflow stream list [flags]

Flags:

Flag	Short	Type	Default	Description
--type		string		Filter by entity type
--limit		int32	50	Maximum number of streams
--offset		int32	0	Offset for pagination
--json		bool	false	Output as JSON
--server	-s	string	$IRONFLOW_SERVER_URL or http://localhost:9123	Server URL

Output:

ENTITY_ID   TYPE    VERSION  EVENTS  UPDATED
order-1     Order   3        3       2m ago
order-2     Order   1        1       5m ago
user-1      User    2        2       1h ago

ironflow stream delete

Delete an entity stream. Appends a $stream.deleted tombstone at the next version and drops the stream’s snapshots; further appends are refused. --purge also deletes every event below the tombstone. Irreversible; prompts for confirmation unless --yes is passed.

Requires streams:delete, which only admin holds by default.

Two things the prompt will tell you, worth knowing before you run it:

• Without --purge the events survive only if the server has no entity-event retention window. IRONFLOW_ENTITY_EVENT_RETENTION_DAYS windows on each event’s age, not the tombstone’s, so where it is set, tombstoning an old stream can hand its whole history to that night’s sweep.
• --purge is refused while any run those events triggered is still active. It cascade-deletes runs through runs.event_id, and the cascade does not check status. The command exits non-zero and deletes nothing; the tombstone already blocks new appends, so retry once the runs finish.

On PostgreSQL, --purge does not wait on those runs or their rows. It is refused while another call holds one of them or a row of one, for example a step report in progress, a run invoked from one of them, or the lease a cancelled run still holds. The command exits non-zero and deletes nothing. The write ends on its own, so run the command again. --purge can still wait on the stream’s event rows, for example for a run redaction to commit, before it answers.

ironflow stream delete <entity-id> [flags]

Arguments:

Argument	Required	Description
entity-id	Yes	The entity ID to delete

Flags:

Flag	Short	Type	Default	Description
--purge		bool	false	Also delete every event below the tombstone
--yes		bool	false	Skip confirmation prompt
--server	-s	string	$IRONFLOW_SERVER_URL or http://localhost:9123	Server URL

Examples:

ironflow stream delete order-1
ironflow stream delete order-1 --purge --yes

Output:

Deleted stream order-1 (tombstone at version 3)

With --purge, the output reads Deleted stream order-1 and purged its history (tombstone at version 3).

Requires streams:delete (admin by default).

ironflow stream subscribe

Watch real-time events for an entity stream via WebSocket.

ironflow stream subscribe <entity-id> [flags]

Arguments:

Argument	Required	Description
entity-id	Yes	The entity ID to subscribe to

Flags:

Flag	Short	Type	Default	Description
--server	-s	string	ws://localhost:9123/ws (derived from IRONFLOW_SERVER_URL if set)	WebSocket server URL
--replay	-r	int	0	Number of historical events to replay
--json	-j	bool	false	Output events as JSON
--metadata	-m	bool	false	Include event metadata

Examples:

ironflow stream subscribe order-123
ironflow stream subscribe order-123 --replay 10
ironflow stream subscribe order-123 --json

---