### Setup miniwdl development environment

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/add_functions.md

Commands to clone the repository and install necessary development dependencies.

```bash
git clone --recursive https://github.com/chanzuckerberg/miniwdl.git  # or your own fork
cd miniwdl
pip3 install '.[dev]'  # to install dev dependencies
```

--------------------------------

### Install miniwdl via PyPI

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/getting_started.md

Use pip to install miniwdl. Ensure Python 3.8 or higher is installed.

```bash
pip3 install miniwdl
```

--------------------------------

### Verify miniwdl installation

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/FAQ.md

Displays the list of available commands to confirm successful installation.

```bash
miniwdl --help
```

--------------------------------

### Install miniWDL

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Install miniWDL using pip or conda. Verify the installation using the self-test command.

```bash
pip3 install miniwdl
```

```bash
conda install -c conda-forge miniwdl
```

```bash
miniwdl run_self_test
```

--------------------------------

### Install miniwdl development dependencies

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/CONTRIBUTING.md

Install OS packages and PyPI dependencies for miniwdl development. This includes installing the package with development extras.

```bash
pip3 install '.[dev]'
```

--------------------------------

### Run self-test workflow

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/FAQ.md

Executes an example workflow to verify that miniwdl is functioning correctly.

```bash
miniwdl run_self_test
```

--------------------------------

### Run Alternate Backend Tests

Source: https://github.com/chanzuckerberg/miniwdl/wiki/Release-Procedure

Execute integration tests for Podman, Singularity, and UDocker backends. Ensure these backends are installed and configured before running.

```bash
prove -v tests/{podman,singularity,udocker}.t
```

--------------------------------

### Execute identifier tracing

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/trace_identifiers.md

Example command to run the script against a WDL document provided via stdin.

```bash
$ python3 trace_identifiers.py << 'EOF'
    version 1.0
    workflow sum_sq {
        input {
            Int x
        }
        scatter (i in range(x)) {
            Int sq = (i+1)*(i+1)
        }
        call sum {
            input: x = sq
        }
    }
    task sum {
        input {
            Array[Int] x
        }
        command <<<
            awk 'BEGIN {z=0;} {z+=$0;} END {print z;}' "~{write_lines(x)}"
        >>>
        output {
            Int z = read_int(stdout())
        }
    }
EOF
```

--------------------------------

### Configure Singularity Backend for miniWDL

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Set the MINIWDL__SCHEDULER__CONTAINER_BACKEND environment variable to 'singularity' to use Singularity for container execution. Verify Singularity installation and permissions.

```bash
# Configure Singularity backend
export MINIWDL__SCHEDULER__CONTAINER_BACKEND=singularity
singularity run --fakeroot docker://ubuntu:20.04 cat /etc/issue
miniwdl run_self_test
```

--------------------------------

### Run `miniwdl check` on a WDL File

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/check.md

Execute `miniwdl check` on a WDL file to perform static analysis and report warnings. This example shows the output for `check_demo.wdl`, highlighting issues like missing version, type coercion, unused declarations, forward references, and name collisions.

```none
$ miniwdl check check_demo.wdl
check_demo.wdl
     (Ln 1, Col 1) MissingVersion, document should declare WDL version; draft-2 assumed
     task t
         (Ln 2, Col 10) StringCoercion, String s = :Int?:
         (Ln 2, Col 10) UnusedDeclaration, nothing references String s
         (Ln 2, Col 21) ForwardReference, reference to i precedes its declaration
         (Ln 10, Col 14) NameCollision, declaration of 't' collides with a task name
```

--------------------------------

### Configure Singularity Runtime for miniwdl

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_backends.md

Set the environment variable to use Singularity as the container backend for miniwdl. This requires Singularity to be installed on the system.

```bash
singularity run --fakeroot docker://ubuntu:20.04 cat /etc/issue
```

```bash
MINIWDL__SCHEDULER__CONTAINER_BACKEND=singularity
```

--------------------------------

### Scale Runtime Resources to Input Size in WDL

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_advanced.md

Dynamically adjust CPU and memory reservations based on input size to prevent unnecessary serialization of tasks. This example scales CPU and memory based on the number of input files.

```wdl
task res {
  input {
    Array[File]+ input_files

    Int cpu = if length(input_files) < 16 then length(input_files) else 16
    Int memGB = cpu*2
  }

  command {
    cat "~{write_lines(input_files)}" | xargs -i -P ~{cpu} echo {}
  }

  runtime {
    cpu: cpu
    memory: "~{memGB}GB"
  }
}
```

--------------------------------

### Install miniwdl via Conda

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/getting_started.md

Install miniwdl using conda after setting up conda-forge. Ensure conda-forge is configured in your channels.

```bash
conda install miniwdl
```

--------------------------------

### Configure udocker Backend for miniWDL

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Set the MINIWDL__SCHEDULER__CONTAINER_BACKEND environment variable to 'udocker' to use udocker for container execution. Ensure udocker is installed and configured.

```bash
# Configure udocker backend
export MINIWDL__SCHEDULER__CONTAINER_BACKEND=udocker
udocker run ubuntu:20.04 cat /etc/issue
miniwdl run_self_test
```

--------------------------------

### Stop, Move, and Link Docker Directory

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_advanced.md

Use this procedure to move the Docker storage location to a local scratch disk. Ensure Docker is stopped before moving the directory and started afterward.

```default
systemctl stop docker    # or appropriate command to stop dockerd
mv /var/lib/docker /mnt
ln -s /mnt/docker /var/lib/docker
systemctl start docker
```

--------------------------------

### Traverse WDL AST with WDL.Walker for Analysis

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Implement custom walkers using `WDL.Walker` to traverse WDL Abstract Syntax Trees (ASTs) for static analysis, linting, or code transformation. This example demonstrates finding all Array identifier expressions.

```python
import WDL

# Load document
doc = WDL.load("workflow.wdl")

# Custom walker to find all Array identifier expressions
def trace_identifiers(obj):
    if isinstance(obj, WDL.Document):
        if obj.workflow:
            trace_identifiers(obj.workflow)
        for task in obj.tasks:
            trace_identifiers(task)
    elif isinstance(obj, WDL.Workflow):
        for ch in (obj.inputs or []) + obj.body + (obj.outputs or []):
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Task):
        for ch in (obj.inputs or []) + obj.postinputs + [obj.command] + obj.outputs:
            trace_identifiers(ch)
    elif isinstance(obj, WDL.WorkflowSection):
        trace_identifiers(obj.expr)
        for ch in obj.body:
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Call):
        for rhs in obj.inputs.values():
            trace_identifiers(rhs)
    elif isinstance(obj, WDL.Decl):
        trace_identifiers(obj.expr)
    elif isinstance(obj, WDL.Expr.Base):
        for ch in obj.children:
            trace_identifiers(ch)

    # Report Array identifiers
    if isinstance(obj, WDL.Expr.Ident) and isinstance(obj.type, WDL.Type.Array):
        print(f"L{obj.pos.line} Array[{obj.type.item_type}] {obj.name}")

trace_identifiers(doc)
```

--------------------------------

### Ubuntu Docker Smoke Test

Source: https://github.com/chanzuckerberg/miniwdl/wiki/Release-Procedure

Run Miniwdl self-tests within an Ubuntu 20.04 Docker container. This verifies Miniwdl installation and basic functionality in a common Linux environment.

```bash
docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp ubuntu:20.04 \
  bash -c 'apt-get -qq update && apt-get install -y python3-pip && pip3 install miniwdl && miniwdl run_self_test'
```

--------------------------------

### Run MiniWDL Inside Docker Container

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_advanced.md

Example command to run miniwdl within a Docker container, mounting the host's Docker socket and input/output directories. Requires conda to install miniwdl inside the container.

```bash
mkdir /tmp/wdl
echo Alice > /tmp/wdl/alice
echo 'version 1.0
      task hello {
        input {
          File who
        }
        command {
          echo "Hello, ~{read_string(who)}!" | tee message.txt
        }
        output {
          File message = "message.txt"
        }
      }' > /tmp/wdl/hello.wdl
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/wdl:/tmp/wdl continuumio/miniconda3 \
  bash -c 'conda install -y -c conda-forge miniwdl &&
    miniwdl run /tmp/wdl/hello.wdl who=/tmp/wdl/alice --dir /tmp/wdl'
```

--------------------------------

### Run WDL Visualization Script

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/wdlviz.md

Commands to download a sample WDL file and execute the visualization script.

```bash
$ wget https://raw.githubusercontent.com/gatk-workflows/gatk4-germline-snps-indels/1.1.2/joint-discovery-gatk4-local.wdl
$ python3 wdlviz.py joint-discovery-gatk4-local.wdl
```

--------------------------------

### ShellCheck Integration with `miniwdl check`

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/check.md

When ShellCheck is installed, `miniwdl check` automatically runs it on task command scripts. This example shows a ShellCheck warning related to using `! -n` instead of `-z` for checking empty strings.

```none
(Ln 5, Col 17) CommandShellCheck, SC2236 Use -z instead of ! -n.
```

--------------------------------

### Initialize WDL document loading

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/trace_identifiers.md

The entry point for the script, which loads a WDL document from a file or standard input.

```python
#!/usr/bin/env python3
import os
import sys
import WDL


def main(args):
    doc = WDL.load(args[0] if args else "/dev/stdin")
    trace_identifiers(doc)
```

--------------------------------

### Generate miniwdl documentation locally

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/CONTRIBUTING.md

Generate the project's documentation locally. The output will be available in the `docs/_build/html/` directory.

```bash
make doc
```

--------------------------------

### Run assemble_refbased Workflow with Inputs

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/getting_started.md

Execute the assemble_refbased WDL workflow by providing input file paths and sample name as command-line arguments. Use --verbose for detailed logs.

```bash
$ miniwdl run pipes/WDL/workflows/assemble_refbased.wdl   \
    reads_unmapped_bams=test/input/G5012.3.testreads.bam  \
    reference_fasta=test/input/ebov-makona.fasta          \
    sample_name=G5012.3 --verbose
```

--------------------------------

### Load WDL Document for Visualization

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/wdlviz.md

Initializes the WDL document from a file or standard input and triggers the visualization process.

```python3
#!/usr/bin/env python3
import os
import sys
import WDL
import graphviz


def main(args):
    # load WDL document given local filename
    doc = WDL.load(args[0] if args else "/dev/stdin")
    assert doc.workflow, "No workflow in WDL document"

    # visualize workflow
    wdlviz(doc.workflow).render("workflow.dot", view=True)
```

--------------------------------

### Define a file-system-interacting WDL function

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/add_functions.md

Example of adding a word_count function that processes a file input.

```python3
        ...
        @static([Type.File()], Type.Int())
        def word_count(v: Value.File) -> Value.Int:
            with open(self._devirtualize_filename(v.value), "r") as infile:
                return Value.Int(len(infile.read().split(" ")))
        ...
```

--------------------------------

### Define a static WDL function

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/add_functions.md

Example of adding a factorial function to WDL.StdLib.Base using the static decorator.

```python3
class Base:
    def __init__(self):
        ...
        @static([Type.Int()], Type.Int())
        def factorial(v: Value.Int) -> Value.Int:
            def f(n: int) -> int:
                return 1 if n <= 1 else n * f(n - 1)

            return Value.Int(f(v.value))
        ...
```

--------------------------------

### Load, Parse, Configure, and Execute WDL Workflow

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

This Python script demonstrates loading a WDL workflow, parsing inputs, configuring the runtime, executing the workflow, and processing outputs. Ensure necessary libraries like WDL and runtime are imported.

```python
import logging
import WDL
import runtime

# Load and prepare workflow
doc = WDL.load("workflow.wdl")
workflow = doc.workflow

# Parse inputs
input_json = {
    "sample_name": "test_sample",
    "input_file": "/path/to/input.bam"
}
input_env = WDL.values_from_json(input_json, workflow.available_inputs)

# Configure runtime
logger = logging.getLogger("miniwdl")
cfg = runtime.config.Loader(logger)

# Execute workflow
run_dir, output_env = runtime.run(
    cfg,
    workflow,
    input_env,
    run_dir="/tmp/workflow_runs"
)

# Process outputs
outputs = WDL.values_to_json(output_env, namespace=workflow.name)
print(f"Run completed in: {run_dir}")
print(f"Outputs: {outputs}")
```

--------------------------------

### Create and run a WDL ZIP archive

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/zip.md

Package a WDL file into a ZIP archive and execute it using miniwdl run.

```bash
$ miniwdl zip path/to/my.wdl
$ miniwdl run my.wdl.zip input1=value1 ...
```

--------------------------------

### Define a WDL workflow with an assertion

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/assert.md

Example of using the proposed assert statement within a WDL workflow to validate input values.

```wdl
version development
workflow div {
    input {
        Int numerator
        Int denominator
    }
    assert denominator != 0
    output {
        Int quotient = numerator / denominator
    }
}
```

--------------------------------

### Preview assemble_refbased Workflow Inputs/Outputs

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/getting_started.md

Use miniwdl to preview the required and optional inputs, as well as the outputs, for the assemble_refbased WDL workflow without running it.

```bash
$ miniwdl run pipes/WDL/workflows/assemble_refbased.wdl

missing required inputs for assemble_refbased: reads_unmapped_bams, reference_fasta

required inputs:
  Array[File]+ reads_unmapped_bams
  File reference_fasta

optional inputs:
  String sample_name
  ...

outputs:
  File assembly_fasta
  Int assembly_length
  Int assembly_length_unambiguous
  Int reference_genome_length
  Float assembly_mean_coverage
  ...
```

--------------------------------

### Pre-download URI Inputs with miniwdl localize

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Download File/Directory inputs from URIs to a local cache before workflow execution.

```bash
# Localize inputs from JSON file
miniwdl localize workflow.wdl inputs.json
```

--------------------------------

### Build and push miniwdl-tools image

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/tools_image/README.md

Commands to build the Docker image with squash enabled and tag it using its content-digest for registry deployment.

```bash
docker pull ubuntu:20.04
docker build --no-cache --squash -t miniwdl-tools:latest tools_image/
TAG=$(docker inspect miniwdl-tools:latest | jq -r .[0].Id | tr ':' '_' \
      | xargs printf 'ghcr.io/miniwdl-ext/miniwdl-tools:Id_%s')
docker tag miniwdl-tools:latest $TAG
docker push $TAG
echo $TAG
```

--------------------------------

### Override Default Docker Image via Environment Variable

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_reference.md

This example demonstrates how to override the default Docker image using an environment variable. This method is useful for temporary changes or when a configuration file is not desired.

```bash
MINIWDL__TASK_RUNTIME__DEFAULTS='{"docker":"ubuntu:20.10"}'
```

--------------------------------

### Trace Identifiers in MiniWDL Workflows

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/trace_identifiers.md

This script analyzes a MiniWDL document to trace array variable identifiers and their definitions, printing the line number, type, name, and definition line number. It requires the WDL library to be installed.

```python3
#!/usr/bin/env python3
import os
import sys
import WDL


def main(args):
    doc = WDL.load(args[0] if args else "/dev/stdin")
    trace_identifiers(doc)


def trace_identifiers(obj):
    if isinstance(obj, WDL.Document):
        if obj.workflow:
            trace_identifiers(obj.workflow)
        for task in obj.tasks:
            trace_identifiers(task)
    elif isinstance(obj, WDL.Workflow):
        for ch in (obj.inputs or []) + obj.body + (obj.outputs or []):
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Task):
        for ch in (
            (obj.inputs or [])
            + obj.postinputs
            + [obj.command]
            + obj.outputs
            + list(obj.runtime.values())
        ):
            trace_identifiers(ch)
    elif isinstance(obj, WDL.WorkflowSection):
        trace_identifiers(obj.expr)
        for ch in obj.body:
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Call):
        for rhs in obj.inputs.values():
            trace_identifiers(rhs)
    elif isinstance(obj, WDL.Decl):
        trace_identifiers(obj.expr)
    elif isinstance(obj, WDL.Expr.Base):
        for ch in obj.children:
            trace_identifiers(ch)

    if isinstance(obj, WDL.Expr.Ident) and isinstance(obj.type, WDL.Type.Array):
        print(
            f"L{obj.pos.line} Array[{obj.type.item_type}] {obj.name}"
            + " defined on "
            + f"L{obj.referee.pos.line}"
        )


if __name__ == "__main__":
    main(sys.argv[1:])

```

--------------------------------

### Create a WDL Task for `miniwdl check` Demo

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/check.md

This bash script creates a sample WDL task file named `check_demo.wdl`. It demonstrates a valid but poorly-written WDL task that `miniwdl check` can analyze.

```bash
$ cat << 'EOF' > check_demo.wdl
  task t {
      String s = i
      Int? i
      command <<<
         if [ ! -n ~{s} ]; then
             echo Empty
         fi
      >>>
      output {
          String t = read_string(stdout())
      }
  }
EOF
```

--------------------------------

### miniwdl run usage syntax

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_cli.md

Displays the command-line interface usage pattern and available flags for the miniwdl run command.

```default
usage: miniwdl run [-h] [-i INPUT.json] [--empty input_key] [--none input_key]
                   [--task TASK_NAME] [-j] [-d DIR] [--error-json]
                   [-o OUT.json] [-v] [--no-color] [--log-json] [--cfg FILE]
                   [--runtime-defaults JSON] [--no-cache]
                   [--env VARNAME[=VALUE]] [--copy-input-files]
                   [--copy-input-files-for TASK_NAME] [--as-me] [-p DIR]
                   [--no-outside-imports] [--no-quant-check] [--debug]
                   URI [input_key=value [input_key=value ...]]
```

--------------------------------

### Override Default Docker Image via Custom Config File

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_reference.md

This example shows how to override the default Docker image used by miniwdl when no runtime.docker is specified in a task. It uses a custom configuration file placed in ~/.config/miniwdl.cfg.

```bash
$ cat << 'EOF' > ~/.config/miniwdl.cfg
[task_runtime]
defaults = {
        "docker": "ubuntu:20.10"
    }
EOF
```

--------------------------------

### Run WDL Visualization Script

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/wdlviz.md

Executes the Python script with a sample WDL workflow provided via standard input.

```bash
python3 wdlviz.py << 'EOF'
    version 1.0
    workflow w {
        call sum as sum1 {
            input: x = 1, y = 2
        }
        Int twice = 2*sum1.z
        call sum as sum2 {
            input: x = sum1.z, y = twice
        }
    }
    task sum {
        input {
            Int x
            Int y
        }
        command {
            echo $(( ~{x} + ~{y} ))
        }
        output {
            Int z = read_int(stdout())
        }
    }
EOF
```

--------------------------------

### Suppressing Warnings in WDL with Inline Comments

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/check.md

This bash script creates a WDL task file (`check_demo2.wdl`) demonstrating how to suppress specific warnings using inline WDL comments like `# !WarningName`. This example suppresses `ForwardReference`, `StringCoercion`, and `NameCollision` warnings.

```bash
$ cat << 'EOF' > check_demo2.wdl
  task t {
      String s = i  # !ForwardReference !StringCoercion
      Int? i
      command <<<
         if [ ! -n ~{s} ]; then
             echo Empty
         fi
      >>>
      output {
          String t = read_string(stdout())
          # Meant to do that: !NameCollision
      }
  }
EOF
```

--------------------------------

### Configure Podman Backend for miniWDL

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Set the MINIWDL__SCHEDULER__CONTAINER_BACKEND environment variable to 'podman' to use Podman for container execution. Ensure passwordless sudo for podman or configure rootless mode.

```bash
# Configure Podman backend
export MINIWDL__SCHEDULER__CONTAINER_BACKEND=podman
# Ensure passwordless sudo for podman (or configure rootless)
sudo -kn podman run ubuntu:20.04 cat /etc/issue
miniwdl run_self_test
```

--------------------------------

### Configure Podman Runtime for miniwdl

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_backends.md

Set the environment variable to use Podman as the container backend for miniwdl. Ensure Podman is configured for passwordless sudo if running miniwdl as a non-root user.

```bash
sudo -kn podman run ubuntu:20.04 cat /etc/issue
```

```bash
MINIWDL__SCHEDULER__CONTAINER_BACKEND=podman
```

```bash
MINIWDL__PODMAN__EXE='["podman"]'
```

--------------------------------

### miniwdl run CLI

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_cli.md

Command line interface for executing WDL workflows.

```APIDOC
## CLI Command: miniwdl run

### Description
Executes a WDL workflow specified by the URI. Supports various input formats, runtime configurations, and debugging options.

### Usage
miniwdl run [-h] [-i INPUT.json] [--empty input_key] [--none input_key] [--task TASK_NAME] [-j] [-d DIR] [--error-json] [-o OUT.json] [-v] [--no-color] [--log-json] [--cfg FILE] [--runtime-defaults JSON] [--no-cache] [--env VARNAME[=VALUE]] [--copy-input-files] [--copy-input-files-for TASK_NAME] [--as-me] [-p DIR] [--no-outside-imports] [--no-quant-check] [--debug] URI [input_key=value [input_key=value ...]]

### Parameters
- **URI** (string) - Required - The URI of the WDL workflow to run.
- **input_key=value** (string) - Optional - Additional input key-value pairs.
- **-i INPUT.json** (file) - Optional - Path to a JSON file containing workflow inputs.
- **-o OUT.json** (file) - Optional - Path to write the workflow output JSON.
- **-d DIR** (directory) - Optional - Directory for workflow execution outputs.
- **--cfg FILE** (file) - Optional - Path to a configuration file.
- **--task TASK_NAME** (string) - Optional - Run only the specified task.
- **--env VARNAME[=VALUE]** (string) - Optional - Set environment variables for the workflow execution.
```

--------------------------------

### Run full miniwdl test suite

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/CONTRIBUTING.md

Execute the complete test suite for miniwdl, including code coverage reporting. This process may take several minutes.

```bash
make test
```

--------------------------------

### Test WDL function with miniwdl run

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/add_functions.md

Execute a WDL workflow using the newly defined function via the command line.

```bash
$ python3 -m WDL run --dir /tmp <(echo "
workflow factorials {
    scatter (n in range(11)) {
        Pair[Int,Int] p = (n, factorial(n))
    }
    output {
        Array[Pair[Int,Int]] results = p
    }
}
")
```

--------------------------------

### Downloading and Tracing a MiniWDL Workflow

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/trace_identifiers.md

This command sequence demonstrates how to download a MiniWDL workflow file and then use the trace_identifiers.py script to analyze its structure and identify variable definitions.

```bash
$ wget https://raw.githubusercontent.com/gatk-workflows/gatk4-germline-snps-indels/master/joint-discovery-gatk4-local.wdl
$ python3 trace_identifiers.py joint-discovery-gatk4-local.wdl
L103 Array[File] input_gvcfs defined on L48
L117 Array[String] unpadded_intervals defined on L115
L124 Array[String] sample_names defined on L47
L125 Array[String] unpadded_intervals defined on L115
L127 Array[File] input_gvcfs defined on L48
L128 Array[File] input_gvcfs_indices defined on L49
L138 Array[String] unpadded_intervals defined on L115
L165 Array[File] HardFilterAndMakeSitesOnlyVcf.sites_only_vcf defined on L150
L166 Array[File] HardFilterAndMakeSitesOnlyVcf.sites_only_vcf_index defined on L150
L179 Array[String] indel_recalibration_tranche_values defined on L61
L180 Array[String] indel_recalibration_annotation_values defined on L62
L199 Array[String] snp_recalibration_tranche_values defined on L59
L200 Array[String] snp_recalibration_annotation_values defined on L60
L216 Array[File] HardFilterAndMakeSitesOnlyVcf.sites_only_vcf defined on L150
L219 Array[File] HardFilterAndMakeSitesOnlyVcf.sites_only_vcf defined on L150
L220 Array[File] HardFilterAndMakeSitesOnlyVcf.sites_only_vcf_index defined on L150
L223 Array[String] snp_recalibration_tranche_values defined on L59
L224 Array[String] snp_recalibration_annotation_values defined on L60
L241 Array[File] SNPsVariantRecalibratorScattered.tranches defined on L217
L256 Array[String] snp_recalibration_tranche_values defined on L59
L257 Array[String] snp_recalibration_annotation_values defined on L60
L276 Array[File] HardFilterAndMakeSitesOnlyVcf.variant_filtered_vcf defined on L150
L280 Array[File] HardFilterAndMakeSitesOnlyVcf.variant_filtered_vcf defined on L150
L281 Array[File] HardFilterAndMakeSitesOnlyVcf.variant_filtered_vcf_index defined on L150
L285 Array[File] SNPsVariantRecalibratorScattered.recalibration defined on L217
L285 Array[File] SNPsVariantRecalibratorScattered.recalibration defined on L217
L286 Array[File] SNPsVariantRecalibratorScattered.recalibration_index defined on L217
L286 Array[File] SNPsVariantRecalibratorScattered.recalibration_index defined on L217
L317 Array[File] ApplyRecalibration.recalibrated_vcf defined on L277
L318 Array[File] ApplyRecalibration.recalibrated_vcf_index defined on L277
L344 Array[File?] CollectMetricsSharded.detail_metrics_file defined on L297
L345 Array[File?] CollectMetricsSharded.summary_metrics_file defined on L297
L401 Array[File] input_gvcfs defined on L385
L402 Array[String] sample_names defined on L384
L560 Array[String] recalibration_tranche_values defined on L536
L561 Array[String] recalibration_annotation_values defined on L537
L614 Array[String] recalibration_tranche_values defined on L588
L615 Array[String] recalibration_annotation_values defined on L589
L668 Array[String] recalibration_tranche_values defined on L642
L669 Array[String] recalibration_annotation_values defined on L643
L707 Array[File] input_fofn defined on L693
L794 Array[File] input_vcfs_fofn defined on L777
L868 Array[File] input_details_fofn defined on L852

```

--------------------------------

### Clone miniwdl repository

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/CONTRIBUTING.md

Clone the miniwdl repository and its submodules to set up the development environment. Ensure you use the --recursive flag for submodules.

```bash
git clone --recursive https://github.com/chanzuckerberg/miniwdl.git
cd miniwdl
```

--------------------------------

### View miniwdl zip usage help

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/zip.md

Display the command-line interface options and arguments for the miniwdl zip command.

```default
usage: miniwdl zip [-h] [-o ZIP_FILE] [-f] [--input JSON_OR_FILE] [-a FILE]
                   [-p DIR] [--no-outside-imports] [--no-quant-check]
                   [--debug]
                   WDL_FILE
```

--------------------------------

### MiniWDL Configuration File Format

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Explains the INI-style configuration file format for customizing miniWDL behavior, including cache settings, runtime defaults, and scheduler options.

```APIDOC
## Configuration File Format

Configure miniWDL using INI-style configuration files or environment variables for cache settings, runtime defaults, and container backends.

### Configuration File Example (`~/.config/miniwdl.cfg`)
```ini
[call_cache]
# Enable output caching for task/workflow reuse
put = true
get = true
dir = ~/.cache/miniwdl

[download_cache]
# Cache downloaded URI inputs
put = true
get = true
dir = /tmp/miniwdl_download_cache

[task_runtime]
# Default runtime settings
defaults = {
    "docker": "ubuntu:20.04",
    "maxRetries": 1
  }
# Memory limit multiplier (0 = no limit)
memory_limit_multiplier = 1.5

[scheduler]
# Container backend: docker_swarm, podman, singularity, udocker
container_backend = docker_swarm
# Maximum concurrent tasks (0 = auto-detect)
task_concurrency = 0

[download_awscli]
# Use host AWS credentials for S3 downloads
host_credentials = true
```

### Environment Variable Overrides
Environment variables can override configuration file settings using double underscore delimiters.

```bash
# Environment variable overrides
export MINIWDL__CALL_CACHE__PUT=true
export MINIWDL__CALL_CACHE__GET=true
export MINIWDL__TASK_RUNTIME__DEFAULTS='{"docker":"ubuntu:22.04"}'
export MINIWDL__SCHEDULER__CONTAINER_BACKEND=podman
```
```

--------------------------------

### miniwdl localize Command

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Demonstrates how to use the `miniwdl localize` command to download and cache WDL-related files.

```APIDOC
## miniwdl localize

### Description
Localize specific URIs or directories for use with WDL workflows, with options to force re-download and bypass the cache.

### Usage
```bash
# Localize specific URIs
miniwdl localize --file s3://bucket/reference.fasta \
                 --file https://example.com/data.bam

# Localize directories
miniwdl localize --directory s3://bucket/database/

# Force re-download (bypass cache)
miniwdl localize workflow.wdl inputs.json --no-cache
```

### Parameters
* `--file` (URI): Specifies a file URI to localize.
* `--directory` (URI): Specifies a directory URI to localize.
* `--no-cache`: Forces re-download of files, bypassing the cache.
```

--------------------------------

### miniwdl input_template Command Line Usage

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/input_template.md

This shows the available options for the `miniwdl input_template` command, including arguments for specifying tasks, namespaces, and debugging.

```bash
usage: miniwdl input_template [-h] [--task TASK_NAME] [--no-namespace]
                              [-p DIR] [--no-outside-imports]
                              [--no-quant-check] [--debug]
                              [WDL_URI]
```

--------------------------------

### Python API - AST Traversal with WDL.Walker

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Explains how to traverse WDL abstract syntax trees (AST) for static analysis, linting, and code transformation using `WDL.Walker`.

```APIDOC
## Python API - AST Traversal with WDL.Walker

Traverse WDL abstract syntax trees for static analysis, linting, and code transformation.

### Usage
```python
import WDL

# Load document
doc = WDL.load("workflow.wdl")

# Custom walker to find all Array identifier expressions
def trace_identifiers(obj):
    if isinstance(obj, WDL.Document):
        if obj.workflow:
            trace_identifiers(obj.workflow)
        for task in obj.tasks:
            trace_identifiers(task)
    elif isinstance(obj, WDL.Workflow):
        for ch in (obj.inputs or []) + obj.body + (obj.outputs or []):
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Task):
        for ch in (obj.inputs or []) + obj.postinputs + [obj.command] + obj.outputs:
            trace_identifiers(ch)
    elif isinstance(obj, WDL.WorkflowSection):
        trace_identifiers(obj.expr)
        for ch in obj.body:
            trace_identifiers(ch)
    elif isinstance(obj, WDL.Call):
        for rhs in obj.inputs.values():
            trace_identifiers(rhs)
    elif isinstance(obj, WDL.Decl):
        trace_identifiers(obj.expr)
    elif isinstance(obj, WDL.Expr.Base):
        for ch in obj.children:
            trace_identifiers(ch)

    # Report Array identifiers
    if isinstance(obj, WDL.Expr.Ident) and isinstance(obj.type, WDL.Type.Array):
        print(f"L{obj.pos.line} Array[{obj.type.item_type}] {obj.name}")

trace_identifiers(doc)
```
```

--------------------------------

### Configure miniwdl Settings with miniwdl configure

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Interactively configure miniwdl settings for call caching, download caching, and AWS credentials. Can show current configuration, force overwrites, or use specific config files.

```bash
# Interactive configuration wizard
miniwdl configure
```

```bash
# Show current effective configuration
miniwdl configure --show
```

```bash
# Force overwrite existing configuration
miniwdl configure --force
```

```bash
# Use specific config file
miniwdl configure ~/.config/custom_miniwdl.cfg
```

--------------------------------

### Run quick miniwdl tests

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/CONTRIBUTING.md

Run a faster version of the test suite that omits slower test cases and does not track coverage. This is useful for quick checks.

```bash
make qtest
```

--------------------------------

### Package WDL Workflows with miniwdl zip

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Create portable ZIP archives of WDL workflows, including imports, for distribution. Supports specifying output filenames, including default inputs, additional files, and forcing overwrites.

```bash
# Create workflow ZIP archive
miniwdl zip workflow.wdl
# Creates: workflow.wdl.zip
```

```bash
# Specify output filename
miniwdl zip workflow.wdl -o my_workflow.zip
```

```bash
# Include default inputs JSON
miniwdl zip workflow.wdl --input defaults.json
```

```bash
# Include additional files
miniwdl zip workflow.wdl -a README.md -a config.yaml
```

```bash
# Force overwrite existing archive
miniwdl zip workflow.wdl -f
```

--------------------------------

### Configure Download Caching

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/runner_reference.md

Enable download caching by adding these settings to the [download_cache] section of the configuration file.

```default
[download_cache]
put = true
get = true
dir = /tmp/miniwdl_download_cache
```

--------------------------------

### Registering the custom function

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/add_functions.md

Initialize the custom function instance within the WDL.StdLib.Base constructor.

```python3
        ...
        self.choose_random = _ChooseRandom()
        ...
```

--------------------------------

### Run `miniwdl check` with Suppressed Warnings

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/check.md

After creating `check_demo2.wdl` with inline suppressions, running `miniwdl check` shows that some warnings are now hidden. This output still reports the `MissingVersion` and `CommandShellCheck` warnings, as they were not suppressed.

```none
$ miniwdl check check_demo2.wdl
check_demo2.wdl
    (Ln 1, Col 1) MissingVersion, document should declare WDL version; draft-2 assumed
    task t
        (Ln 5, Col 17) CommandShellCheck, SC2236 Use -z instead of ! -n.
        (Ln 2, Col 10) UnusedDeclaration, nothing references String s
```

--------------------------------

### Execute WDL Workflows with miniwdl run

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Run WDL workflows and tasks locally. Supports command-line inputs, JSON input files, array inputs, specific task execution, output directory specification, runtime defaults, and dry runs. Can also run from ZIP archives or URLs.

```bash
# Preview workflow inputs and outputs without running
miniwdl run workflow.wdl
```

```bash
# Run workflow with command-line inputs
miniwdl run workflow.wdl \
    reads_unmapped_bams=sample.bam \
    reference_fasta=reference.fasta \
    sample_name=MySample \
    --verbose
```

```bash
# Run with JSON input file
miniwdl run workflow.wdl -i inputs.json
```

```bash
# Run with array inputs (repeat the key)
miniwdl run workflow.wdl \
    input_files=file1.bam \
    input_files=file2.bam \
    input_files=file3.bam
```

```bash
# Run a specific task from multi-task document
miniwdl run document.wdl --task TaskName input1=value1
```

```bash
# Specify output directory
miniwdl run workflow.wdl -d /path/to/output inputs=values
```

```bash
# Run with runtime defaults (retry failed tasks)
miniwdl run workflow.wdl --runtime-defaults '{"maxRetries":2}' inputs=values
```

```bash
# Output JSON only (dry run)
miniwdl run workflow.wdl -j input1=value1
```

```bash
# Run from ZIP archive or URL
miniwdl run workflow.wdl.zip input1=value1
miniwdl run https://example.com/workflow.wdl input1=value1
```

--------------------------------

### Generate and Use WDL Input Template

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/input_template.md

Use `miniwdl input-template` to generate a JSON skeleton for WDL inputs. Edit the generated JSON file and then use it with `miniwdl run`.

```bash
$ miniwdl input-template path/to/my.wdl > my_inputs.json
$ vim my_inputs.json  # edit template
$ miniwdl run path/to/my.wdl -i my_inputs.json
```

--------------------------------

### Execute a WDL workflow

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/FAQ.md

Runs a specified WDL file. Use the --verbose flag for detailed execution information.

```bash
miniwdl run hello.wdl
```

```bash
miniwdl run myfile.wdl
```

```bash
miniwdl run myfile.wdl --verbose
```

--------------------------------

### Provide Cromwell-style JSON Inputs

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/getting_started.md

For complex inputs or to separate input definitions from the command, supply a Cromwell-style JSON file using the --input flag.

```json
{
  "assemble_refbased.reads_unmapped_bams": [
    {
      "class": "File",
      "location": "test/input/G5012.3.testreads.bam"
    }
  ],
  "assemble_refbased.reference_fasta": {
    "class": "File",
    "location": "test/input/ebov-makona.fasta"
  },
  "assemble_refbased.sample_name": "G5012.3"
}
```

--------------------------------

### miniwdl zip Command

Source: https://github.com/chanzuckerberg/miniwdl/blob/main/docs/zip.md

Generates a ZIP file containing a WDL source file and its imported dependencies. This ZIP can be directly used with `miniwdl run`.

```APIDOC
## miniwdl zip

### Description
Generates a ZIP file including a given WDL source code file and any other WDL files it imports. The ZIP file can be supplied directly to `miniwdl run`, which can extract it automatically.

Optionally, you can also include a JSON file with default workflow inputs. Any command-line arguments provided at runtime would be merged into (override) these defaults.

The ZIP file will include a MANIFEST.json identifying the top-level WDL and inputs JSON, if present. The manifest format follows that of Amazon Genomics CLI.

### Command line usage
```bash
$ miniwdl zip path/to/my.wdl
$ miniwdl run my.wdl.zip input1=value1 ...
```

### Arguments
```default
usage: miniwdl zip [-h] [-o ZIP_FILE] [-f] [--input JSON_OR_FILE] [-a FILE]
                   [-p DIR] [--no-outside-imports] [--no-quant-check]
                   [--debug]
                   WDL_FILE
```

#### Positional Arguments
*   **WDL_FILE** (string) - Required - The path to the main WDL file to be zipped.

#### Named Arguments
*   **-h, --help** - Show help message and exit.
*   **-o ZIP_FILE, --output ZIP_FILE** - Specify the output ZIP file name. Defaults to `<WDL_FILE>.zip`.
*   **-f, --force** - Overwrite output ZIP file if it exists.
*   **--input JSON_OR_FILE** - Path to a JSON file containing default workflow inputs. These can be overridden by command-line arguments.
*   **-a FILE, --auxiliary FILE** - Include an auxiliary file in the ZIP archive.
*   **-p DIR, --package-dir DIR** - Directory to search for imported WDL files. Defaults to the directory of the main WDL file.
*   **--no-outside-imports** - Prevent importing WDL files from outside the specified package directory.
*   **--no-quant-check** - Disable quantitative checks on inputs and outputs.
*   **--debug** - Enable debug logging.
```

--------------------------------

### Localize URIs and Directories with miniwdl

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Use the `miniwdl localize` command to download remote files or directories to the local filesystem. The `--no-cache` flag forces a re-download, bypassing the cache.

```bash
miniwdl localize --file s3://bucket/reference.fasta \
                 --file https://example.com/data.bam
```

```bash
miniwdl localize --directory s3://bucket/database/
```

```bash
miniwdl localize workflow.wdl inputs.json --no-cache
```

--------------------------------

### Python API - WDL.load()

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Shows how to load and parse WDL documents programmatically using `WDL.load()`, including handling imports, typechecking, and parsing document text directly.

```APIDOC
## Python API - WDL.load()

Load and parse WDL documents programmatically with automatic import resolution and typechecking.

### Usage
```python
import WDL

# Load WDL document from file
doc = WDL.load("workflow.wdl")

# Access workflow and tasks
if doc.workflow:
    print(f"Workflow: {doc.workflow.name}")
    for inp in doc.workflow.available_inputs:
        print(f"  Input: {inp.name} ({inp.value.type})")
    for out in doc.workflow.effective_outputs:
        print(f"  Output: {out.name} ({out.value})")

for task in doc.tasks:
    print(f"Task: {task.name}")
    print(f"  Command: {task.command}")

# Load with custom import paths
doc = WDL.load("workflow.wdl", path=["/path/to/imports", "/another/path"])

# Disable quantifier checking for legacy WDL
doc = WDL.load("legacy.wdl", check_quant=False)

# Parse document text directly (no imports or typechecking)
doc = WDL.parse_document("""
version 1.0
task hello {
    command { echo "Hello World" }
    output { String message = read_string(stdout()) }
}
""")
```
```

--------------------------------

### Run Pre-commit Hook on All Files

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Execute the configured pre-commit hooks on all files in the repository using the 'pre-commit run --all-files' command.

```bash
# Run pre-commit on all files
pre-commit run --all-files
```

--------------------------------

### miniwdl Configuration File Format

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Configure miniwdl using an INI-style file (`~/.config/miniwdl.cfg`) for cache settings, runtime defaults, and container backends. Environment variables can override these settings using double underscore delimiters.

```ini
# ~/.config/miniwdl.cfg

[call_cache]
# Enable output caching for task/workflow reuse
put = true
get = true
dir = ~/.cache/miniwdl

[download_cache]
# Cache downloaded URI inputs
put = true
get = true
dir = /tmp/miniwdl_download_cache

[task_runtime]
# Default runtime settings
defaults = {
    "docker": "ubuntu:20.04",
    "maxRetries": 1
  }
# Memory limit multiplier (0 = no limit)
memory_limit_multiplier = 1.5

[scheduler]
# Container backend: docker_swarm, podman, singularity, udocker
container_backend = docker_swarm
# Maximum concurrent tasks (0 = auto-detect)
task_concurrency = 0

[download_awscli]
# Use host AWS credentials for S3 downloads
host_credentials = true
```

```bash
# Environment variable overrides (double underscore delimiters)
export MINIWDL__CALL_CACHE__PUT=true
export MINIWDL__CALL_CACHE__GET=true
export MINIWDL__TASK_RUNTIME__DEFAULTS='{"docker":"ubuntu:22.04"}'
export MINIWDL__SCHEDULER__CONTAINER_BACKEND=podman
```

--------------------------------

### Python API - WDL.values_from_json() / WDL.values_to_json()

Source: https://context7.com/chanzuckerberg/miniwdl/llms.txt

Demonstrates converting between Cromwell-style JSON and WDL value bindings for programmatic input/output handling.

```APIDOC
## Python API - WDL.values_from_json() / WDL.values_to_json()

Convert between Cromwell-style JSON and WDL value bindings for programmatic input/output handling.

### Usage
```python
import WDL
import json

# Load workflow
doc = WDL.load("workflow.wdl")
workflow = doc.workflow

# Parse JSON inputs to WDL values
input_json = {
    "workflow_name.sample_name": "MySample",
    "workflow_name.input_files": ["/path/to/file1.bam", "/path/to/file2.bam"],
    "workflow_name.reference": "/path/to/reference.fasta"
}

input_env = WDL.values_from_json(
    input_json,
    workflow.available_inputs,
    required=workflow.required_inputs,
    namespace=workflow.name
)

# Access individual values
for binding in input_env:
    print(f"{binding.name} = {binding.value.json}")

# Convert WDL values back to JSON
output_json = WDL.values_to_json(input_env, namespace=workflow.name)
print(json.dumps(output_json, indent=2))
```
```