Skip to main content
A flow is a named sequence of steps that represents one backend process — such as a checkout, a webhook handler, or a background job. You define flows on the Failpath dashboard, sync them into your repository as a local graph, and instrument each step in your code with the @failpath/sdk. Every time that process runs in production, Failpath records what happened, step by step.

​
The flows.json file

When you run npx failpath init, the CLI creates a .failpath/ directory in your repository, writes a flows.json file that mirrors the current graph from your Failpath dashboard project, and generates .failpath/sdk.ts from that graph. The JSON file is the local source of truth for your flow definitions — it describes every flow and every step node, along with the keys your SDK code uses to identify them.
After init, your repository contains:
  • .failpath/flows.json — the flow graph pulled from the dashboard
  • .failpath/sdk.ts — generated typed bindings for flow slugs and step keys
  • .failpath/AGENTS.md — context for AI coding assistants
  • An updated .gitignore and a .env file containing your FAILPATH_PROJECT_KEY
You should commit .failpath/flows.json alongside your application code so that your flow definitions are version-controlled and visible to your team. If your application imports .failpath/sdk.ts, commit that generated file too or regenerate it before typechecking and building.

​
The flow.slug field

Each flow in flows.json has a slug property. This slug is the key you pass to failpath.run() in your SDK code to associate a runtime execution with its flow definition on the dashboard.
If your flow’s slug is "checkout", every call to failpath.run("checkout", ...) is recorded as a run of that flow. Prefer failpathFlows from .failpath/sdk.ts so TypeScript autocompletes the slug and catches typos. Raw string literals still work when they match exactly what is in flows.json.

​
Steps within a flow

Each flow is made up of step nodes. In flows.json, every node has an sdkStepKey field — this is the string you pass as the first argument to run.step() in your application code. Keeping these keys in sync between flows.json and your code is how Failpath connects live run data to the right node on the dashboard graph.
The dashboard graph is the canonical definition of which steps exist and what their keys are. Use the generated constants or the sdkStepKey values directly — do not rename them in code.

​
Publishing changes to the dashboard

If you edit a flow graph locally or need to push a new configuration, run:
publish validates your flows.json, regenerates .failpath/sdk.ts, and pushes the local graph to the Failpath dashboard. Use this when you have made changes in your repository that should be reflected on the dashboard.

​
Pulling dashboard changes

If you make edits on the Failpath dashboard — adding steps, renaming nodes, or restructuring a flow — pull those changes into your local flows.json with:
sync overwrites your local flows.json with the latest graph from the dashboard and regenerates .failpath/sdk.ts. Run it whenever you update a flow through the dashboard UI so that your local file, generated types, and SDK step keys stay in sync.
Do not hand-edit flows.json beyond what the dashboard produces. The file is generated by the Failpath CLI and dashboard tooling. Manual edits may produce an invalid graph that fails validation on the next publish or causes step events to be unmatched on the dashboard.