ironflow emit

Emit a named event to the server. If any registered functions have triggers matching the event name, runs will be created for them.

ironflow emit <event-name> [flags]

By default, the event is emitted asynchronously — the command prints the event ID and any triggered runs, then exits immediately. Use --wait to block until all triggered runs complete.

Arguments:

Argument	Required	Description
event-name	Yes	The event name (e.g., order.placed)

Flags:

Flag	Short	Type	Default	Description
--data	-d	string		Inline JSON data payload (defaults to {})
--data-file	-f	string		Path to JSON file containing data payload
--metadata	-m	string[]		Key=value metadata pairs (repeatable)
--wait	-w	bool	false	Block until all matched runs complete
--timeout	-t	duration	30s	Max wait time (only with --wait)
--version		int	1	Event schema version
--json		bool	false	Output as JSON instead of human-friendly text
--server	-s	string		Server URL override

Data input:

Data comes from exactly one source. If multiple are detected, the command errors:

1. --data '{...}' — Inline JSON string
2. --data-file path.json — Read from file
3. Stdin — Automatically detected when input is piped

If none are provided, data defaults to {} (empty object).

Examples:

# Emit with inline data
ironflow emit order.placed --data '{"order_id": "123", "total": 99.99}'

# Emit from a file
ironflow emit user.signup --data-file ./test-user.json

# Pipe from stdin
echo '{"batch_id": "daily"}' | ironflow emit cron.daily

# Signal event with no data
ironflow emit cache.invalidate

# Wait for all runs to complete
ironflow emit order.placed --data '{"order_id": "123"}' --wait

# Wait with custom timeout
ironflow emit video.uploaded --data-file ./meta.json --wait --timeout 120s

# JSON output for scripting
ironflow emit order.placed --data '{}' --wait --json | jq '.results[0]'

# Attach metadata
ironflow emit order.placed --data '{}' -m source=cli -m env=dev

# Emit with a specific event version
ironflow emit order.placed --data '{"order_id": "123"}' --version 2

Output (async):

Event emitted: evt_01HN8K3X5Y (order.placed)
Triggered 2 run(s): run_abc123, run_def456

Output (—wait):

Emitting event "order.placed" and waiting for completion (timeout: 30s)...
✓ process-order              RUN_STATUS_COMPLETED 1200ms   {"order_confirmed":true}
✓ send-notification          RUN_STATUS_COMPLETED 300ms    {"email_sent":true}

Failed or timed-out runs produce a non-zero exit code. When the wait expires, the run continues. Human output prints its run ID and current status. --json still writes the full response, including waitTimedOut: true, before exiting non-zero.

---