The .aether file

One .aether file describes one flow. It’s plain YAML with embedded JavaScript expressions — readable in any editor, diffable in any pull request. You never have to write it by hand (the graph and inspector edit it for you), but knowing the shape pays off quickly.

The shape of a file

version: "1.0" # required — format version
name: User CRUD Flow # required
description: Optional prose about what this flow covers.
variables: # optional — flow-level defaults
  baseUrl: https://api.example.com
start: login # optional — entry node id; defaults to the first node
nodes: # required — the steps
  - id: login
    type: request
    config:
      method: POST
      url: ${{ variables.baseUrl }}/auth/login
      capture:
        accessToken: response.body.token
    next: get_profile
  - id: get_profile
    type: request
    config:
      method: GET
      url: ${{ variables.baseUrl }}/me
      headers:
        Authorization: Bearer ${{ variables.accessToken }}
    next: null

The rules worth knowing

• Every node has id, type, and config. The id must be unique in the file — it’s what routing points at. An optional label gives the node a friendlier display name on the graph.
• Routing lives on the node — there is no edges list. A node names its successor in next (or then/else for conditions, body + next for loops, branches + next for parallel fan-outs). Omit it or set it to null to end that branch. The graph derives its edges from these fields, so the file can never disagree with the picture.
• Two kinds of dynamic values, deliberately distinct:
  • ${{ ... }} — string interpolation inside YAML string values like url, headers, and body: url: ${{ variables.baseUrl }}/users.
  • Bare JavaScript — the entire value of check, expression, and over is a JS expression with response, variables, and env in scope. Don’t wrap these in ${{ }}.
• Layout is part of the file. Dragging a node on the graph writes ui.position into its YAML, so the arrangement survives commits and travels to teammates. A node without a position is laid out automatically.

Why it matters that this is just a file

Commit flows next to the code they test. Review a flow change as a normal diff — a changed URL or assertion reads exactly like a changed line of code. Hand the suite to CI with the CLI or to an AI agent with the MCP server — both read the same files the editor does.

For every node type and its config fields, see the Node reference.