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 with the payload (- reads stdin)
--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
--idempotency-key		string		Deduplication key. A repeat emit with the same key returns the original event instead of emitting a second one. Keys are shared across the environment, so use one key per operation (for example order-123-placed) and never reuse it for a different event or function
--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. Passing both flags is an error:

1. --data '{...}' — Inline JSON string
2. --data-file path.json — Read from file. --data-file - reads stdin

Stdin is read only for --data-file -. Without that flag, a pipe on stdin is ignored and the command prints a note on stderr, and a non-empty file redirected to stdin (< payload.json) is an error. If neither flag is given, data defaults to {} (empty object). The payload can be any JSON value: an array or a scalar goes through as it is.

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

# 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

# Safe to retry: the same key never emits the event twice
ironflow emit order.placed --data '{"order_id": "123"}' --idempotency-key order-123-placed

Output (async):

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

When no function matches, the second line is No functions matched this event. With --json (no --wait), the command prints event_id, event and runs, an array of run_id and status objects. status is always waiting_for_capacity: the command does not read the run state.

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}

With --wait, a failed or timed-out run exits 1, with or without --json. With --json, the command prints the full result on stdout before it exits. A run that paused after exhausting its retries (status PAUSED) exits 1 in both modes and names ironflow run resume <run-id>. 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.

---