Emitting Events

From the CLI

foundry emit <event_type> --project <project> [--throttle <level>] [--payload <json>]

Arguments

Examples

# Simple event, default throttle
foundry emit greet_requested --project hello

# With payload
foundry emit greet_requested --project hello --payload '{"name": "Stacey"}'

# Dry run — observe without mutating
foundry emit vulnerability_detected \
  --project my-tool \
  --throttle dry_run \
  --payload '{"cve": "CVE-2026-1234", "severity": "high"}'

# Dry run — no side effects at all
foundry emit maintenance_run_started \
  --project evt-cli \
  --throttle dry_run

What Happens When You Emit

1. The CLI sends the event to foundryd via gRPC
2. The engine creates an Event with a deterministic ID
3. The engine finds all task blocks that sink on the event type
4. For each matching block:
   • Check throttle: should this block execute? Should it emit?
   • Execute the block's work
   • Collect emitted events
5. Feed emitted events back into step 3 (the chain continues)
6. Return the initial event ID to the CLI

The chain continues until no more events are produced.

Inspecting a Completed Chain

After emitting an event, use foundry trace with the returned event ID to see the full propagation tree and what each block did:

$ foundry emit greet_requested --project hello --payload '{"name": "Stacey"}'
Event emitted: evt_47fcb603e1b18c8435b8cc3b

$ foundry trace evt_47fcb603e1b18c8435b8cc3b
greet_requested (evt_47fcb603e1b18c8435b8cc3b) project=hello
  → ComposeGreeting: ok — composed greeting for Stacey
    greeting_composed (evt_a1b2c3d4e5f6) project=hello
      → DeliverGreeting: ok — delivered greeting: Hello, Stacey!
        greeting_delivered (evt_f6e5d4c3b2a1) project=hello

Pass --verbose to also show trigger payloads, emitted payloads, raw shell output, and paths to any audit artefacts produced.

Persistent Trace Storage

Every completed event chain is written to disk under ~/.foundry/traces/YYYY-MM-DD/{event_id}.json (overridable via FOUNDRY_TRACES_DIR). Traces persist indefinitely across daemon restarts — there is no expiry TTL on disk.

To browse past traces, use foundry history:

# Show the last 7 days
foundry history

# Show a specific date
foundry history 2026-03-22

# Filter by project
foundry history --project my-tool

# Explicit local-file diagnostics when the daemon is stopped
foundry --offline history 2026-03-22 --project my-tool

By default foundry history is daemon-authoritative: it asks foundryd for the durable trace store and does not inspect the client-side FOUNDRY_TRACES_DIR. Use --offline deliberately when you want direct file diagnostics.

You can retrieve the full trace for any persisted event with foundry trace, even if the daemon has been restarted since the event was processed. If the trace is missing, the CLI reports No trace found for <event-id> (expired or unknown).