Configuration ​

Sprocket has a number of facilities for including, excluding, initializing, and resolving configuration.

Options ​

Every option in sprocket.toml is listed in the configuration reference, which is generated from Sprocket's own schema and gives the type, default, and description of each key. You can also print that schema yourself with sprocket config schema to get autocompletion and inline documentation in editors that support JSON schema for TOML, or read the Config struct in the source code.

Load order ​

Configuration can be provided to Sprocket through a variety of different channels (listed in order of the relative priority during loading).

• Command-line arguments. A configuration file can be specified at runtime on the command line using the --config argument.
• Environment variables. The path to a configuration file can be specified via the SPROCKET_CONFIG environment variable.
• Current working directory. Sprocket will attempt to load a sprocket.toml within the current working directory when the sprocket command runs.
• Executable-adjacent configuration. Sprocket will attempt to load a sprocket.toml located in the same directory as the sprocket executable. This is useful for bundled or deployed installations where a default configuration should travel with the binary.
• System-wide configuration locations. See the section below on how to use the system-wide configuration directory.

System-wide configuration locations ​

Resolving effective configuration ​

To determine how your configuration resolves in your current environment, you can use the sprocket config resolve to print it. The default configuration can be written out using the sprocket config init command.

Incremental application ​

Configuration values are incrementally applied, meaning that configuration values loaded later in the configuration loading process take priority over those loaded earlier. This means that:

• Single-value configuration settings are overwritten, and
• Lists of configuration values are appended.

As an example, consider specifying the following configuration file in your current working directory.

[format]
indentation_size = 4

[check]
except = ['ContainerUri']

And the following in a configuration file pointed to by the $SPROCKET_CONFIG environment variable.

[format]
indentation_size = 2

[check]
except = ['SnakeCase']

The configuration provided by $SPROCKET_CONFIG would take priority over the configuration in your current working directory (as defined in the list at the top of this guide), leaving you with the following final configuration.

[format]
# Because this is a single-value configuration setting, the value provided in
# your current working directory is overwritten by the one provided in
# `$SPROCKET_CONFIG`.
indentation_size = 2

[check]
# Because this is a list configuration setting, the values provided in
# `$SPROCKET_CONFIG` are appended to those provided in your current working
# directory.
except = ['ContainerUri', 'SnakeCase']

Skipping configuration search ​

Configuration resolution can be disabled by passing the --skip-config-search option on the command line. This will disable the searching for and loading of configuration files. The only configuration loaded will be that (if) specified by the --config command line argument.

Global options ​

Sprocket provides a few options that apply across all subcommands.

Ignoring WDL files and directories ​

Sprocket is able to parse .sprocketignore files found in the current working directory, its parent directories, and its child directories. The syntax and semantics of these "ignorefiles" are similar to .gitignore files, except the focus is on the discovery/inclusion of WDL files.

Each line of the ignorefile represents a path or glob pattern that should be ignored by Sprocket invocations. Ignorefiles apply their path filters to the directory they are in and any child directories, but not to their parent directory.

This is particularly useful if you have any WDL files that should not be analyzed, checked, or documented. Note that ignorefiles only impact searching for files with the extension .wdl.

Overriding task CPU and memory requirements ​

A task may specify a CPU or memory requirement that exceeds the maximum of that resource known to Sprocket. When this occurs, Sprocket will error saying that the task's resource requirement exceeds the known maximum.

Sprocket can be configured to instead substitute the maximum known resource as the requirement; please note that this does not guarantee that the task will succeed, only that Sprocket will execute the task instead of reporting an error.

Use the following settings to change Sprocket's resource limit behavior:

[run.task]
cpu_limit_behavior = "try_with_max"
memory_limit_behavior = "try_with_max"

Task retries are configured with run.task.retries (and server.engine.task.retries for the server); see retries for the accepted values and how they interact with a task's maxRetries.

Check/lint configuration ​

See the check/lint page.

Evaluation cache capacities ​

Sprocket bounds several in-memory least-recently-used (LRU) caches. Every capacity defaults to 1000 and must be greater than zero.

For example:

[run]
digest_cache_capacity = 2000
choice_cache_capacity = 2000
regex_cache_capacity = 2000

[run.http]
response_cache_capacity = 2000

These settings do not affect the persistent HTTP download cache or Sprocket's call cache.

sprocket dev doc configuration ​

See the doc page.

Module configuration ​

See the sprocket dev module page.