Routine Output

Routine Output Capture

Each step's response is automatically captured and made available to later steps. This page covers how to reference step outputs, drill into nested fields, and check whether a step succeeded.

• Capturing output with output:
• Referencing output by step name
• Nested field access
• The .success field
• Output and loops

Capturing output with output:

Give a step a stable alias with output:. Later steps reference the alias with $ syntax:

steps:
  - name: create-owner
    command: owners create
    args:
      --name: "Alice"
      --email: "alice@example.com"
    output: owner

  - name: create-pet
    command: pets create-pet
    args:
      --name: "Buddy"
      --species: "dog"
    output: new_pet

  - name: adopt
    command: pets adopt-pet
    args-positional:
      - "$new_pet.id"
    args:
      --ownerId: "$owner.id"

Think of output: as "rename this step's result so later steps can find it by a friendlier name."

Referencing output by step name

If you don't set output:, the step's result is still addressable — by its name::

steps:
  - name: create-owner
    command: owners create
    args:
      --name: "Alice"

  - name: use-the-owner
    command: pets adopt-pet
    args:
      --ownerId: "$create-owner.id"   # <-- by step name

When both a name and output: alias exist, either works. Use output: when step names are long, noisy, or likely to change.

Nested field access

Use dot notation to drill into objects and arrays:

# Object field
args:
  --id: "$response.data.id"

# Nested object
args:
  --city: "$owner.address.city"

# Array index
args:
  --first-tag: "$pet.tags.0"

# Array element, then field
args:
  --id: "$response.items.0.id"

If any step in the path is missing, the reference resolves to empty — no exception, but downstream commands may fail. Use condition: to guard on $ref truthy-checks if that's a risk.

The .success field

Every step's captured output exposes a boolean .success field. It is true when the command returns HTTP 2xx (or a truthy result for meta-commands), false otherwise.

This is the idiomatic way to branch on whether a previous step worked:

- name: try-fetch
  command: pets get
  args-positional:
    - "999"
  continueOnError: true

- name: fallback
  command: pets list
  condition: "$try-fetch.success == false"

.success pairs well with continueOnError: true — it lets the routine ignore a failure and take an alternate path.

Output and loops

Inside a forEach or range block, outputs of steps within the block are scoped to the current iteration. They are overwritten on each pass.

- name: for-each-pet
  forEach: "$all_pets"
  as: "pet"
  steps:
    - name: get-detail
      command: pets get
      args-positional:
        - "$pet.id"
      output: detail

    - name: verify
      command: pets get
      args-positional:
        - "$pet.id"
      assert: "$detail.ownerId == $pet.ownerId"   # same-iteration reference — works

Outputs set inside a loop persist after the loop finishes, but each iteration overwrites the previous one — so after the block, any loop-internal alias holds only the last iteration's values. Don't rely on it for per-iteration history; if you need to accumulate results across iterations, drive the work through the source array or use a wrapping step.

---

See also

• Writing Routines — overview
• Routine Conditions & Assertions — branching on output
• Routine Loops — loop-scoped outputs
• Routine YAML Schema — formal field reference