Skip to content

oxo-flow batch#

Execute a command template in parallel across multiple items.

Usage#

oxo-flow batch [OPTIONS] <TEMPLATE> [ITEMS...]

Arguments#

Argument Description
<TEMPLATE> Command template with placeholders ({item}, {stem}, etc.)
[ITEMS...] Items to process (files, globs, or from stdin/file)

Options#

Option Short Default Description
--jobs -j 1 Number of parallel workers
--stop-on-error -x — Stop after first failure
--file -f — Read items from file
--json-output — — Output results as formatted JSON (legacy alias — the global --json now drives the same output)
--dry-run -n — Preview without executing
--workdir -d . Working directory
--environment -e — Environment spec
--generate-workflow — — Generate .oxoflow file
--output -o batch.oxoflow Output workflow file

Placeholders#

Placeholder Example Description
{} / {item} s1.bam Current item
{nr} 1, 2, 3... 1-based index
{basename} s1.bam Filename (no path)
{dir} data/ Directory
{stem} s1 Filename without extension
{ext} bam Extension

Examples#

Basic batch execution#

oxo-flow batch "samtools flagstat {item}" *.bam

Parallel with 8 workers#

oxo-flow batch -j 8 "fastqc {item}" *.fastq.gz

Stop on first error#

oxo-flow batch -x "bwa mem ref.fa {item}" samples.txt

From stdin (pipeline)#

ls *.bam | oxo-flow batch "samtools flagstat {item}"

With environment#

oxo-flow batch -e "conda: bwa_env" "bwa mem ref.fa {item}" *.fastq.gz

Generate workflow#

oxo-flow batch --generate-workflow "bwa mem ref.fa {item}" *.bam -o align.oxoflow

JSON output#

oxo-flow batch --json-output "samtools flagstat {item}" *.bam > results.json

Dry-run preview#

oxo-flow batch -n "fastqc {item}" *.fastq.gz

Notes#

  • Items can be files, globs (*.bam), or plain strings
  • Input file format: one item per line, blank lines and # comments ignored
  • When no items provided and stdin has data, reads from pipe
  • {} is rush-compatible shorthand for {item}

  • Environment spec format: conda: env.yaml or docker: image:tag

  • Generated workflows create one rule per item (batch_item_1, batch_item_2, ...)

Exit Codes#

  • 0 — all items succeeded.
  • 1 — any item failed (#540). The per-item failures are still listed in the output and in --json-output's results array. --stop-on-error (-x) additionally aborts the batch on the FIRST failed item instead of running the rest.