The .cylc File Format

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



Comments follow a # character.


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:

   cat = dusty
   dog = "fido"  # or single quotes: 'fido'

Multiline string values must be triple-quoted:

   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:


It is advisable to indent sections and subsections, for clarity. However, Cylc ignores indentation, so this:

   a = A
      b = B
   b = C  # WARNING: this is still in sub-section!

is equivalent to this:

   a = A
      b = C
Duplicate Sections and Items

Duplicate sections get merged into one. Duplicate settings overwrite previously defined values. So this:

  cat = fluffy
  dog = fido
  cat = dusty

is equivalent to this:

  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 =>
# Equivalent to:
R1 = """
     (foo & bar ) | baz => qux

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.


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:
            FOO = foo