Cylc Rose

Rose Suite Configurations

This plugin is activated by the existence of a Rose Suite Configuration file (called rose-suite.conf) in the workflow definition directory which allows you to:

  • Set template variables used in the workflow definition.

  • Configure files to be installed via cylc install.

  • Define environment variables for the Cylc scheduler.

The following Cylc commands will read Rose Suite Configurations:

  • cylc install

  • cylc validate

  • cylc graph

  • cylc list

  • cylc config


Cylc Rose allows cylc install to replace the rose suite-run command (present in Rose versions 2019.01 and earlier).

Configuration File


Although we now refer to Cylc workflows (rather than suites) we continue to refer to the rose-suite.conf file as a Rose Suite Configuration.

A fuller description of Rose Suite Configuration is available here.

The following sections are permitted in the rose-suite.conf files:

config item


opts=A B C

A space limited list of optional configs.


Variables which the cylc-rose plugin will export to the environment.

[template variables]

Variables which can be used by Jinja2 or Empy in the workflow definition.


A file from one or more sources to be installed.


For compatibility with Cylc 7, sections [suite.rc:empy] and [suite.rc:jinja2] will be processed, but are deprecated and provided for ease of porting Cylc 7 workflows.

Special Variables

The Cylc Rose plugin provides two environment/template variables to the Cylc scheduler:


Cylc commands (such as cylc install, cylc validate and cylc play) will provide the name of the host on which the command is run.

If the workflow is installed the value of ROSE_ORIG_HOST will be set in opt/rose-suite-cylc-install.conf and used by future commands e.g. cylc play.

Using cylc install should produce a more consistent value for ROSE_ORIG_HOST; running Cylc commands on non-installed workflows may produce inconsistent values because the host is identified each time you run a command.


When running Cylc commands such as cylc install, cylc play and cylc validate the plugin provides the version number of your installed Rose Version in workflow scheduler’s environment.

Deprecated since version 8.0.0: Setting [env]ROSE_VERSION in rose-suite.conf. With Cylc 7 / Rose2019 users could set ROSE_VERSION for their suites. This is no longer possible, and if set in your ROSE_VERSION in your suite configuration it will be ignored.


Deprecated since version 8.0.0: CYLC_VERSION will be removed from your configuration by the Cylc-Rose plugin, as it is now set by Cylc.

Additional CLI options

You can use command line options to set or override any setting you could put in a rose-suite.conf file: If you have Cylc Rose installed see cylc install --help.

Cylc Install Optional Config

If Cylc-Rose is installed, using cylc install with a workflow containing a Rose Suite Configuration will write a record of command line options set in $CYLC_RUN_DIR/workflow_name/opt/rose-suite-cylc-install.conf.


For a workflow with the following definitions in the source directory:


[template variables]


    initial cycle point = 2020
        R1 = Hello_{{ NAME }}

    [[Hello_{{ NAME }}]]
        script = True

If you then ran

cylc install

Your final workflow would have the variable NAME inserted:

- Before processing
+ After processing

-           R1 = Hello_{{ NAME }}
+           R1 = Hello_Mars

-       [[Hello_{{ NAME }}]]
+       [[Hello_Mars]]

Rose Stem

Cylc Rose provides a Rose Stem command, if FCM is installed on your system. At Cylc 8 Rose Stem is a wrapper to cylc install rather than rose suite-run.

Rose Stem is a wrapper around the cylc install command which provides some additional Jinja2 variables.

Cylc 8 stores variables set by rose and rose-stem in the optional configuration file ~/cylc-run/my_workflow/opt/rose-suite-cylc-install.conf.


To reinstall a rose stem suite use cylc reinstall. Cylc can get any options you do not change from the rose-suite-cylc-install.conf` file. Using rose stem a second time will attempt install a new copy of your rose stem suite.