Routine Sub Routines

Sub-Routines and Meta-Commands

Routines compose. This page covers how to call one routine from another (sub-routines) and the built-in meta-commands (wait-until, session refresh) that give routines control-flow primitives beyond regular API calls.

• Sub-routines
• Passing variable overrides to a sub-routine
• wait-until
• session refresh

Sub-routines

Invoke another routine from within a routine with command: routine run:

- name: setup
  command: routine run
  args-positional:
    - create-test-data

The sub-routine runs with its own variable defaults. It counts as a single step in the parent routine — a failure inside the sub-routine fails the parent step (unless continueOnError: true is set on the routine run step).

Sub-routines are the right tool when:

• Multiple routines share setup or teardown logic
• A complex workflow decomposes into independently-testable pieces
• You want to keep individual routines focused (one responsibility each)

Passing variable overrides to a sub-routine

Use --set- prefixed args to override the sub-routine's variables::

- name: setup
  command: routine run
  args-positional:
    - create-test-data
  args:
    --set-owner_name: "Custom Owner"
    --set-pet_count: "5"

The --set- prefix maps to --set key=value overrides on the sub-routine.

# create-test-data.yaml (the sub-routine)
name: create-test-data
variables:
  owner_name: "Default Owner"
  pet_count: 3
steps: [...]

With the call above, the sub-routine runs with owner_name="Custom Owner" and pet_count="5".

Sub-routine output. Setting output: on a routine run step captures the sub-routine's execution summary — a record with success, stepsRun, stepsSkipped, stepsFailed — not the data returned by the sub-routine's individual steps. Use $provisioned.success to branch on whether the sub-routine completed cleanly; if you need to thread resource IDs between parent and sub-routine, pass them in explicitly via --set- and have the sub-routine act on them.

- name: provision
  command: routine run
  args-positional:
    - create-test-data
  output: provisioned

- name: verify
  command: owners list
  condition: "$provisioned.success"

---

wait-until

Polls a command repeatedly until it returns a truthy result. Use this for asynchronous operations — a resource transitioning to a ready state, an eventually-consistent list updating, a job finishing.

- name: wait-for-adoption
  command: wait-until
  args-positional:
    - "pets get"
  args:
    --id: "$pet.id"
    --interval: 5
    --timeout: 60

The first positional argument is the command path to poll. All other args are passed through to that command on every poll.

Arg	Default	Description
--interval	3	Seconds between polls
--timeout	120	Maximum seconds to wait before failing the step

wait-until succeeds as soon as the polled command returns a truthy (non-null, non-empty) result. If the timeout is hit, the step fails with a timeout error (honours continueOnError: like any other step).

session refresh

Re-runs the configured authentication strategy mid-routine, refreshing the cached session. Useful for long-running routines where the session may expire, or when switching credentials between phases:

- name: refresh-auth
  command: session refresh

No arguments. The step fails if re-authentication fails, allowing downstream steps to branch on $refresh-auth.success.

See Session Auth for how sessions are managed and cached.

---

See also

• Writing Routines — overview
• Routine Variables — variable defaults for sub-routines
• Routine Error Handling — making sub-routine failures non-fatal
• Routine YAML Schema — formal field reference