Getting Started


If Rose is not installed at your site, please refer to Rose: Installation for detail.

Before using Rose, it is desirable to configure a few things for yourself. If you have just installed Rose at your site, you should configure it to meet your site requirements.

The format of both the user and site configuration file is documented in user/site config.

Rose combines the settings in the site configuration and the user configuration at run time. You can view the actual setting by issuing the command:

rose config

You can configure Rose by creating and editing your user configuration file at ~/.metomi/rose.conf. E.g.:

mkdir -p ~/.metomi
${EDITOR:-vi} ~/.metomi/rose.conf

Rose should work out of the box if it is configured correctly at your site.

Text Editor

The default external text editor used by GUIs is gedit. The default external text editor used by CLI commands is the value of the VISUAL or EDITOR environment variable, or vi if neither environment variable is set.

You should change the [external] geditor (the external text editor used by GUIs) and the [external] editor (the external text editor used by CLI commands) settings in ~/.metomi/rose.conf if you do not want to use the default.

For emacs and most text editors, you can do something like:


For any text editor command that normally forks and detaches from the shell it is started it, you should use an option to ensure that the text editor runs in the foreground to allow Rose to wait for the edit session to finish. E.g. for gvim, you will do:

editor=gvim -f
geditor=gvim -f

Editor Syntax Highlighting

There are gedit, kate, vim, and emacs plugins for syntax highlighting of Rose configuration files, located at:

  • $ROSE_HOME/etc/rose-conf.lang
  • $ROSE_HOME/etc/rose-conf.xml
  • $ROSE_HOME/etc/rose-conf.vim
  • $ROSE_HOME/etc/rose-conf-mode.el

$ROSE_HOME should be replaced with the path to the root directory of your local Rose installation, which you can locate by running rose --version. See the files themselves for setup notes.

Bash Auto-Completion

There is a Rose bash completion script that you can source to enhance the Rose command line interface within an interactive Bash shell.

The script allows you to tab-complete Rose commands, options, and arguments.

You can find the file at $ROSE_HOME/etc/rose-bash-completion. The file contains the instructions for using it.

As with the Editor Syntax Highlighting above, you can locate your $ROSE_HOME by running rose --version.

Configuring cylc

See cylc User Guide for detail.

You may want to set up cylc-specific text editor plugins - see the cylc User Guide for details.

DO NOT modify the [hosts] → HOST → run directory and [hosts] → HOST → work directory settings, since they are incompatible with Rose. Equivalent functionalities are provided by the [rose-suite-run]root-dir* settings in the Rose site/user configuration.