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 and writes a flows.json file that mirrors the current graph from your Failpath dashboard project. This 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. 
npx failpath init --project-key fp_project_xxx
After init, your repository contains:
  • .failpath/flows.json — the flow graph pulled from the dashboard
  • .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.

​
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. 
const run = failpath.run("checkout", { runId: requestId });
If your flow’s slug is "checkout", every call to failpath.run("checkout", ...) is recorded as a run of that flow. Make sure the slug you use in code matches 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. 
await run.step("validate-cart", async () => {
  return validateCart();
});
The dashboard graph is the canonical definition of which steps exist and what their keys are. Use 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: 
npx failpath publish
publish validates your flows.json 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: 
npx failpath sync
sync overwrites your local flows.json with the latest graph from the dashboard. Run it whenever you update a flow through the dashboard UI so that your local file and your 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.