Routine Variables

Routine Variables

Routines use three kinds of dynamic values: user-defined variables (variables: block + --set overrides), built-in variables ($_timestamp, $_date), and resolver functions ($_uuid, $_random_int(...), $_env(...), etc.).

All three use the same $ syntax when referenced in args, conditions, assertions, and other variable defaults.

• User-defined variables
• Runtime overrides with --set
• Built-in variables
• Resolver functions
• Custom resolvers

User-defined variables

Declare defaults in the variables: block and reference them with $ syntax:

name: find-pets-by-species
variables:
  species: "dog"
  limit: 10
steps:
  - name: find-pets
    command: pets list
    args:
      --species: "$species"
      --limit: "$limit"

Variable defaults can reference other variables and built-ins:

variables:
  run_id: "run-$_timestamp"
  owner_email: "test-$_uuid@example.com"
  owner_name: "QA $_date"

YAML lists are supported — useful for driving forEach from a variable:

variables:
  ids: [1, 2, 3]
steps:
  - name: loop
    forEach: "$ids"
    steps: [...]

Runtime overrides with --set

Override any declared variable at invocation time:

petstore routine run find-pets-by-species \
  --set species=cat \
  --set limit=50

Resolution order (lowest → highest precedence):

1. Built-in variables / resolver functions
2. variables: block defaults
3. --set key=value CLI overrides

Keys passed via --set are merged into the variable scope as-is — they are not validated against the variables: block, so a typo becomes a silently-unused key rather than an error. Double-check spelling.

Built-in variables

These are pre-declared in every routine and resolved once when the routine starts, so every reference in a single run produces the same value:

Variable	Description	Example
$_timestamp	Unix epoch seconds	1774569600
$_date	ISO date (YYYY-MM-DD)	2026-04-23

variables:
  tag: "smoke-$_date"
  batch_id: "$_timestamp"

Resolver functions

Resolver functions run every time they are referenced — unlike built-in variables which are resolved once. They are ideal for per-step random values, env var lookups, and array searches.

Random-value resolvers

Function	Returns	Example
$_uuid	UUID v4	"6f19...a7"
$_random_hex_color	Random #rrggbb	"#a3f2c1"
$_random_int(min,max)	Integer in [min,max]	$_random_int(1,15)
$_random_from(a,b,c,...)	Random item from list	$_random_from(dog,cat,bird)
$_random_distinct_from(a,b,c,...)	Draws without repeat; pool resets per loop block and refills when exhausted	$_random_distinct_from(red,green,blue)

args:
  --email: "$_uuid@example.com"
  --color: "$_random_hex_color"
  --age: "$_random_int(1,10)"
  --species: "$_random_from(dog,cat,bird)"

See Routine Loops for the $_random_distinct_from pool-reset behaviour inside loops.

$_env(VAR) / $_env(VAR, default)

Reads an environment variable. Takes one or two arguments. If the var isn't set and no default is given, it returns an empty string and prints a warning to stderr.

variables:
  api_token: "$_env(PETSTORE_API_TOKEN)"
  region: "$_env(AWS_REGION, us-east-1)"
steps:
  - name: authenticate
    command: auth token
    args:
      --token: "$api_token"

In project mode, a .env file at the project root (next to .apijack.json) is auto-loaded at startup — local development works out of the box without exporting vars into your shell. Variables already set in the process environment take precedence over .env entries. In pure global mode, export the var yourself or pass it inline (PETSTORE_API_TOKEN=... petstore routine run ...).

$_find($array, field, value)

Finds the first element in an array whose field equals value. Returns undefined if nothing matches (the routine continues; downstream references will resolve as empty).

steps:
  - name: list-owners
    command: owners list
    output: owners

  - name: adopt-for-alice
    command: pets adopt-pet
    args-positional:
      - "$pet.id"
    args:
      --ownerId: "$_find($owners, name, Alice).id"

The third argument can itself reference a variable:

variables:
  target_name: "Alice"
args:
  --ownerId: "$_find($owners, name, $target_name).id"

$_contains($array, field, value)

Returns the literal string "true" or "false" — designed for use inside condition: expressions.

- name: skip-if-exists
  command: owners create
  args:
    --name: "Alice"
  condition: "$_contains($owners, name, Alice) == false"

Custom resolvers

Projects can register their own $_*(...) functions via .apijack/resolvers/<name>.ts. See Project Mode for the extension point.

---

See also

• Writing Routines — overview
• Routine Output Capture — step output references
• Routine YAML Schema — formal field reference