Skip to content

Reference Configuration File

Configuration reference ​

sprocket.toml controls Sprocket commands and runtime behavior. sprocket config init prints a configuration file with the defaults, while sprocket config schema prints the JSON Schema used to build this page. For configuration discovery, load order, and incremental merging, see Configuration.

Keys marked as required must be present when their containing table is configured. A default shown here comes from the schema or, when the schema omits it, from sprocket config init.

[format] ​

Configuration for the format command.

indent ​

  • Type: one of "tabs" | integer
  • Default: 4
  • Constraints: minimum 0; maximum 16; format uint

The indentation configuration.

max_line_length ​

  • Type: one of "none" | integer
  • Default: 90
  • Constraints: minimum 60; maximum 240; format uint

The maximum line length.

sort_imports ​

  • Type: boolean
  • Default: true

Whether to sort import statements alphabetically.

sort_inputs ​

  • Type: boolean
  • Default: false

Whether to sort input sections.

trailing_commas ​

  • Type: boolean
  • Default: true

Whether to add trailing commas to multiline lists.

reorder_sections ​

  • Type: boolean
  • Default: false

Whether to reorder task and workflow sections to Sprocket's opinionated order.

upgrade_deprecations ​

  • Type: boolean
  • Default: false

Whether to eagerly upgrade deprecated WDL constructs.

Currently this includes changing curly brace command sections ({}) into heredoc command sections (<<<>>>) and changing dollar-style placeholders (${}) into tilde-style placeholders (~{}).

newline_style ​

  • Type: one of "auto" | "unix" | "windows"
  • Default: "auto"

The newline style.

quote_style ​

  • Type: one of "double" | "single" | "preserve"
  • Default: "preserve"

The quote style.

[check] ​

Configuration for the check and lint commands.

See also: Check and lint command.

except ​

  • Type: array of string
  • Default: []

Rule IDs or tags to except from running.

This list is also honored by the analyzer subcommand.

deny_warnings ​

  • Type: boolean
  • Default: false

Causes the command to fail if any warnings are reported.

deny_notes ​

  • Type: boolean
  • Default: false

Causes the command to fail if any notes or warnings are reported.

hide_notes ​

  • Type: boolean
  • Default: false

Hide diagnostics with note severity.

hide_warnings ​

  • Type: boolean
  • Default: false

Hide diagnostics with warning and note severity.

tags ​

  • Type: array of string
  • Default: []

Set of lint tags to opt into. Leave this empty to use the default set of tags.

baseline ​

  • Type: string, nullable

Path to the diagnostic baseline file.

[check.lint] ​

Lint rule configuration.

See also: Check and lint command.

allowed_runtime_keys ​

  • Type: array of string
  • Default: []

List of keys to ignore in the ExpectedRuntimeKeys lint.

Example ​
toml
allowed_runtime_keys = ["foo"]

allowed_names ​

  • Type: array of string
  • Default: []

List of names to ignore in the SnakeCase and DeclarationName lints.

Example ​
toml
allowed_names = ["Foo", "counter_int"]

bash_set_options ​

  • Type: array of one of "allexport" | "braceexpand" | "errexit" | "errtrace" | "functrace" | "hashall" | "keyword" | "noclobber" | "noexec" | "noglob" | "nolog" | "nounset" | "onecmd" | "physical" | "pipefail" | "posix" | "privileged" | "restricted" | "verbose" | "xtrace"
  • Default: ["errexit", "nounset", "pipefail"]

List of options to enforce in the bash set builtin for every command section.

Example ​
toml
bash_set_options = ["errexit", "nounset", "pipefail"]

[analyzer] ​

Configuration for the analyzer command.

lint ​

  • Type: boolean
  • Default: false

Whether to enable lint rules.

[run] ​

Configuration for the run command.

See also: Run command.

backend ​

  • Type: string
  • Default: "default"

The name of the backend to use.

suppress_env_specific_output ​

  • Type: boolean
  • Default: false

(Experimental) Avoid environment-specific output; default is false.

If this option is true, selected error messages and log output will avoid emitting environment-specific output such as absolute paths and system resource counts.

This is largely meant to support "golden testing" where a test's success depends on matching an expected set of outputs exactly. Cues that help users overcome errors, such as the path to a temporary directory or the number of CPUs available to the system, confound this style of testing. This flag is a best-effort experimental attempt to reduce the impact of these differences in order to allow a wider range of golden tests to be written.

experimental_features_enabled ​

  • Type: boolean
  • Default: false

(Experimental) Whether experimental features are enabled; default is false.

Experimental features are provided to users with heavy caveats about their stability and rough edges. Use at your own risk, but feedback is quite welcome.

fail ​

  • Type: one of "slow" | "fast"
  • Default: "slow"

The failure mode for workflow or task evaluation.

A value of FailureMode::Slow will result in evaluation waiting for executing tasks to complete upon error or interruption.

A value of FailureMode::Fast will immediately attempt to cancel executing tasks upon error or interruption.

digest_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for runtime digest caches.

The file and directory digests calculated during evaluation are stored in LRU caches with this capacity.

The capacity cannot be zero.

Defaults to 1000.

choice_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the runtime enum choice cache.

The values created for enums during evaluation are stored in an LRU cache with this capacity.

The capacity cannot be zero.

Defaults to 1000.

regex_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the runtime compiled regular expression cache.

When a WDL stdlib function that takes a regular expression is called, a newly seen regular expression is compiled and stored in an LRU cache with this capacity.

The capacity cannot be zero.

Defaults to 1000.

output_dir ​

  • Type: string
  • Default: "./out"

The output directory (default: ./out).

Individual runs are stored at <output_dir>/runs/<target>/<timestamp>/.

events_capacity ​

  • Type: integer
  • Default: 5000
  • Constraints: minimum 0; format uint32

The capacity of the events channel used to display progress statistics.

If the number of progress events being generated outpaces Sprocket's ability to read the events for displaying the progress statistics and the channel reaches its capacity, Sprocket will stop displaying progress statistics. This is most likely to occur when Sprocket has concurrently queued up a large number of tasks.

Increasing the capacity will increase the size of the memory allocation made by the events channel.

The default is 5000.

[run.http] ​

HTTP configuration.

See also: Run command.

cache_dir ​

  • Type: string
  • Default: "system"

The HTTP download cache location.

Defaults to an operating system specific cache directory for the user.

retries ​

  • Type: integer
  • Default: 5
  • Constraints: minimum 0; format uint32

The number of retries for transferring files.

parallelism ​

  • Type: one of "available" | integer
  • Default: "available"
  • Constraints: minimum 0; format uint

The maximum parallelism for file transfers.

Defaults to the host's available parallelism.

hash_algorithm ​

  • Type: string
  • Default: "sha256"

The hash algorithm to use for calculating content digests for file uploads.

Defaults to sha256.

response_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the in-memory HTTP response cache.

Each HTTP operation performed in evaluation gets its own LRU response cache with this capacity.

The capacity cannot be zero.

Note: this capacity affects only in-memory caches; it does not affect the download cache.

Defaults to 1000.

[run.workflow] ​

Workflow evaluation configuration.

See also: Run command.

This table has no direct keys.

[run.workflow.scatter] ​

Scatter statement evaluation configuration.

See also: Run command.

concurrency ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 0; format uint64

The number of scatter array elements to process concurrently.

Defaults to 1000.

A value of 0 is invalid.

Lower values use less memory for evaluation and higher values may better saturate the task execution backend with tasks to execute for large scatters.

This setting does not change how many tasks an execution backend can run concurrently, but may affect how many tasks are sent to the backend to run at a time.

For example, if concurrency was set to 10 and we evaluate the following scatters:

wdl
scatter (i in range(100)) {
    call my_task
}

scatter (j in range(100)) {
    call my_task as my_task2
}

Here each scatter is independent and therefore there will be 20 calls (10 for each scatter) made concurrently. If the task execution backend can only execute 5 tasks concurrently, 5 tasks will execute and 15 will be "ready" to execute and waiting for an executing task to complete.

If instead we evaluate the following scatters:

wdl
scatter (i in range(100)) {
    scatter (j in range(100)) {
        call my_task
    }
}

Then there will be 100 calls (10*10 as 10 are made for each outer element) made concurrently. If the task execution backend can only execute 5 tasks concurrently, 5 tasks will execute and 95 will be "ready" to execute and waiting for an executing task to complete.

Warning: nested scatter statements cause exponential memory usage based on this value, as each scatter statement evaluation requires allocating new scopes for scatter array elements being processed.

[run.task] ​

Task evaluation configuration.

See also: Call caching; Run command.

retries ​

  • Type: one of "default" | integer
  • Default: "default"
  • Constraints: minimum 0; format uint64

The default maximum number of retries to attempt if a task fails.

A task's max_retries requirement will override this value.

container ​

  • Type: string
  • Default: "ubuntu:latest"

The default container to use if a container is not specified in a task's requirements.

shell ​

  • Type: string
  • Default: "bash"

The default shell to use for tasks.

Warning: the use of a shell other than bash may lead to tasks that may not be portable to other execution engines.

The shell must support a -c option to run a specific script file (i.e. an evaluated task command).

Note that this option affects all task commands, so every container that is used must contain the specified shell.

If using this setting causes your tasks to fail, please do not file an issue.

cpu_limit_behavior ​

  • Type: one of "try_with_max" | "deny"
  • Default: "deny"

The behavior when a task's cpu requirement cannot be met.

memory_limit_behavior ​

  • Type: one of "try_with_max" | "deny"
  • Default: "deny"

The behavior when a task's memory requirement cannot be met.

cache_dir ​

  • Type: string
  • Default: "system"

The call cache directory to use for caching task execution results.

Defaults to an operating system specific cache directory for the user.

cache ​

  • Type: one of "off" | "on" | "explicit"
  • Default: "off"

The call caching mode to use for tasks.

digests ​

  • Type: one of "strong" | "strongish" | "weak"
  • Default: "weak"

The content digest mode to use.

Used as part of call caching.

excluded_cache_requirements ​

  • Type: array of string
  • Default: []

Keys of task requirements to exclude from call cache checking.

When specified, these requirement keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for requirements that may vary between runs but should not invalidate the cache (e.g., dynamic resource allocation).

excluded_cache_hints ​

  • Type: array of string
  • Default: []

Keys of task hints to exclude from call cache checking.

When specified, these hint keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for hints that may vary between runs but should not invalidate the cache.

excluded_cache_inputs ​

  • Type: array of string
  • Default: []

Keys of task inputs to exclude from call cache checking.

When specified, these input keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for inputs that may vary between runs but should not affect the task's output.

[run.backends] ​

Task execution backends configuration.

If the collection is empty and backend has the default value, the engine default backend is used.

This table is a map. Replace <name> in the variant sections below with a unique configuration name.

See also: Run command.

[run.backends.<name>] — local ​

Use the local task execution backend.

See also: Run command.

cpu ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

Set the number of CPUs available for task execution.

Defaults to the number of logical CPUs for the host.

The value cannot be zero or exceed the host's number of CPUs.

memory ​

  • Type: string, nullable

Set the total amount of memory for task execution as a unit string (e.g. 2 GiB).

Defaults to the total amount of memory for the host.

The value cannot be zero or exceed the host's total amount of memory.

type ​

  • Type: "local"
  • Required: yes

Selects the local variant for this table.

[run.backends.<name>] — docker ​

Use the Docker task execution backend.

See also: Docker backend; Run command.

cleanup ​

  • Type: boolean
  • Default: true

Whether or not to remove a task's container after the task completes.

Defaults to true.

type ​

  • Type: "docker"
  • Required: yes

Selects the docker variant for this table.

[run.backends.<name>] — tes ​

Use the TES task execution backend.

See also: TES backend; Run command.

url ​

  • Type: string, nullable
  • Constraints: format uri

The URL of the Task Execution Service.

inputs ​

  • Type: string, nullable
  • Constraints: format uri

The root cloud storage URL for storing inputs.

outputs ​

  • Type: string, nullable
  • Constraints: format uri

The root cloud storage URL for storing outputs.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The polling interval, in seconds, for checking task status.

Defaults to 1 second.

retries ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The number of retries after encountering an error communicating with the TES server.

Defaults to no retries.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent requests the backend will send to the TES server.

Defaults to 10 concurrent requests.

insecure ​

  • Type: boolean
  • Default: false

Whether or not the TES server URL may use an insecure protocol like HTTP.

type ​

  • Type: "tes"
  • Required: yes

Selects the tes variant for this table.

[run.backends.<name>.auth] — tes / basic ​

Use basic authentication for the TES backend.

See also: TES backend; Run command.

username ​

  • Type: string
  • Required: yes

The HTTP basic authentication username.

password ​

  • Type: string
  • Required: yes

The HTTP basic authentication password.

type ​

  • Type: "basic"
  • Required: yes

Selects the basic variant for this table.

[run.backends.<name>.auth] — tes / bearer ​

Use bearer token authentication for the TES backend.

See also: TES backend; Run command.

token ​

  • Type: string
  • Required: yes

The HTTP bearer authentication token.

type ​

  • Type: "bearer"
  • Required: yes

Selects the bearer variant for this table.

[run.backends.<name>] — lsf_apptainer ​

Use the experimental LSF + Apptainer task execution backend.

Requires enabling experimental features.

See also: LSF backend; Run command.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The task monitor polling interval, in seconds.

Defaults to 30 seconds.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent LSF operations the backend will perform.

This controls the maximum concurrent number of bsub processes the backend will spawn to queue tasks.

Defaults to 10 concurrent operations.

job_name_prefix ​

  • Type: string, nullable

Prefix to add to every LSF job name before the task identifier. This is truncated as needed to satisfy the byte-oriented LSF job name limit.

type ​

  • Type: "lsf_apptainer"
  • Required: yes

Selects the lsf_apptainer variant for this table.

[run.backends.<name>.default_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[run.backends.<name>.short_task_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[run.backends.<name>.gpu_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[run.backends.<name>.fpga_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[run.backends.<name>.bsub] — lsf_apptainer ​

The additional arguments to bsub used to queue a new task.

See also: LSF backend; Run command.

args ​

  • Type: array of string
  • Default: []

The additional arguments to pass to the backend program.

[[run.backends.<name>.bsub.conditional]] — lsf_apptainer ​

Represents a set of conditional arguments for the LSF and Slurm backends.

Conditional arguments are passed to the program responsible for queuing a task when the associated conditional expression evaluates to true.

See also: LSF backend; Run command.

condition ​

  • Type: string
  • Required: yes

The condition for including the arguments.

args ​

  • Type: array of string
  • Default: []

The arguments to use when the condition evaluates to true.

[run.backends.<name>.apptainer] — lsf_apptainer ​

The configuration of Apptainer, which is used as the container runtime on the compute nodes where LSF dispatches tasks.

Note that this will likely be replaced by an abstraction over multiple container execution runtimes in the future, rather than being hardcoded to Apptainer.

See also: LSF backend; Run command.

executable ​

  • Type: string
  • Default: "apptainer"

Path to the Apptainer (or Singularity) executable.

Defaults to "apptainer". Set to "singularity" or a full path (e.g., /usr/local/bin/apptainer) if the executable is not on PATH or if using Singularity instead.

image_cache_dir ​

  • Type: string
  • Default: "system"

Path to a shared directory for caching pulled .sif images.

Defaults to an operating system specific cache directory for the user.

extra_args ​

  • Type: array of string
  • Default: []

Additional command-line arguments to pass to apptainer exec when executing tasks.

[run.backends.<name>] — slurm_apptainer ​

Use the experimental Slurm + Apptainer task execution backend.

Requires enabling experimental features.

See also: Slurm backend; Run command.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The task monitor polling interval, in seconds.

Defaults to 30 seconds.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent Slurm operations the backend will perform.

This controls the maximum concurrent number of sbatch processes the backend will spawn to queue tasks.

Defaults to 10 concurrent operations.

job_name_prefix ​

  • Type: string, nullable

Prefix to add to every Slurm job name before the task identifier.

type ​

  • Type: "slurm_apptainer"
  • Required: yes

Selects the slurm_apptainer variant for this table.

[run.backends.<name>.default_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[run.backends.<name>.short_task_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[run.backends.<name>.gpu_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[run.backends.<name>.fpga_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Run command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[run.backends.<name>.sbatch] — slurm_apptainer ​

The additional arguments to sbatch used to queue a new task.

See also: Slurm backend; Run command.

args ​

  • Type: array of string
  • Default: []

The additional arguments to pass to the backend program.

[[run.backends.<name>.sbatch.conditional]] — slurm_apptainer ​

Represents a set of conditional arguments for the LSF and Slurm backends.

Conditional arguments are passed to the program responsible for queuing a task when the associated conditional expression evaluates to true.

See also: Slurm backend; Run command.

condition ​

  • Type: string
  • Required: yes

The condition for including the arguments.

args ​

  • Type: array of string
  • Default: []

The arguments to use when the condition evaluates to true.

[run.backends.<name>.apptainer] — slurm_apptainer ​

The configuration of Apptainer, which is used as the container runtime on the compute nodes where Slurm dispatches tasks.

Note that this will likely be replaced by an abstraction over multiple container execution runtimes in the future, rather than being hardcoded to Apptainer.

See also: Slurm backend; Run command.

executable ​

  • Type: string
  • Default: "apptainer"

Path to the Apptainer (or Singularity) executable.

Defaults to "apptainer". Set to "singularity" or a full path (e.g., /usr/local/bin/apptainer) if the executable is not on PATH or if using Singularity instead.

image_cache_dir ​

  • Type: string
  • Default: "system"

Path to a shared directory for caching pulled .sif images.

Defaults to an operating system specific cache directory for the user.

extra_args ​

  • Type: array of string
  • Default: []

Additional command-line arguments to pass to apptainer exec when executing tasks.

[run.storage] ​

Storage configuration.

See also: Run command.

This table has no direct keys.

[run.storage.azure] ​

Azure Blob Storage configuration.

See also: Azure storage; Run command.

This table has no direct keys.

[run.storage.azure.auth] ​

Represents authentication information for Azure Blob Storage.

See also: Azure storage; Run command.

account_name ​

  • Type: string
  • Required: yes

The Azure Storage account name to use.

access_key ​

  • Type: string
  • Required: yes

The Azure Storage access key to use.

[run.storage.s3] ​

AWS S3 configuration.

See also: Amazon S3 storage; Run command.

region ​

  • Type: string, nullable

The default region to use for S3-schemed URLs (e.g. s3://<bucket>/<blob>).

Defaults to us-east-1.

[run.storage.s3.auth] ​

Represents authentication information for AWS S3 storage.

See also: Amazon S3 storage; Run command.

access_key_id ​

  • Type: string
  • Required: yes

The AWS Access Key ID to use.

secret_access_key ​

  • Type: string
  • Required: yes

The AWS Secret Access Key to use.

[run.storage.google] ​

Google Cloud Storage configuration.

See also: Google Cloud Storage; Run command.

This table has no direct keys.

[run.storage.google.auth] ​

Represents authentication information for Google Cloud Storage.

See also: Google Cloud Storage; Run command.

access_key ​

  • Type: string
  • Required: yes

The HMAC Access Key to use.

secret ​

  • Type: string
  • Required: yes

The HMAC Secret to use.

[server] ​

Configuration for the server command.

See also: Server command.

host ​

  • Type: string
  • Default: "127.0.0.1"

Host to bind to.

port ​

  • Type: integer
  • Default: 8080
  • Constraints: minimum 0; maximum 65535; format uint16

Port to bind to.

allowed_origins ​

  • Type: array of string
  • Default: []

Allowed CORS origins.

output_dir ​

  • Type: string
  • Default: "./out"

Directory for workflow outputs.

allowed_file_paths ​

  • Type: array of string
  • Default: []

Allowed file paths for file-based workflows.

allowed_urls ​

  • Type: array of string
  • Default: []

Allowed URL prefixes for URL-based workflows.

max_concurrent_runs ​

  • Type: one of "unlimited" | integer
  • Default: "unlimited"
  • Constraints: minimum 0; format uint

Maximum concurrent workflows.

orphan_timeout_minutes ​

  • Type: integer
  • Default: 5
  • Constraints: minimum 0; format uint64

How many minutes a session may go without recording a heartbeat before the runs it owns are marked orphaned. Applies to sprocket run invocations as well as servers.

[server.database] ​

Database configuration.

See also: Server command.

url ​

  • Type: string
  • Default: "default"

Database URL (e.g., sqlite://sprocket.db). Defaults to sprocket.db in the output directory. in the output directory.

[server.engine] ​

The engine configuration to use during execution.

See also: Server command.

backend ​

  • Type: string
  • Default: "default"

The name of the backend to use.

suppress_env_specific_output ​

  • Type: boolean
  • Default: false

(Experimental) Avoid environment-specific output; default is false.

If this option is true, selected error messages and log output will avoid emitting environment-specific output such as absolute paths and system resource counts.

This is largely meant to support "golden testing" where a test's success depends on matching an expected set of outputs exactly. Cues that help users overcome errors, such as the path to a temporary directory or the number of CPUs available to the system, confound this style of testing. This flag is a best-effort experimental attempt to reduce the impact of these differences in order to allow a wider range of golden tests to be written.

experimental_features_enabled ​

  • Type: boolean
  • Default: false

(Experimental) Whether experimental features are enabled; default is false.

Experimental features are provided to users with heavy caveats about their stability and rough edges. Use at your own risk, but feedback is quite welcome.

fail ​

  • Type: one of "slow" | "fast"
  • Default: "slow"

The failure mode for workflow or task evaluation.

A value of FailureMode::Slow will result in evaluation waiting for executing tasks to complete upon error or interruption.

A value of FailureMode::Fast will immediately attempt to cancel executing tasks upon error or interruption.

digest_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for runtime digest caches.

The file and directory digests calculated during evaluation are stored in LRU caches with this capacity.

The capacity cannot be zero.

Defaults to 1000.

choice_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the runtime enum choice cache.

The values created for enums during evaluation are stored in an LRU cache with this capacity.

The capacity cannot be zero.

Defaults to 1000.

regex_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the runtime compiled regular expression cache.

When a WDL stdlib function that takes a regular expression is called, a newly seen regular expression is compiled and stored in an LRU cache with this capacity.

The capacity cannot be zero.

Defaults to 1000.

[server.engine.http] ​

HTTP configuration.

See also: Server command.

cache_dir ​

  • Type: string
  • Default: "system"

The HTTP download cache location.

Defaults to an operating system specific cache directory for the user.

retries ​

  • Type: integer
  • Default: 5
  • Constraints: minimum 0; format uint32

The number of retries for transferring files.

parallelism ​

  • Type: one of "available" | integer
  • Default: "available"
  • Constraints: minimum 0; format uint

The maximum parallelism for file transfers.

Defaults to the host's available parallelism.

hash_algorithm ​

  • Type: string
  • Default: "sha256"

The hash algorithm to use for calculating content digests for file uploads.

Defaults to sha256.

response_cache_capacity ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 1; format uint32

The capacity for the in-memory HTTP response cache.

Each HTTP operation performed in evaluation gets its own LRU response cache with this capacity.

The capacity cannot be zero.

Note: this capacity affects only in-memory caches; it does not affect the download cache.

Defaults to 1000.

[server.engine.workflow] ​

Workflow evaluation configuration.

See also: Server command.

This table has no direct keys.

[server.engine.workflow.scatter] ​

Scatter statement evaluation configuration.

See also: Server command.

concurrency ​

  • Type: integer
  • Default: 1000
  • Constraints: minimum 0; format uint64

The number of scatter array elements to process concurrently.

Defaults to 1000.

A value of 0 is invalid.

Lower values use less memory for evaluation and higher values may better saturate the task execution backend with tasks to execute for large scatters.

This setting does not change how many tasks an execution backend can run concurrently, but may affect how many tasks are sent to the backend to run at a time.

For example, if concurrency was set to 10 and we evaluate the following scatters:

wdl
scatter (i in range(100)) {
    call my_task
}

scatter (j in range(100)) {
    call my_task as my_task2
}

Here each scatter is independent and therefore there will be 20 calls (10 for each scatter) made concurrently. If the task execution backend can only execute 5 tasks concurrently, 5 tasks will execute and 15 will be "ready" to execute and waiting for an executing task to complete.

If instead we evaluate the following scatters:

wdl
scatter (i in range(100)) {
    scatter (j in range(100)) {
        call my_task
    }
}

Then there will be 100 calls (10*10 as 10 are made for each outer element) made concurrently. If the task execution backend can only execute 5 tasks concurrently, 5 tasks will execute and 95 will be "ready" to execute and waiting for an executing task to complete.

Warning: nested scatter statements cause exponential memory usage based on this value, as each scatter statement evaluation requires allocating new scopes for scatter array elements being processed.

[server.engine.task] ​

Task evaluation configuration.

See also: Call caching; Server command.

retries ​

  • Type: one of "default" | integer
  • Default: "default"
  • Constraints: minimum 0; format uint64

The default maximum number of retries to attempt if a task fails.

A task's max_retries requirement will override this value.

container ​

  • Type: string
  • Default: "ubuntu:latest"

The default container to use if a container is not specified in a task's requirements.

shell ​

  • Type: string
  • Default: "bash"

The default shell to use for tasks.

Warning: the use of a shell other than bash may lead to tasks that may not be portable to other execution engines.

The shell must support a -c option to run a specific script file (i.e. an evaluated task command).

Note that this option affects all task commands, so every container that is used must contain the specified shell.

If using this setting causes your tasks to fail, please do not file an issue.

cpu_limit_behavior ​

  • Type: one of "try_with_max" | "deny"
  • Default: "deny"

The behavior when a task's cpu requirement cannot be met.

memory_limit_behavior ​

  • Type: one of "try_with_max" | "deny"
  • Default: "deny"

The behavior when a task's memory requirement cannot be met.

cache_dir ​

  • Type: string
  • Default: "system"

The call cache directory to use for caching task execution results.

Defaults to an operating system specific cache directory for the user.

cache ​

  • Type: one of "off" | "on" | "explicit"
  • Default: "off"

The call caching mode to use for tasks.

digests ​

  • Type: one of "strong" | "strongish" | "weak"
  • Default: "weak"

The content digest mode to use.

Used as part of call caching.

excluded_cache_requirements ​

  • Type: array of string
  • Default: []

Keys of task requirements to exclude from call cache checking.

When specified, these requirement keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for requirements that may vary between runs but should not invalidate the cache (e.g., dynamic resource allocation).

excluded_cache_hints ​

  • Type: array of string
  • Default: []

Keys of task hints to exclude from call cache checking.

When specified, these hint keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for hints that may vary between runs but should not invalidate the cache.

excluded_cache_inputs ​

  • Type: array of string
  • Default: []

Keys of task inputs to exclude from call cache checking.

When specified, these input keys will be ignored when calculating cache keys and validating cache entries.

This can be useful for inputs that may vary between runs but should not affect the task's output.

[server.engine.backends] ​

Task execution backends configuration.

If the collection is empty and backend has the default value, the engine default backend is used.

This table is a map. Replace <name> in the variant sections below with a unique configuration name.

See also: Server command.

[server.engine.backends.<name>] — local ​

Use the local task execution backend.

See also: Server command.

cpu ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

Set the number of CPUs available for task execution.

Defaults to the number of logical CPUs for the host.

The value cannot be zero or exceed the host's number of CPUs.

memory ​

  • Type: string, nullable

Set the total amount of memory for task execution as a unit string (e.g. 2 GiB).

Defaults to the total amount of memory for the host.

The value cannot be zero or exceed the host's total amount of memory.

type ​

  • Type: "local"
  • Required: yes

Selects the local variant for this table.

[server.engine.backends.<name>] — docker ​

Use the Docker task execution backend.

See also: Docker backend; Server command.

cleanup ​

  • Type: boolean
  • Default: true

Whether or not to remove a task's container after the task completes.

Defaults to true.

type ​

  • Type: "docker"
  • Required: yes

Selects the docker variant for this table.

[server.engine.backends.<name>] — tes ​

Use the TES task execution backend.

See also: TES backend; Server command.

url ​

  • Type: string, nullable
  • Constraints: format uri

The URL of the Task Execution Service.

inputs ​

  • Type: string, nullable
  • Constraints: format uri

The root cloud storage URL for storing inputs.

outputs ​

  • Type: string, nullable
  • Constraints: format uri

The root cloud storage URL for storing outputs.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The polling interval, in seconds, for checking task status.

Defaults to 1 second.

retries ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The number of retries after encountering an error communicating with the TES server.

Defaults to no retries.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent requests the backend will send to the TES server.

Defaults to 10 concurrent requests.

insecure ​

  • Type: boolean
  • Default: false

Whether or not the TES server URL may use an insecure protocol like HTTP.

type ​

  • Type: "tes"
  • Required: yes

Selects the tes variant for this table.

[server.engine.backends.<name>.auth] — tes / basic ​

Use basic authentication for the TES backend.

See also: TES backend; Server command.

username ​

  • Type: string
  • Required: yes

The HTTP basic authentication username.

password ​

  • Type: string
  • Required: yes

The HTTP basic authentication password.

type ​

  • Type: "basic"
  • Required: yes

Selects the basic variant for this table.

[server.engine.backends.<name>.auth] — tes / bearer ​

Use bearer token authentication for the TES backend.

See also: TES backend; Server command.

token ​

  • Type: string
  • Required: yes

The HTTP bearer authentication token.

type ​

  • Type: "bearer"
  • Required: yes

Selects the bearer variant for this table.

[server.engine.backends.<name>] — lsf_apptainer ​

Use the experimental LSF + Apptainer task execution backend.

Requires enabling experimental features.

See also: LSF backend; Server command.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The task monitor polling interval, in seconds.

Defaults to 30 seconds.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent LSF operations the backend will perform.

This controls the maximum concurrent number of bsub processes the backend will spawn to queue tasks.

Defaults to 10 concurrent operations.

job_name_prefix ​

  • Type: string, nullable

Prefix to add to every LSF job name before the task identifier. This is truncated as needed to satisfy the byte-oriented LSF job name limit.

type ​

  • Type: "lsf_apptainer"
  • Required: yes

Selects the lsf_apptainer variant for this table.

[server.engine.backends.<name>.default_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[server.engine.backends.<name>.short_task_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[server.engine.backends.<name>.gpu_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[server.engine.backends.<name>.fpga_lsf_queue] — lsf_apptainer ​

Configuration for an LSF queue.

Each queue can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that queue will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: LSF backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the queue; this is the string passed to bsub -q <queue_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this queue can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this queue can provision for a single task.

[server.engine.backends.<name>.bsub] — lsf_apptainer ​

The additional arguments to bsub used to queue a new task.

See also: LSF backend; Server command.

args ​

  • Type: array of string
  • Default: []

The additional arguments to pass to the backend program.

[[server.engine.backends.<name>.bsub.conditional]] — lsf_apptainer ​

Represents a set of conditional arguments for the LSF and Slurm backends.

Conditional arguments are passed to the program responsible for queuing a task when the associated conditional expression evaluates to true.

See also: LSF backend; Server command.

condition ​

  • Type: string
  • Required: yes

The condition for including the arguments.

args ​

  • Type: array of string
  • Default: []

The arguments to use when the condition evaluates to true.

[server.engine.backends.<name>.apptainer] — lsf_apptainer ​

The configuration of Apptainer, which is used as the container runtime on the compute nodes where LSF dispatches tasks.

Note that this will likely be replaced by an abstraction over multiple container execution runtimes in the future, rather than being hardcoded to Apptainer.

See also: LSF backend; Server command.

executable ​

  • Type: string
  • Default: "apptainer"

Path to the Apptainer (or Singularity) executable.

Defaults to "apptainer". Set to "singularity" or a full path (e.g., /usr/local/bin/apptainer) if the executable is not on PATH or if using Singularity instead.

image_cache_dir ​

  • Type: string
  • Default: "system"

Path to a shared directory for caching pulled .sif images.

Defaults to an operating system specific cache directory for the user.

extra_args ​

  • Type: array of string
  • Default: []

Additional command-line arguments to pass to apptainer exec when executing tasks.

[server.engine.backends.<name>] — slurm_apptainer ​

Use the experimental Slurm + Apptainer task execution backend.

Requires enabling experimental features.

See also: Slurm backend; Server command.

interval ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The task monitor polling interval, in seconds.

Defaults to 30 seconds.

max_concurrency ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint32

The maximum number of concurrent Slurm operations the backend will perform.

This controls the maximum concurrent number of sbatch processes the backend will spawn to queue tasks.

Defaults to 10 concurrent operations.

job_name_prefix ​

  • Type: string, nullable

Prefix to add to every Slurm job name before the task identifier.

type ​

  • Type: "slurm_apptainer"
  • Required: yes

Selects the slurm_apptainer variant for this table.

[server.engine.backends.<name>.default_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[server.engine.backends.<name>.short_task_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[server.engine.backends.<name>.gpu_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[server.engine.backends.<name>.fpga_slurm_partition] — slurm_apptainer ​

Configuration for a Slurm partition.

Each partition can optionally have per-task CPU and memory limits set so that tasks which are too large to be scheduled on that partition will fail immediately instead of pending indefinitely. In the future, these limits may be populated or validated by live information from the cluster, but for now they must be manually based on the user's understanding of the cluster configuration.

See also: Slurm backend; Server command.

name ​

  • Type: string
  • Required: yes

The name of the partition; this is the string passed to sbatch --partition=<partition_name>.

max_cpu_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum number of CPUs this partition can provision for a single task.

max_memory_per_task ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

The maximum memory this partition can provision for a single task.

[server.engine.backends.<name>.sbatch] — slurm_apptainer ​

The additional arguments to sbatch used to queue a new task.

See also: Slurm backend; Server command.

args ​

  • Type: array of string
  • Default: []

The additional arguments to pass to the backend program.

[[server.engine.backends.<name>.sbatch.conditional]] — slurm_apptainer ​

Represents a set of conditional arguments for the LSF and Slurm backends.

Conditional arguments are passed to the program responsible for queuing a task when the associated conditional expression evaluates to true.

See also: Slurm backend; Server command.

condition ​

  • Type: string
  • Required: yes

The condition for including the arguments.

args ​

  • Type: array of string
  • Default: []

The arguments to use when the condition evaluates to true.

[server.engine.backends.<name>.apptainer] — slurm_apptainer ​

The configuration of Apptainer, which is used as the container runtime on the compute nodes where Slurm dispatches tasks.

Note that this will likely be replaced by an abstraction over multiple container execution runtimes in the future, rather than being hardcoded to Apptainer.

See also: Slurm backend; Server command.

executable ​

  • Type: string
  • Default: "apptainer"

Path to the Apptainer (or Singularity) executable.

Defaults to "apptainer". Set to "singularity" or a full path (e.g., /usr/local/bin/apptainer) if the executable is not on PATH or if using Singularity instead.

image_cache_dir ​

  • Type: string
  • Default: "system"

Path to a shared directory for caching pulled .sif images.

Defaults to an operating system specific cache directory for the user.

extra_args ​

  • Type: array of string
  • Default: []

Additional command-line arguments to pass to apptainer exec when executing tasks.

[server.engine.storage] ​

Storage configuration.

See also: Server command.

This table has no direct keys.

[server.engine.storage.azure] ​

Azure Blob Storage configuration.

See also: Azure storage; Server command.

This table has no direct keys.

[server.engine.storage.azure.auth] ​

Represents authentication information for Azure Blob Storage.

See also: Azure storage; Server command.

account_name ​

  • Type: string
  • Required: yes

The Azure Storage account name to use.

access_key ​

  • Type: string
  • Required: yes

The Azure Storage access key to use.

[server.engine.storage.s3] ​

AWS S3 configuration.

See also: Amazon S3 storage; Server command.

region ​

  • Type: string, nullable

The default region to use for S3-schemed URLs (e.g. s3://<bucket>/<blob>).

Defaults to us-east-1.

[server.engine.storage.s3.auth] ​

Represents authentication information for AWS S3 storage.

See also: Amazon S3 storage; Server command.

access_key_id ​

  • Type: string
  • Required: yes

The AWS Access Key ID to use.

secret_access_key ​

  • Type: string
  • Required: yes

The AWS Secret Access Key to use.

[server.engine.storage.google] ​

Google Cloud Storage configuration.

See also: Google Cloud Storage; Server command.

This table has no direct keys.

[server.engine.storage.google.auth] ​

Represents authentication information for Google Cloud Storage.

See also: Google Cloud Storage; Server command.

access_key ​

  • Type: string
  • Required: yes

The HMAC Access Key to use.

secret ​

  • Type: string
  • Required: yes

The HMAC Secret to use.

[test] ​

Configuration for the test command.

See also: Test command.

parallelism ​

  • Type: integer
  • Default: 50
  • Required: yes
  • Constraints: minimum 0; format uint32

Number of test executions to run in parallel.

The default is 50.

throttle ​

  • Type: integer
  • Default: 100
  • Required: yes
  • Constraints: minimum 0; format uint64

Delay between submitting initial test executions, in milliseconds.

Once the parallelism permits are exhausted, this throttle delay is ignored and new tests are submitted eagerly as prior tests complete and free permits.

The default is 100 milliseconds.

fixtures_dir ​

  • Type: string, nullable

Directory containing test fixture files.

If not set, fixtures are resolved from <workspace>/test/fixtures.

run_dir ​

  • Type: string, nullable

Directory to use for executing tests.

If not set, runs are written to <workspace>/test/runs.

[doc] ​

Configuration for the doc command.

See also: Documentation command.

index_page ​

  • Type: string
  • Default: "none"

Path to a Markdown file to embed in the <output>/index.html file.

  • Type: string
  • Default: "none"

Path to an SVG logo to embed on each page.

If not supplied, the default Sprocket logo will be used.

  • Type: string
  • Default: "none"

Path to an alternate light mode SVG logo to embed on each page.

If not supplied, the logo SVG will be used; or if that is also not supplied, the default Sprocket logo will be used.

homepage_url ​

  • Type: string
  • Default: "none"

An optional link to the project's homepage.

github_url ​

  • Type: string
  • Default: "none"

An optional link to the project's GitHub repository.

slack_url ​

  • Type: string
  • Default: "none"

An optional link to the project's Slack workspace.

light_mode ​

  • Type: boolean
  • Default: false

Initialize pages in light mode instead of the default dark mode.

with_doc_comments ​

  • Type: boolean
  • Default: false

Enables support for documentation comments

This option is experimental. Follow the pre-RFC discussion here: https://github.com/openwdl/wdl/issues/757.

[doc.extra_html] ​

Configuration for custom HTML to embed in generated pages.

See also: Documentation command.

head ​

  • Type: string
  • Default: "none"

Path to an HTML file that should have its contents embedded in each HTML page, immediately before the closing <head> tag.

body_open ​

  • Type: string
  • Default: "none"

Path to an HTML file that should have its contents embedded in each HTML page, immediately after the opening <body> tag.

body_close ​

  • Type: string
  • Default: "none"

Path to an HTML file that should have its contents embedded in each HTML page, immediately before the closing <body> tag.

[doc.seo] ​

Search-engine-optimization metadata embedded in each page's <head>.

See also: Documentation command.

title ​

  • Type: string
  • Default: "none"

Site title. When set, each page's <title> becomes "<page> | <title>" and drives og:site_name.

description ​

  • Type: string
  • Default: "none"

Default page description (<meta name="description"> and the Open Graph and Twitter Card descriptions).

author ​

  • Type: string
  • Default: "none"

Content author (<meta name="author">).

keywords ​

  • Type: array of string
  • Default: []

Keywords (<meta name="keywords">).

base_url ​

  • Type: string
  • Default: "none"

Absolute site base URL used to build per-page <link rel="canonical"> and og:url values.

image_url ​

  • Type: string
  • Default: "none"

Social-preview image URL (og:image, twitter:image).

locale ​

  • Type: string
  • Default: "none"

Open Graph locale (og:locale); defaults to en_US when unset.

twitter_handle ​

  • Type: string
  • Default: "none"

Twitter handle, including the leading @ (twitter:site, twitter:creator).

robots ​

  • Type: string
  • Default: "none"

Robots directive (<meta name="robots">, e.g. index, follow).

theme_color ​

  • Type: string
  • Default: "none"

Browser theme color (<meta name="theme-color">).

[common] ​

Common configuration options for all commands.

color ​

  • Type: one of "auto" | "always" | "never"
  • Default: "auto"

Display color output.

report_mode ​

  • Type: one of "full" | "one-line"
  • Default: "full"

The report mode.

[common.wdl] ​

WDL-specific configuration.

fallback_version ​

  • Type: string
  • Default: "none"

The fallback version to use when a WDL document declares an unrecognized version (e.g., version development).

[common.wdl.feature_flags] ​

Feature flags for experimental WDL versions.

wdl_1_3 ​

  • Type: boolean
  • Default: true

Formerly enabled experimental WDL 1.3 features.

This flag is now a no-op as WDL 1.3 is fully supported. Setting this to false will emit a warning.

wdl_1_4 ​

  • Type: boolean
  • Default: false

Enables experimental WDL 1.4 features.

Defaults to false. While false, wdl-analysis reports an error for any document declaring version 1.4.

[module] ​

Configuration for the module command group ([module] section).

See also: Module commands.

This table has no direct keys.

[module.init] ​

Configuration for sprocket dev module init.

See also: Module commands.

author ​

  • Type: string, nullable

Default module author name.

email ​

  • Type: string, nullable

Default module author email.

license ​

  • Type: string, nullable

Default SPDX license expression.

[modules] ​

Configuration for the module system ([modules] section).

See also: Module commands.

cache_path ​

  • Type: string, nullable

Override the global cache location for this project.

default_git_platform ​

  • Type: one of "github" | "gitlab" | "bitbucket"
  • Default: "github"

The platform used to expand owner/repo dependency shorthands.

large_file_warning ​

  • Type: one of "none" | integer | string
  • Default: "1.0 MiB"
  • Constraints: minimum 0; format uint64; pattern ^\d+(?:\.\d+)?\s*(?:[KMGTPEkmgtpe][Ii]?[Bb]?|[Bb])$

Threshold for the large-file warning, or LargeFileWarning::Disabled when the user opts out. Defaults to 1 MiB.

max_transfer_bytes ​

  • Type: string
  • Default: "2.0 GiB"
  • Constraints: pattern ^[Uu][Nn][Ll][Ii][Mm][Ii][Tt][Ee][Dd]$; pattern ^\d+(?:\.\d+)?\s*(?:[KMGTPEkmgtpe][Ii]?[Bb]?|[Bb])$

Maximum bytes accepted from a Git remote during one fetch. Defaults to 2 GiB.

require_signed ​

  • Type: boolean
  • Default: false

Reject any unsigned module in the dependency tree.

trust_mode ​

  • Type: one of "auto-accept" | "tofu" | "confirm"
  • Default: "confirm"

Policy for accepting signer keys.

allowed_schemes ​

  • Type: array of string
  • Default: ["https", "ssh"]

URL schemes permitted for top-level Git dependencies. Defaults to ["https", "ssh"].

allowed_transitive_schemes ​

  • Type: array of string
  • Default: ["https"]

URL schemes permitted for transitive Git dependencies. Defaults to ["https"] so remote manifests cannot silently trigger SSH authentication against an attacker-controlled host.

max_advertised_refs ​

  • Type: integer
  • Default: 100000
  • Constraints: minimum 0; format uint64

Maximum number of advertised refs accepted from a remote. Defaults to 100,000.

denied_hosts ​

  • Type: array of string
  • Default: [ "localhost", "127.0.0.1", "::1", "0.0.0.0"]

Hosts denied for all Git dependencies. Defaults to localhost addresses.

allowed_hosts ​

  • Type: array of string
  • Default: []

Hosts permitted for top-level Git dependencies. Empty means any non-denied host is allowed.

allowed_transitive_hosts ​

  • Type: array of string
  • Default: ["github.com", "gitlab.com"]

Hosts permitted for transitive Git dependencies. Defaults to ["github.com", "gitlab.com"]. When non-empty, a transitive dependency may only be fetched from a host on this list, and Git credentials are presented only to those hosts, so a transitive manifest cannot direct the user's credentials at a host the user has not vouched for. An empty list permits any non-denied host but presents no credentials to transitive dependencies.

max_materialized_files ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

Maximum number of files allowed in a single materialized module tree. None (the default) disables the limit. Checked against the Git tree object after fetch but before sparse checkout; this bounds materialized content, not network transfer.

max_materialized_bytes ​

  • Type: integer, nullable
  • Constraints: minimum 0; format uint64

Maximum total bytes of regular files allowed in a single materialized module tree. None (the default) disables the limit. Same enforcement point as max_materialized_files.

Search commands, configuration, and guides.