Recording a flow

Sometimes the fastest way to describe a scenario is to do it. klera gives you two ways to record yourself walking through the app and turn that walk-through into a .flow.md file you can keep, edit, and rerun.

You’ll pick between them based on who is doing the recording and where they’re standing.

Both produce the same output: a .flow.md file with prose you can clean up, plus a .flow.json cache that captures the exact steps the recorder saw. The prose is what you keep editing afterwards.

Option A: in-app recorder

This is the path most PMs and designers will use. The recorder lives inside the dev build of the app — the build engineering hands you for testing — and a single keyboard shortcut starts and stops it.

What gets captured

The recorder is conservative. It captures the things a flow needs to reproduce later, and nothing else:

• Taps — on every interactive element, with the element’s name or text or accessibility label so the flow doesn’t depend on screen coordinates.
• Typed text — what you typed and which field you typed it into.
• Screen transitions — when the screen changes, so the flow can assert the next screen is visible before continuing.
• Visual snapshots — only if you tap the camera icon in the overlay during recording. By default, snapshots are not captured.

What is not captured: scrolling that didn’t lead to a tap, idle seconds, network traffic, your typing speed, or any system-level gestures (like swiping up to close the app).

What to clean up afterwards

The draft prose the recorder generates is a starting point, not a final flow. Two minutes of cleanup is normal:

1. Rename the file. recorded-2026-04-29-1412.flow.md is a timestamp; rename it to something a teammate would recognise, like flows/sign-in-and-reorder.flow.md.
2. Rewrite the title. The recorder’s first guess at a scenario name is usually too literal. Replace it with the one-line summary you’d write in a Linear ticket.
3. Clean up the body prose. The recorder describes what it saw in plain language, but it’s a description of clicks. Rewrite it the way you’d describe the scenario to a coworker. Group related steps into one sentence. Drop steps that aren’t essential.
4. Add the assertion. A recording captures what you did; it doesn’t always capture what success looks like. Add a final sentence: “Assert that the welcome screen shows the user’s name.”

After you save your edits, the compiled .flow.json regenerates automatically. The exact mechanics are explained in writing prose flows.

Option B: engineer-led CLI recording

If you’re sitting at a desk with engineering and they have a terminal open, the same recording surface is available from the command line:

pnpm exec klera record sign-in-and-reorder

This connects to the running dev build and starts recording, the same way the in-app shortcut does. The PM walks through the scenario; the engineer presses Ctrl-C in the terminal to stop. The result is the same pair of files in flows/, named after whatever the engineer typed on the command line.

When this option makes sense:

• Pairing on a tricky scenario where the engineer wants to capture console output too (network calls, log lines).
• Reproducing a CI failure on a developer’s laptop and saving the reproduction as a flow so the next regression catches it.
• Bulk-recording several short scenarios in one session — the CLI remembers the previous filename so you can keep adding flows without re-typing every name.

The output format is identical. Whoever ends up owning the flow can edit the prose afterwards in their editor of choice.

After recording

Once the file is on disk and you’ve cleaned up the prose, treat it like any other flow: run it, commit it, let CI keep it green. The writing prose flows page covers the editing loop. The reading a report page covers what happens when the flow eventually fails.

If a recorded flow turns out to be flakier than you expected — for instance, the recorder caught a race condition between two animations — the self-healing reference explains how klera tries to recover before declaring a failure.