switch

NAME

switch - evaluate a value and branch to different states

SYNOPSIS

state-name:
  tool: switch
  arguments:
    value: <expression>
  goto:
    <match1>: <state1>
    <match2>: <state2>
    _: <default-state>

DESCRIPTION

The switch tool evaluates a value and routes execution to different states based on the result. It enables conditional branching without shell scripting.

The value argument is evaluated after variable substitution. The result is matched against goto keys (case-insensitive, whitespace-trimmed).

ARGUMENTS

Argument	Required	Default	Description
`value`	Yes	-	Expression to evaluate

GOTO MAP

Key	Description
`<value>`	Exact match (case-insensitive)
`_`	Wildcard/default (required)

EXIT CODES

Code	Meaning
`0`	Always (branching is handled via goto)

EXPRESSIONS

Simple Variable

value: "{{ status }}"

Returns the variable’s value.

Equality Comparison

value: "{{ env == 'production' }}"

Returns "true" or "false".

Inequality Comparison

value: "{{ mode != 'debug' }}"

Returns "true" or "false".

EXAMPLES

Branch on Variable Value

route-environment:
  tool: switch
  arguments:
    value: "{{ environment }}"
  goto:
    production: deploy-prod
    staging: deploy-staging
    development: deploy-dev
    _: unknown-env

Boolean Condition

check-ready:
  tool: switch
  arguments:
    value: "{{ status == 'ready' }}"
  goto:
    "true": proceed
    "false": wait
    _: error

Multi-value Routing

handle-response:
  tool: bash
  arguments:
    command: curl -s -o /dev/null -w "%{http_code}" https://api.example.com
  output: var(http_status)
  next: route-status

route-status:
  tool: switch
  arguments:
    value: "{{ http_status }}"
  goto:
    "200": handle-success
    "404": handle-not-found
    "500": handle-server-error
    _: handle-other

Workflow State Machine

start-at: check-state

variables:
  state: "initial"

states:
  check-state:
    tool: switch
    arguments:
      value: "{{ state }}"
    goto:
      initial: initialize
      running: process
      complete: finish
      _: error

  initialize:
    tool: bash
    arguments:
      command: echo "running"
    output: var(state)
    next: check-state

  process:
    tool: bash
    arguments:
      command: ./process.sh && echo "complete"
    output: var(state)
    next: check-state

  finish:
    tool: bash
    arguments:
      command: echo "Done!"

  error:
    tool: bash
    arguments:
      command: 'echo "Unknown state: {{ state }}" >&2 && exit 1'

Feature Flags

check-feature:
  tool: bash
  arguments:
    command: '[ -f ./flags/new-ui.enabled ] && echo "enabled" || echo "disabled"'
  output: var(new_ui)
  next: route-ui

route-ui:
  tool: switch
  arguments:
    value: "{{ new_ui }}"
  goto:
    enabled: build-new-ui
    disabled: build-classic-ui
    _: build-classic-ui

Approval Workflow

get-approval:
  tool: ask-user
  arguments:
    question: "Approve deployment?"
    options:
      - "yes"
      - "no"
      - "defer"
  output: var(approval)
  next: route-approval

route-approval:
  tool: switch
  arguments:
    value: "{{ approval }}"
  goto:
    "yes": deploy
    "no": cancel
    defer: pause-for-later
    _: cancel

MATCHING RULES

Value is trimmed of whitespace
Comparison is case-insensitive
Keys are matched in order of definition
_ matches if no other key matches
_ is required (validation error if missing)

ERROR HANDLING

The switch tool itself always succeeds (exit 0). Routing errors are prevented by requiring the _ fallback.

If a matched state doesn’t exist, the workflow fails when attempting to transition.

COMMON PATTERNS

Boolean Gate

is-production:
  tool: switch
  arguments:
    value: "{{ env == 'production' }}"
  goto:
    "true": production-path
    _: non-production-path

Exit Code Routing

# Previous state captures exit code
check-result:
  tool: switch
  arguments:
    value: "{{ exit_code }}"
  goto:
    "0": success
    "1": failure
    _: unknown

User Choice

# After ask-user
route-choice:
  tool: switch
  arguments:
    value: "{{ user_choice }}"
  goto:
    option1: handle-option1
    option2: handle-option2
    _: handle-default