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
--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		Server URL override

Data input follows the same rules as emit (flag vs file vs stdin, error on conflict).

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

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		int	100	Maximum number of events to return
--direction		string	forward	Read direction (forward or backward)
--json		bool	false	Output as JSON
--server	-s	string		Server URL override

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		Server URL override

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		int	50	Maximum number of streams
--offset		int	0	Offset for pagination
--json		bool	false	Output as JSON
--server	-s	string		Server URL override

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 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

---