Bash Nodes

Bash nodes run shell commands — perfect for command-line bioinformatics tools like FastQC, BWA, GATK, and samtools.

The Simplest Bash Node

Here’s a complete, working bash node:

#!/bin/bash
FASTQ_FILE=""
OUTPUT_DIR=""
THREADS=4
 
mkdir -p "$OUTPUT_DIR"
fastqc "$FASTQ_FILE" -o "$OUTPUT_DIR" -t "$THREADS"
 
echo "__BASH_OUTPUT__ output_dir=$OUTPUT_DIR"

That’s it. This node has 3 inputs and 1 output. Read on to understand why.

Start With a Shebang

Every bash node begins with a shebang line:

#!/bin/bash

This tells the system to run your code with bash.

What Is an Input?

Inputs are UPPERCASE variable assignments at the top of your script.

#!/bin/bash
FASTQ_FILE=""
OUTPUT_DIR=""
THREADS=4

This node has three inputs: FASTQ_FILE, OUTPUT_DIR, and THREADS. When the workflow runs, values from upstream nodes replace these defaults automatically.

Use Empty Strings for File Inputs

For file paths and string inputs, use empty quotes as the default:

FASTQ_FILE=""       # gets replaced by upstream connection
OUTPUT_DIR=""       # gets replaced by upstream connection

For numeric inputs, provide a sensible default:

THREADS=4           # used if nothing is connected

Why UPPERCASE?

The system only detects uppercase variables (like FASTQ_FILE, THREADS) as inputs. Lowercase variables (like output_dir) are treated as internal script variables, not inputs.

Single-letter uppercase variables (like R=, I=) are also skipped — use at least two characters.

Using Inputs in Your Script

Reference them with $ like normal bash variables:

fastqc "$FASTQ_FILE" -o "$OUTPUT_DIR" -t "$THREADS"

Always quote your variables ("$FASTQ_FILE") to handle paths with spaces.

What Is an Output?

Outputs come from __BASH_OUTPUT__ lines.

Since bash doesn’t have return statements, we use a special marker:

echo "__BASH_OUTPUT__ output_dir=$OUTPUT_DIR"

This creates an output named output_dir. Downstream nodes can connect to it.

Multiple Outputs

Add multiple __BASH_OUTPUT__ lines:

echo "__BASH_OUTPUT__ bam_file=$OUTPUT_BAM"
echo "__BASH_OUTPUT__ metrics=$METRICS_FILE"

Now downstream nodes can connect to either bam_file or metrics.

No Output?

If you don’t add any __BASH_OUTPUT__ lines, the system automatically adds a default output called done. This is useful for nodes that are the last step in a pipeline.

Error Handling

Check if your command succeeded and report status:

#!/bin/bash
FASTQ_FILE=""
OUTPUT_DIR=""
 
fastqc "$FASTQ_FILE" -o "$OUTPUT_DIR"
 
if [ $? -eq 0 ]; then
    echo "FastQC completed successfully"
    echo "__BASH_OUTPUT__ output_dir=$OUTPUT_DIR"
else
    echo "FastQC failed with exit code $?"
    exit 1
fi

This pattern prevents silent failures — if a tool crashes, the node stops and reports the error instead of passing bad data downstream.

How Variables Arrive

When you connect an upstream node to your bash node, the system injects the values as bash variable assignments that override your defaults:

#!/bin/bash
# Your defaults:
FASTQ_FILE=""
THREADS=4
 
# Injected from upstream (overrides defaults):
# FASTQ_FILE="/tmp/workflow/data/processed.fastq"
# THREADS=16

The injected values override your defaults. So your defaults act as placeholders that get replaced at runtime.

A Complete Example

Here’s a real BWA-MEM alignment node:

#!/bin/bash
REF_GENOME=""
FASTQ_R1=""
FASTQ_R2=""
OUTPUT_SAM=""
THREADS=8
 
mkdir -p "$(dirname "$OUTPUT_SAM")"
 
bwa mem -t "$THREADS" "$REF_GENOME" "$FASTQ_R1" "$FASTQ_R2" > "$OUTPUT_SAM"
 
if [ $? -eq 0 ]; then
    echo "Alignment completed successfully"
    echo "__BASH_OUTPUT__ sam_file=$OUTPUT_SAM"
else
    echo "Alignment failed"
    exit 1
fi

Good to Know

Verbose output? Redirect to a log file

Many bioinformatics tools (BWA, STAR, FastQC) print a lot of progress output. Redirect verbose output to a file and only echo key results:

bwa mem ref.fa "$FASTQ_R1" "$FASTQ_R2" > out.sam 2> bwa.log
echo "Alignment complete. See bwa.log for details."

stderr is treated as error output

Bash treats stderr as errors, even if the command succeeds. Some tools write progress info to stderr. If that’s intentional, redirect it:

fastqc "$FASTQ_FILE" 2>/dev/null    # discard stderr
fastqc "$FASTQ_FILE" 2>&1           # merge stderr into stdout

Non-interactive only

Bash nodes can’t prompt for user input. If a command requires confirmation (e.g., y/n), it will hang forever. Always pass flags like -y or --yes:

apt-get install -y samtools

No timeout

There’s no execution timeout. Long-running alignments or downloads are fine. But make sure your script doesn’t hang waiting for user input.

Output is text-only

Bash nodes return text output (stdout), not structured objects. You can’t pass a DataFrame or AnnData from a bash node — use Python or R for that.

Quick Summary