bash

NAME

bash - execute shell commands via /bin/bash

SYNOPSIS

state-name:
  tool: bash
  arguments:
    command: <shell-command>

DESCRIPTION

The bash tool executes shell commands using /bin/bash -c. Commands run in the workflow instance directory, providing isolation between workflow runs.

Commands have full access to the shell environment, including pipes, redirects, and subshells. Variable substitution happens before the command is passed to bash.

ARGUMENTS

Argument	Required	Default	Description
`command`	Yes	-	Shell command to execute

EXIT CODES

Code	Meaning
`0`	Command succeeded
`1-255`	Command exit code (passed through)

OUTPUT

When output is specified, stdout is captured instead of displayed.

get-date:
  tool: bash
  arguments:
    command: date +%Y-%m-%d
  output: var(today)

Stderr is always passed through to the terminal.

EXAMPLES

Simple Command

greet:
  tool: bash
  arguments:
    command: echo "Hello, World!"

Multi-line Script

setup:
  tool: bash
  arguments:
    command: |
      mkdir -p ./output
      touch ./output/.gitkeep
      echo "Setup complete"

Using Variables

process:
  tool: bash
  arguments:
    command: 'echo "Processing {{ filename }}"'

Capturing Output

get-version:
  tool: bash
  arguments:
    command: cat VERSION
  output: var(version)
  next: show-version

show-version:
  tool: bash
  arguments:
    command: 'echo "Version: {{ version }}"'

Writing to File

generate-report:
  tool: bash
  arguments:
    command: ./generate-report.sh
  output: file(./reports/latest.txt)

Error Handling

risky-command:
  tool: bash
  arguments:
    command: ./might-fail.sh
  on-error:
    1: handle-failure
    _: handle-unknown
  next: success-path

Conditional Execution

check-file:
  tool: bash
  arguments:
    command: '[ -f ./config.json ] && echo "exists" || echo "missing"'
  output: var(file_status)

WORKING DIRECTORY

Commands execute in the instance directory (./) by default. Use absolute paths or {{ path() }} for files outside the instance:

read-project-file:
  tool: bash
  arguments:
    command: 'cat "{{ path(@/config.json) }}"'

ESCAPING

Variable substitution happens before shell escaping. To use literal {{:

# This produces: echo "{{ not_a_variable }}"
show-template:
  tool: bash
  arguments:
    command: 'echo "{{ "{{" }} not_a_variable {{ "}}" }}"'

For complex escaping, consider using a file:

run-script:
  tool: bash
  arguments:
    command: bash "{{ path(./script.sh) }}"