The .cylc File Format

Cylc global and workflow configuration files are written in a nested INI-based format.

Syntax

Comments

Comments follow a # character.

Settings

Configuration items (settings) are written as key = value pairs, 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]]]

Indentation

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
"""

Include-files

flow.cylc fragments can be included verbatim with the %include directive. Include-files can be included multiple times, and even nested. Include-file paths should relative to the flow.cylc location:

%include "inc/site-a.cylc"

Jinja2’s template inclusion mechanism can be used with Cylc too.

Shorthand

In the documentation, we often use a compact single-line notation to refer to nested config items, where we drop the additional brackets at each level:

[section]

An entire section.

[section]setting

A setting within a section.

[section]setting=value

The value of a setting within a section.

[section][sub section]another setting

A setting within a sub-section.

This is purely for making it easier to refer to items; they cannot be written this way in the flow.cylc file.

# This:
#   [runtime][task-a][environment]FOO = foo
# Means:
[runtime]
    [[task-a]]
        [[[environment]]]
            FOO = foo