The .cylc File Format
Cylc global and workflow configuration files are written in a nested INI-based format.
Comments follow a
Configuration items (settings) are written as
key = valuepairs, and can be contained within sections. Setting names (the keys) may contain spaces.
- String Values
Quoting single-line string values is optional:
[animals] cat = dusty dog = "fido" # or single quotes: 'fido'
Multiline string values must be triple-quoted:
[song] lyrics = """ # (or triple single-quotes: '''value''') No stop signs Speed limit Nobody's gonna slow me down """
- List Values
List values are comma-separated:
animals = dusty, fido, cujo
- Boolean Values
Booleans are capitalized:
ice cream is good = True # or False
- Sections and Sub-sections
Settings have a level-dependent number of square brackets:
[section] [[sub-section]] [[[sub-sub-section]]]
It is advisable to indent sections and subsections, for clarity. However, Cylc ignores indentation, so this:
[section] a = A [[sub-section]] b = B b = C # WARNING: this is still in sub-section!
is equivalent to this:
[section] a = A [[sub-section]] b = C
- Duplicate Sections and Items
Duplicate sections get merged into one. Duplicate settings overwrite previously defined values. So this:
[animals] cat = fluffy [animals] dog = fido cat = dusty
is equivalent to this:
[animals] cat = dusty dog = fido
The only exception to this rule is graph strings, which get merged. So these graph strings:
R1 = "foo => bar" R1 = "foo => baz"
merge to this:
R1 = "foo => bar & baz"
- Continuation lines
If necessary, you can continue on the next line after a backslash character:
verse = "the quick \ brown fox"
However, backslash line continuation is fragile (trailing invisible whitespace breaks it). Long graph strings strings should be split on graph symbols instead:
R1 = """ (foo & bar ) | baz => qux """ # Equivalent to: R1 = """ (foo & bar ) | baz => qux """
flow.cylcfragments can be included verbatim with the
%includedirective. Include-files can be included multiple times, and even nested. Include-file paths should relative to the
Jinja2’s template inclusion mechanism can be used with Cylc too.
We often use a compact single-line notation to refer to nested config items:
An entire section.
A setting within a section.
The value of a setting within a section.
A setting within a sub-section.
In the file, however, section headings need additional brackets at each level.
# This: # [runtime][task-a][environment]FOO = foo # Means: [runtime] [[task-a]] [[[environment]]] FOO = foo