# Help with understanding cylc documentation **URL:** \ **Category:** Cylc Support\ **Created:** [April 28, 2026, 9:11pm UTC](https://cylc.discourse.group/t/help-with-understanding-cylc-documentation/1312 "2026-04-28T21:11:05Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![bpabla50](https://avatars.discourse-cdn.com/v4/letter/b/b9bd4f/32.png) [@bpabla50](https://cylc.discourse.group/u/bpabla50)\ **Post date:** [April 28, 2026, 9:11pm UTC](https://cylc.discourse.group/t/help-with-understanding-cylc-documentation/1312/1 "2026-04-28T21:11:05Z")
I must admit that I have not read cylc documentation from start, but from time to time I consult pages, what I need for cylc8. My confusion is that, if I look at given page of documentation/examples, I don’t know, which one is cylc reserved keyword, and which one is user defined. Is the variable define on left of equal sign is reserved keyword or user defined. Same goes to string defined right to equal sign. What possible names are allowed for [??] in flow.cylc. Same goes for [[??]], [[[???]]]. Do we have template of flow.cylc, which gives all possible names for [??], [[??]]. All reserved keywords for any level of bracket. I find info are scattered here and there, but for new user, it is hard to put together. Is there any colour code convention in documentation to differentiate between cylc reserved keywords versus user defined strings. I am trying to write flow.cylc, which uses family to group various tasks. I want to define only once say in “root” family some parameters like: mach = xyz; memory = 2G, time=10min, jobname etc. Job scheduler is PBS. [scheduler] [task parameters] …I want to know, what possible names are allowed on left. It did not like MY\_\*, my variable num = 1..6 allow implicit tasks = True MY\_DEFAULT\_PATH = /space/hall8/sitestore/eccc/aq/r1/bap001/cylc\_viapixi/ex6\_familycontaine ---
**Author:** ![hilary.j.oliver](https://yyz2.discourse-cdn.com/free1/user_avatar/cylc.discourse.group/hilary.j.oliver/32/4_2.png) [@hilary.j.oliver](https://cylc.discourse.group/u/hilary.j.oliver)\ **Post date:** [April 28, 2026, 11:57pm UTC](https://cylc.discourse.group/t/help-with-understanding-cylc-documentation/1312/2 "2026-04-28T23:57:25Z")
Hi @bpabla50 Workflow config items are documented in [Reference → Configuration → Workflow Configuration](https://cylc.github.io/cylc-doc/stable/html/reference/config/workflow.html) Global config items are documented in [Reference → Configuration → Global Configuration](https://cylc.github.io/cylc-doc/stable/html/reference/config/global.html) You can also use the `cylc config` command with the `--defaults` option, to see a list all allowed pre-defined config items. ```bash # Print all defined and all allowed pre-defined global config items $ cylc config --defaults # Print all defined and all allowed pre-defined workflow config items $ cylc config --defaults ``` For example, for the following minimal valid `flow.cylc`: ```auto [scheduling] [[graph]] R1 = foo [runtime] [[foo]] ``` The resulting workflow configuration with _all allowed pre-defined items_ (scrollable!): ```ini [meta] description = title = URL = [scheduler] UTC mode = False allow implicit tasks = False install = cycle point format = cycle point num expanded year digits = 0 cycle point time zone = Z [[experimental]] all = False expire triggers = False [[main loop]] [[events]] handlers = handler events = mail events = startup handlers = shutdown handlers = abort handlers = workflow timeout = workflow timeout handlers = abort on workflow timeout = stall handlers = stall timeout = stall timeout handlers = abort on stall timeout = inactivity timeout = inactivity timeout handlers = abort on inactivity timeout = restart timeout = expected task failures = [[mail]] footer = to = from = task event batch interval = [task parameters] [[templates]] [scheduling] initial cycle point = 1 final cycle point = 1 initial cycle point constraints = final cycle point constraints = hold after cycle point = stop after cycle point = cycling mode = integer runahead limit = P4 sequential xtriggers = False [[queues]] [[[default]]] limit = 100 members = [[special tasks]] clock-trigger = external-trigger = clock-expire = sequential = [[xtriggers]] [[graph]] R1 = foo [runtime] [[root]] completion = platform = inherit = script = init-script = env-script = err-script = exit-script = pre-script = post-script = work sub-directory = execution polling intervals = execution retry delays = execution time limit = submission polling intervals = submission retry delays = run mode = live [[[meta]]] title = description = URL = [[[skip]]] outputs = disable task event handlers = True [[[simulation]]] default run length = PT10S speedup factor = time limit buffer = PT30S fail cycle points = fail try 1 only = True disable task event handlers = True [[[environment filter]]] include = exclude = [[[job]]] batch system = batch submit command template = [[[remote]]] host = owner = retrieve job logs = retrieve job logs max size = retrieve job logs retry delays = [[[events]]] handlers = handler events = handler retry delays = mail events = execution timeout = submission timeout = expired handlers = late offset = late handlers = submitted handlers = started handlers = succeeded handlers = failed handlers = submission failed handlers = warning handlers = critical handlers = retry handlers = submission retry handlers = execution timeout handlers = submission timeout handlers = custom handlers = [[[mail]]] from = to = [[[workflow state polling]]] interval = max-polls = message = alt-cylc-run-dir = verbose mode = [[[environment]]] [[[directives]]] [[[outputs]]] [[[parameter environment templates]]] [[foo]] completion = succeeded platform = inherit = script = init-script = env-script = err-script = exit-script = pre-script = post-script = work sub-directory = execution polling intervals = execution retry delays = execution time limit = submission polling intervals = submission retry delays = run mode = live [[[meta]]] title = description = URL = [[[skip]]] outputs = disable task event handlers = True [[[simulation]]] default run length = PT10S speedup factor = time limit buffer = PT30S fail cycle points = fail try 1 only = True disable task event handlers = True [[[environment filter]]] include = exclude = [[[job]]] batch system = batch submit command template = [[[remote]]] host = owner = retrieve job logs = retrieve job logs max size = retrieve job logs retry delays = [[[events]]] handlers = handler events = handler retry delays = mail events = execution timeout = submission timeout = expired handlers = late offset = late handlers = submitted handlers = started handlers = succeeded handlers = failed handlers = submission failed handlers = warning handlers = critical handlers = retry handlers = submission retry handlers = execution timeout handlers = submission timeout handlers = custom handlers = [[[mail]]] from = to = [[[workflow state polling]]] interval = max-polls = message = alt-cylc-run-dir = verbose mode = [[[environment]]] [[[directives]]] [[[outputs]]] [[[parameter environment templates]]] ``` Note that empty sections above (and the already user-defined `[runtime]foo` in this example) indicate space for user-defined config items. These are only used where Cylc could obviously not pre-define them, such as `[runtime][][environment]` sections for user-defined job environment variables, and `[runtime][][outputs]` for user-defined task outputs, and `[runtime][][directives]` for arbitrary job runner directives (in principle Cylc could predine all valid directives for PBS, Slurm, etc., but that’s barely feasible in practice so we allow any directive names and expect you to only use those that are valid to your job runner). ---
**Author:** ![bpabla50](https://avatars.discourse-cdn.com/v4/letter/b/b9bd4f/32.png) [@bpabla50](https://cylc.discourse.group/u/bpabla50)\ **Post date:** [April 30, 2026, 6:35pm UTC](https://cylc.discourse.group/t/help-with-understanding-cylc-documentation/1312/3 "2026-04-30T18:35:20Z")
Thanks @hilary.j.oliver