90 lines
1.6 KiB
Markdown
90 lines
1.6 KiB
Markdown
---
|
|
title: Build your first flow
|
|
description: Create a minimal Bun-backed flow package and run it locally.
|
|
---
|
|
|
|
# Build your first flow
|
|
|
|
This tutorial creates a flow package that handles a `demo.hello` event and
|
|
prints a `FLOW_RESULT`.
|
|
|
|
## 1. Create the files
|
|
|
|
Flow packages live under `flows/*` while installed copies can live under
|
|
`.codex/flows/*`. Create this structure:
|
|
|
|
```text
|
|
flows/hello-flow/
|
|
flow.toml
|
|
schemas/hello.schema.json
|
|
exec/hello.ts
|
|
```
|
|
|
|
## 2. Write the manifest
|
|
|
|
```toml
|
|
name = "hello-flow"
|
|
version = 1
|
|
description = "Greets a person from a demo event."
|
|
|
|
[[steps]]
|
|
name = "hello"
|
|
runner = "bun"
|
|
script = "exec/hello.ts"
|
|
timeout_ms = 30000
|
|
|
|
[steps.trigger]
|
|
type = "demo.hello"
|
|
schema = "schemas/hello.schema.json"
|
|
```
|
|
|
|
## 3. Add the event schema
|
|
|
|
```json
|
|
{
|
|
"type": "object",
|
|
"required": ["name"],
|
|
"properties": {
|
|
"name": { "type": "string" }
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4. Implement the step
|
|
|
|
```ts
|
|
const context = JSON.parse(await Bun.stdin.text());
|
|
const name = context.flow.event.payload.name;
|
|
|
|
console.log(`FLOW_RESULT ${JSON.stringify({
|
|
status: "completed",
|
|
message: `hello ${name}`,
|
|
})}`);
|
|
```
|
|
|
|
The runner sends JSON on stdin. The step must print a final line beginning with
|
|
`FLOW_RESULT ` followed by JSON.
|
|
|
|
## 5. Fire the event
|
|
|
|
Create `event.json`:
|
|
|
|
```json
|
|
{
|
|
"id": "demo:hello:ada",
|
|
"type": "demo.hello",
|
|
"source": "tutorial",
|
|
"receivedAt": "2026-05-15T00:00:00.000Z",
|
|
"payload": {
|
|
"name": "Ada"
|
|
}
|
|
}
|
|
```
|
|
|
|
Run all matching steps:
|
|
|
|
```bash
|
|
bun run flow fire --event event.json
|
|
```
|
|
|
|
You should see the event id and one result for `hello-flow/hello`.
|