Command Reference§

Rose Commands§

Environment variables§

Usage: rose app-run [OPTIONS] [--] [COMMAND ...]

Run an application according to its configuration.

May run a builtin application (if the mode setting in the configuration specifies the name of a builtin application) or a command.

Determine the command to run in this order:

If COMMAND is specified, invoke the command.
If the --command-key=KEY option is defined, invoke the command specified in [command]KEY.
If the ROSE_APP_COMMAND_KEY environment variable is set, the command specified in the [command]KEY setting in the application configuration whose KEY matches it is used.
If the environment variable ROSE_TASK_NAME is defined and a setting in the [command] section has a key matching the value of the environment variable, then the value of the setting is used as the command.
Invoke the command specified in [command]default.

--app-mode=MODE       Run a command or builtin application identified by 
                      `MODE`. The default `MODE` is `command`.
-c KEY, --command-key=KEY
                      Run the command in [command]KEY instead of 
                      [command]default.
-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-D [SECTION]KEY=VALUE, --define=[SECTION]KEY=VALUE
                      Each of these overrides the `[SECTION]KEY` setting 
                      with a given `VALUE`.

                      Can be used to disable a setting using the 
                      syntax`--define=[SECTION]!KEY` or even 
                      `--define=[!SECTION]`.
-h, --help            show this help message and exit
-i, --install-only    Install files only, don't run the command.
-N, --new             Remove all items in `$PWD` before doing anything.

                      This option only works with the `--config=DIR` option 
                      and if `$PWD` is not `DIR`.
--no-overwrite        Do not overwrite existing files.
-O KEY, --opt-conf-key=KEY
                      Each of these switches on an optional configuration 
                      identified by `KEY`.

                      The configurations are applied first-to-last.

                      The `(KEY)` syntax denotes an optional configuration 
                      that can be missing. Otherwise, the optional  
                      configuration must exist.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

optional ROSE_APP_COMMAND_KEY: Switch to a particular command specified in [command]KEY.
optional ROSE_APP_MODE: Specifies a builtin application to run.
optional ROSE_APP_OPT_CONF_KEYS: Each KEY in this space delimited list switches on an optional configuration. The configurations are applied first-to-last.
optional ROSE_FILE_INSTALL_ROOT: If specified, change to the specified directory to install files.

Environment variables§

Usage: rose app-upgrade [OPTIONS] [VERSION]

Upgrade an application configuration using metadata upgrade macros.

Alternatively, show the available upgrade/downgrade versions:

= indicates the current version.
* indicates the default version to change to.

If an application contains optional configurations, loop through each one, combine with the main, upgrade it, and re-create it as a diff vs the upgraded main configuration.

-a, --all-versions    Use all tagged versions.
-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-d, --downgrade       Downgrade the version instead of upgrade.
-h, --help            show this help message and exit
-M PATH, --meta-path=PATH
                      Prepend items to the metadata search path.

                      This option can be used repeatedly to load multiple 
                      paths.
-y, --non-interactive, --yes
                      Switch off interactive prompting.
-O DIR, --output=DIR  Specify the name of the output directory.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

VERSION: A version to change to. If no version is specified, show available versions. If --non-interactive is used, use the latest version available. If --non-interactive and --downgrade are used, use the earliest version available.

optional ROSE_META_PATH: Prepend $ROSE_META_PATH to the metadata search path.

Options§

rose check-software [OPTIONS]

Check software dependencies for the rose documentation builder.

--doc   Only check dependencies for the documentation builder.
--rst   Output dependencies as text in rst format.

Environment variables§

Usage: rose config [options]

Parse and print rose configuration files.

With no option and no argument, print the rose site + user configuration.

# Print the value of OPTION in SECTION.
rose config SECTION OPTION

# Print the value of OPTION in SECTION in FILE.
rose config --file=FILE SECTION OPTION

# Print the value of OPTION in SECTION if exists, or VALUE otherwise.
rose config --default=VALUE SECTION OPTION

# Print the OPTION=VALUE pairs in SECTION.
rose config SECTION

# Print the value of a top level OPTION.
rose config OPTION

# Print the OPTION keys in SECTION.
rose config --keys SECTION

# Print the SECTION keys.
rose config --keys

# Exit with 0 if OPTION exists in SECTION, or 1 otherwise.
rose config -q SECTION OPTION

# Exit with 0 if SECTION exists, or 1 otherwise.
rose config -q SECTION

# Combine the configurations in FILE1 and FILE2, and dump the result.
rose config --file=FILE1 --file=FILE2

# Print the value of OPTION in SECTION of the metadata associated with
# the specified config FILE
rose config --file=FILE --meta SECTION OPTION

# Print the value of a specified metadata KEY
rose config --meta-key=KEY

--default=VALUE       Specify a default value
-E, --env-var-process
                      Process environment variable substitution.

                      Only works when returning a string value.
-f FILE, --file=FILE  Specify the configuration file(s).

                      If none specified, read from `$THIS/../etc/rose.conf` 
                      and `$HOME/.metomi/rose.conf` (where `$THIS` is the 
                      location of this command).
-h, --help            show this help message and exit
-k, --keys            Only print the `SECTION` keys in the configuration 
                      file or the `OPTION` keys in a `SECTION`.
--meta                Operate on a config file's metadata.
--meta-key=KEY        Prints the value of a specified metadata flag `KEY`.

                      Cannot be used in conjunction with `--file=FILE`.
--no-opts             Do not load optional configurations.
--print-conf          Prints the result as a Rose configuration file 
                      snippet.

                      This allows the output to be concatenated into another
                       Rose configuration file.
-i, --print-ignored   Print ignored settings.

                      E.G. !OPTION=VALUE. These are not output by default.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Exit with 0 if the specified `SECTION` and/or `OPTION`
                       exist in the configuration, or 1 otherwise.
-v, --verbose         Increment verbosity.

optional ROSE_META_PATH: Prepend $ROSE_META_PATH to the metadata search path.

Configuration§

Usage: rose config-diff [OPTIONS] FILE1 FILE2 [-- [DIFF_OPTIONS] [DIFF_ARGUMENTS]]

Display the metadata-annotated difference between two Rose config files.

# Display the metadata-annotated diff between two Rose config files.
rose config-diff FILE1 FILE2

# Display the metadata-annotated diff between two Rose config dirs.
rose config-diff DIR1 DIR2

# Display the diff, ignoring particular setting patterns
rose config-diff --ignore=namelist:foo FILE1 FILE2

# Display the diff with a particular diff tool
rose config-diff --diff-tool=kdiff3 FILE1 FILE2

# Display the diff with some diff tool specific options/arguments
rose config-diff FILE1 FILE2 -- [DIFF_OPTIONS] [DIFF_ARGUMENTS]

--diff-tool=DIFF_TOOL
                      Specify an alternate diff tool.

                      E.G: diffuse, vimdiff or kompare.
-g, --graphical       Run in graphical mode (X windows, etc.)
-h, --help            show this help message and exit
-i PATTERN, --ignore=PATTERN
                      Ignore setting ids that contain (regex) PATTERN.

                      Can be specified more than once. `PATTERN` may also 
                      bea key used in site or user configuration which 
                      expands toa list of patterns. See `CONFIGURATION` 
                      below.
-M PATH, --meta-path=PATH
                      Prepend items to the metadata search path.

                      This option can be used repeatedly to load multiple 
                      paths.
--opt-conf-key-1=KEY  Switch on an optional configuration file the first 
                      item in a comparison.
--opt-conf-key-2=KEY  Switch on an optional configuration file the first 
                      item in a comparison.
-p PROPERTIES, --properties=PROPERTIES
                      Filter metadata properties.

                      This should be a comma separated list of metadata 
                      options, such as title,description,help.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

optional ROSE_META_PATH: Prepend $ROSE_META_PATH to the metadata search path.

PATH1, PATH2: Two Rose configuration files or directories to compare. If the path is a directory, look underneath for a Rose configuration file. ‘-’ for PATH1 or PATH2 denotes read in from standard input.
--: Options and arguments after a -- token are passed directly to the diff tool.

[external]diff-tool, [external]gdiff-tool

You can override the default non-graphical and graphical diff tools by setting e.g:

[external]
diff-tool=diff3
gdiff-tool=kompare

in your site or user Rose configuration (rose.conf).

[rose-config-diff]properties, [rose-config-diff]ignore{…}

You can override the default metadata properties to display by setting e.g:

[rose-config-diff]
properties=title,ns,description,help

in your site or user Rose configuration (rose.conf). You can also set shorthand ignore patterns by setting e.g.:

[rose-config-diff]
ignore{foo}=namelist:bar,namelist:baz

in the same location. This will allow you to run:

rose config-diff --ignore=foo ...

instead of:

rose config-diff --ignore=namelist:bar --ignore=namelist:baz ...

Options§

Usage: rose config-dump [options]

Re-dump Rose configuration files in the common format.

Load and dump "rose-*.conf" files in place. Apply format-specific pretty-printing.

By default, it recursively loads and dumps all rose-*.conf files in the current working directory.

rose config-dump
rose config-dump -C /path/to/conf/dir
rose config-dump -f /path/to/file1 -f /path/to/file2

-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-f FILE, --file=FILE  Specify the configuration file(s).

                      If none specified, read from `$THIS/../etc/rose.conf` 
                      and `$HOME/.metomi/rose.conf` (where `$THIS` is the 
                      location of this command).
-h, --help            show this help message and exit
--no-pretty           Switch off format-specific prettyprinting.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Print format§

# 1. Print date time point
# 1.1 Current date time with an optional offset
rose date [--offset=OFFSET]
rose date now [--offset=OFFSET]
rose date ref [--offset=OFFSET]
# 1.2 Task cycle date time with an optional offset
#     Assume: export ROSE_TASK_CYCLE_TIME=20371225T000000Z
rose date -c [--offset=OFFSET]
rose date -c ref [--offset=OFFSET]
# 1.3 A specific date time with an optional offset
rose date 20380119T031407Z [--offset=OFFSET]

# 2. Print duration
# 2.1 Between now (+ OFFSET1) and a future date time (+ OFFSET2)
rose date now [--offset1=OFFSET1] 20380119T031407Z [--offset2=OFFSET2]
# 2.2 Between a date time in the past and now
rose date 19700101T000000Z now
# 2.3 Between task cycle time (+ OFFSET1) and a future date time
#     Assume: export ROSE_TASK_CYCLE_TIME=20371225T000000Z
rose date -c ref [--offset1=OFFSET1] 20380119T031407Z
# 2.4 Between task cycle time and now (+ OFFSET2)
#     Assume: export ROSE_TASK_CYCLE_TIME=20371225T000000Z
rose date -c ref now [--offset2=OFFSET2]
# 2.5 Between a date time in the past and the task cycle date time
#     Assume: export ROSE_TASK_CYCLE_TIME=20371225T000000Z
rose date -c 19700101T000000Z ref
# 2.6 Between 2 specific date times
rose date 19700101T000000Z 20380119T031407Z

# 3.  Convert ISO8601 duration
# 3.1 Into the total number of hours (H), minutes (M) or seconds (S)
#     it represents, preceed negative durations with a double backslash
#     (e.g. \-PT1H)
rose date --as-total=s PT1H

Parse and print 1. a date time point or 2. a duration.

With 0 or 1 argument. Print the current or the specified date time point with an optional offset.
With 2 arguments. Print the duration between the 2 arguments.

--as-total=TIME_FORMAT
    Used to express an ISO8601 duration in the specified time format,
    hours `H`, minutes `M` or seconds `S`.
--calendar=gregorian|360day|365day|366day
    Specify the calendar mode. See `CALENDAR MODE` below.
--offset1=OFFSET, --offset=OFFSET, -s OFFSET, -1 OFFSET
    Specify 1 or more offsets to add to argument 1 or the current time.
    See `OFFSET FORMAT` below.
--offset2=OFFSET, -2 OFFSET
    Specify 1 or more offsets to add to argument 2.
    See `OFFSET FORMAT` below.
--parse-format=FORMAT, -p FORMAT
    Specify a format for parsing `DATE-TIME`. See `PARSE FORMAT` below.
--print-format=FORMAT, --format=FORMAT, -f FORMAT
    Specify a format for printing the result. See `PRINT FORMAT` below.
--use-task-cycle-time, -c
    Use the value of the `ROSE_TASK_CYCLE_TIME` environment variable as
    the reference time instead of the current time.
--utc, -u
    Assume date time in UTC instead of local or other time zones.

The calendar mode is determined (in order) by:

The --calendar=MODE option.
The ROSE_CYCLING_MODE or ISODATETIMECALENDAR environment variable.
(ROSE_CYCLING_MODE over-rides if both set)
Default to “gregorian”.

In both cases the ROSE.* variable will over-ride the ISODATETIME variable if both are set to ensure legacy behaviour for Rose.

ROSE_CYCLING_MODE/ISODATETIMECALENDAR=gregorian|360day|365day|366day: Specify the calendar mode.
ROSE_TASK_CYCLE_TIME/ISODATETIMEREF: Specify the current cycle time of a task in a suite. If the --use-task-cycle-time option is set, the value of this environment variable is used by the command as the reference time instead of the current time.

OFFSET must follow the ISO 8601 duration representations such as PnW or PnYnMnDTnHnMnS - P followed by a series of nU where U is the unit (Y, M, D, H, M, S) and n is a positive integer, where T delimits the date series from the time series if any time units are used. n may also have a decimal (e.g. PT5.5M) part for a unit provided no smaller units are supplied. It is not necessary to specify zero values for units. If OFFSET is negative, prefix a -. For example:

P6D - 6 day offset
PT6H - 6 hour offset
PT1M - 1 minute offset
-PT1M - (negative) 1 minute offset
P3M - 3 month offset
P2W - 2 week offset (note no other units may be combined with weeks)
P2DT5.5H - 2 day, 5.5 hour offset
-P2YT4S - (negative) 2 year, 4 second offset

The format for parsing a date time point should be compatible with the POSIX strptime template format (see the strptime command help), with the following subset supported across all date/time ranges:

%F, %H, %M, %S, %Y, %d, %j, %m, %s, %z

If not specified, the system will attempt to parse DATE-TIME using the following formats:

ctime: %a %b %d %H:%M:%S %Y
Unix date: %a %b %d %H:%M:%S %Z %Y
Basic ISO8601: %Y-%m-%dT%H:%M:%S, %Y%m%dT%H%M%S
Cylc 5: %Y%m%d%H (deprecated)

If none of these match, the date time point will be parsed according to the full ISO 8601 date/time standard.

For printing a date time point, the print format will default to the same format as the parse format. Also supports the isodatetime library dump syntax for these operations which follows ISO 8601 example syntax - for example:

CCYY-MM-DDThh:mm:ss -> 1955-11-05T09:28:00,
CCYY -> 1955,
CCYY-DDD -> 1955-309,
CCYY-Www-D -> 1955-W44-6.

Usage of this ISO 8601-like syntax should be as ISO 8601-compliant as possible.

Note that specifying an explicit timezone in this format (e.g. CCYY-MM-DDThh:mm:ss+0100 or CCYYDDDThhmmZ will automatically adapt the date/time to that timezone i.e. apply the correct hour/minute UTC offset.

For printing a duration, the following can be used in format statements:

y: years
m: months
d: days
h: hours
M: minutes
s: seconds

For example, for a duration P57DT12H - y,m,d,h -> 0,0,57,12

Options§

Usage: rose env-cat [OPTIONS] [FILE ...]

Substitute environment variables in input files and print.

If no argument is specified, read from STDIN. One FILE argument may be -, which means read from STDIN.

In match-mode=default, the command will look for $NAME or ${NAME} syntax and substitute them with the value of the environment variable NAME. A backslash in front of the syntax, e.g. \$NAME or \${NAME} will escape the substitution.

In match-mode=brace, the command will look for ${NAME} syntax only.

rose env-cat [OPTIONS] [FILE ...]

-h, --help            show this help message and exit
-m MODE, --match-mode=MODE
                      Specify the match mode.

                      can be `brace` or `default`.
-o FILE, --output=FILE
                      Specify an output file.

                      If no output file is specified or if `FILE`is `-`, 
                      write output to STDOUT.
--unbound=STRING, --undef=STRING
                      Substitute unbound variables with the provided STRING.

                      The command will normally fail on unbound (or 
                      undefined) variables.

                      If this option is specified, the command will 
                      substitute an unbound variable with the value of 
                      `STRING`, (which can be an empty string), instead of 
                      failing.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Configuration§

Usage: rose host-select [OPTIONS] [GROUP/HOST ...]

Select a host from a set of groups or names by load, by free memory or by random.

Print the selected host name.

  --choice=N            Choose from any of the top N items.
  -h, --help            show this help message and exit
  --rank-method=METHOD  Specify the method for ranking hosts.

                        Can be load, fs, mem or random.
  --threshold=METHOD:METHOD-ARG:NUMBER
                        Specify a threshold for excluding hosts.

                        Each of these option specifies a numeric value of a 
                        threshold of which the hosts must either not exceed or
                         must be greater than depending on the specified 
                        method.

                        Accepts the same `METHOD` and `METHOD-ARG` (and the 
                        same defaults) as the `--rank-method=METHOD[:METHOD-
                        ARG]` option. (Obviously, the `random` method does not
                         make sense in this case.) `load` and `fs` must not 
                        exceed threshold while `mem` must be greater than 
                        threshold. A host not meeting a threshold condition 
                        will be excluded from the ranking list.
  --timeout=FLOAT       Set the timeout in seconds of SSH commands to hosts.
  --debug               Report trace back on error.
  --profile             Switch on profiling.
  -q, --quiet           Decrement verbosity.
  -v, --verbose         Increment verbosity.

RANKING METHODS IN DETAIL (--rank-method):
    `load`
        Rank by average load as reported by `uptime` divided by
        number of virtual processors.

        If `METHOD-ARG` is specified, it must be `1`, `5` or `15`.
        The default is to use the 15 minute load.
    `fs`
        Rank by % usage of a file system as reported by `df`.

        `METHOD-ARG` must be a valid file system in all the given
        hosts and host groups. The default is to use the `~`
        directory.
    `mem`
        Rank by largest amount of free memory. Uses `free -m` to
        return memory in Mb
    `random`
        No ranking is used.

The command reads its settings from the [rose-host-select] section in the Rose configuration. All settings are optional. Type rose config rose-host-select to print settings.

Valid settings are:

default = GROUP/HOST …: The default arguments to use for this command.
group{NAME} = GROUP/HOST …: Declare a named group of hosts.
method{NAME} = METHOD[:METHOD-ARG]: Declare the default ranking method for a group of hosts.
thresholds{NAME} = [METHOD[:METHOD-ARG]:]VALUE …: Declare the default threshold(s) for a group of hosts.
timeout = FLOAT: Set the timeout in seconds of SSH commands to hosts. (default=10.0)

Examples§

Internal command for obtaining information about hosts using the Python psutil module.

The names of psutil methods are passed to stdin along with any arguments as a JSON list.

    # return the virtual memory and cpu usage
    [["virtual_memory"], ["cpu_percent"]]

    # return disk usage for the filesystem mounted at "/"
    [["disk_usage", "/"]]

The input json should be preceded by 
**start**

and followed by 
**end**
 to avoid issues with user profile scripts
and stdin deadlock.

$ rose host-select-client <<'__HERE__'
> **start**
> [["virtual_memory"]]
> **end**
> __HERE__
[{"total": 17179869184, "available": 6276612096, "percent": 63.5, ...}]

Environment variables§

Usage: rose macro [OPTIONS] [MACRO_NAME ...]

List or run macros associated with a suite or application.

Macros are listed/run according to the config dir ($PWD unless --config=DIR is set):

If the config dir is an app directory (or is within an app directory) macros will be listed/run for the rose-app.conf file of that app.
Otherwise macros will be listed/run for the rose-suite.conf, rose-suite.info and (unless --suite-only is set) all rose-app.conf files.

If a configuration contains optional configurations:

For validator macros, validate the main configuration, then validate each main + optional configuration in turn.
For transform macros, transform the main configuration, then transform each main + optional configuration, recreating each optional configuration as the diff vs the transformed main.

-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-F, --fix             Prepend all internal transformer (fixer) macros tothe 
                      argument list.
-h, --help            show this help message and exit
-M PATH, --meta-path=PATH
                      Prepend items to the metadata search path.

                      This option can be used repeatedly to load multiple 
                      paths.
--no-warn=WARNING_TYPE
                      Warnings to disable.
-y, --non-interactive, --yes
                      Switch off interactive prompting.
-O DIR, --output=DIR  The location of the output directory.

                      Only meaningful if there is at least one transformer 
                      in theargument list.
--suite-only          Run only for suite level macros.
-T, --transform       Prepend all transformer macros to the argument list.
-V, --validate        Prepend all validator macros to the argument list.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

MACRO_NAME …: A list of macro names to run. If no macro names are specified and --fix, --validate are not used, list all available macros. Otherwise, run the specified macro names.

optional ROSE_META_PATH: Prepend $ROSE_META_PATH to the metadata search path.

Arguments§

Usage: rose metadata-check [OPTIONS] [ID ...]

Validate configuration metadata.

-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-h, --help            show this help message and exit
-p PROPERTY, --property=PROPERTY
                      Only check a certain property e.g. trigger.

                      This can be specified more than once.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

ID: One or more sections (configuration IDs) to check in the metadata e.g.env=FOO or namelist:bar. If specified, only this section will be checked.

Arguments§

Usage: rose metadata-gen [OPTIONS] [PROPERTY=VALUE ...]

Automatically generate metadata from an application or suite configuration. An aid for metadata development.

WARNING: May Contain Thorns.

--auto-type           Add a 'best guess' for the `type` and `length` 
                      metadata.
-C DIR, --config=DIR  Specify the configuration directory of the 
                      application.

                      If not specified, the current directory will be used.
-h, --help            show this help message and exit
-O DIR, --output=DIR  A directory to output the metadata to.

                      If not specified, output to the application or suite 
                      metadatadirectory.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

PROPERTY[=VALUE] …: One or more key=value pairs of properties to specify for every setting e.g. compulsory=true. If =VALUE is missing, the property will be set to a null string in each setting.

Diagnostics§

rose mpi-launch -f FILE
rose mpi-launch
rose mpi-launch COMMAND [ARGS ...]

Provide a portable way to launch an MPI command.

If --command-file=FILE (or -f FILE) is specified, FILE is assumed to be the command file to be submitted to the MPI launcher command.
Alternatively, if $PWD/rose-mpi-launch.rc exists and --command-file=FILE (or -f FILE) is not specified, it is assumed to be the command file to be submitted to the MPI launcher command.
In the final form, it will attempt to submit COMMAND with the MPI launcher command.

In all cases, the remaining arguments will be appended to the command line of the launcher program.

--command-file=FILE, -f FILE
    Specify a command file for the MPI launcher.
--debug
    Switch on xtrace, i.e. `set -x`.
--quiet, -q
    Decrement verbosity.
--verbose, -v
    Increment verbosity. Print command on `-v` mode. Run `printenv`,
    `ldd` on a binary executable, and `ulimit -a` on `-v -v` mode.

The command reads from the [rose-mpi-launch] section in the Rose configuration.

Valid settings are:

launcher-list=LIST

Specify a list of launcher commands.

E.g:

launcher-list=poe mpiexec

launcher-fileopts.LAUNCHER=OPTION-TEMPLATE

Specify the options to a LAUNCHER for launching with a command file. The template string should contain $ROSE_COMMAND_FILE (or ${ROSE_COMMAND_FILE}), which will be expanded to the path to the command file.

E.g.:

launcher-fileopts.mpiexec=-f $ROSE_COMMAND_FILE
launcher-fileopts.poe=-cmdfile $ROSE_COMMAND_FILE

launcher-(pre|post)opts.LAUNCHER=OPTION-TEMPLATE

Specify the options to a LAUNCHER for launching with a command. preopts are options placed after the launcher command but before COMMAND. postopts are options placed after COMMAND but before the remaining arguments.

E.g.:

launcher-preopts.mpiexec=-n $PROC

optional ROSE_LAUNCHER: Specify the launcher program.
optional ROSE_LAUNCHER_LIST: Override launcher-list setting in configuration.
optional ROSE_LAUNCHER_FILEOPTS: Override launcher-fileopts.LAUNCHER setting for the selected LAUNCHER.
optional ROSE_LAUNCHER_PREOPTS: Override launcher-preopts.LAUNCHER setting for the selected LAUNCHER.
optional ROSE_LAUNCHER_POSTOPTS: Override launcher-postopts.LAUNCHER setting for the selected LAUNCHER.
optional ROSE_LAUNCHER_ULIMIT_OPTS: Only relevant when launching with a command. Tell launcher to run rose mpi-launch --inner $@. Specify the arguments to ulimit. E.g. Setting this variable to -a -s unlimited -d unlimited -a results in ulimit -a; ulimit -s unlimited; ulimit -d unlimited; ulimit -a.
optional NPROC: Specify the number of processors to run on. Default is 1.

Return 0 on success, 1 or exit code of the launcher program on failure.

Options§

Usage: rose-namelist-dump [OPTIONS] [FILE ...]

Convert namelist files into a Rose application configuration snippet. Each argument should be the path to an empty file or a file containing Fortran namelist groups. A - can be used once in the argument list to specify the standard input. If no argument is given, it assumes the standard input is specified. Where possible, use relative path for file names, as the file names appear as-specified in the generated configuration.

--case=MODE           Output names in lower|upper case.

                      Can be `upper`, `lower` or `unchanged` (default).
-h, --help            show this help message and exit
-l, --lower           Shorthand for --case=lower.
-o FILE, --output=FILE
                      Specify the name of the output file.
-u, --upper           Shorthand for --case=upper.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Arguments§

Usage: rose resource RESOURCE_PATH

Display the path of resources in the Rose Python installation.

If the requested resource exists and is a file its path is printed.
If the requested resource exists and is a directory it is listed.

Provide no arguments to see a list of top-level resources.

# List top-level resources:
$ rose resource

# List the contents of the "syntax" directory:
$ rose resource syntax

# Locate the Rose syntax file for the Vim text editor:
$ rose resource syntax/rose-conf.vim

-h, --help     show this help message and exit
--debug        Report trace back on error.
--profile      Switch on profiling.
-q, --quiet    Decrement verbosity.
-v, --verbose  Increment verbosity.

RESOURCE_PATH

Path of the resource to extract.

Run rose resource to see the list of resources.

Options§

Usage: rose stem [options] [path]

Install a suitable suite with a specified set of source tree(s).

To run a rose-stem suite use “cylc play”.

Default values of some of these settings are suite-dependent, specified in the rose-suite.conf file.

Examples

rose stem –group=developer rose stem –source=/path/to/source –source=/other/source –group=mygroup rose stem –source=foo=/path/to/source –source=bar=fcm: bar_tr@head

Jinja2 Variables

Note that <project> refers to the FCM keyword name of the repository in upper case.

HOST_SOURCE_<project>
The complete list of source trees for a given project. Working copies in this list have their hostname prefixed, e.g. host:/path/wc.

HOST_SOURCE_<project>_BASE
The base of the project specified on the command line. This is intended to specify the location of fcm-make config files. Working copies in this list have their hostname prefixed.

RUN_NAMES
A list of groups to run in the rose-stem suite.

SOURCE_<project>
The complete list of source trees for a given project. Unlike the HOST_ variable of similar name, paths to working copies do NOT include the host name.

SOURCE_<project>_BASE
The base of the project specified on the command line. This is intended to specify the location of fcm-make config files. Unlike the HOST_ variable of similar name, paths to working copies do NOT include the host name.

SOURCE_<project>_REV
The revision of the project specified on the command line. This is intended to specify the revision of fcm-make config files.

-h, --help            show this help message and exit
-O OPT_CONF_KEYS, --opt-conf-key=OPT_CONF_KEYS
                      Use optional Rose Config Setting (If Cylc-Rose is
                      installed)
-D DEFINES, --define=DEFINES
                      Each of these overrides the `[SECTION]KEY` setting in
                      a `rose-suite.conf` file. Can be used to disable a
                      setting using the syntax `--define=[SECTION]!KEY` or
                      even `--define=[!SECTION]`.
-S ROSE_TEMPLATE_VARS, --rose-template-variable=ROSE_TEMPLATE_VARS, --define-suite=ROSE_TEMPLATE_VARS
                      As `--define`, but with an implicit `[SECTION]` for
                      workflow variables.
-n WORKFLOW_NAME, --workflow-name=WORKFLOW_NAME
                      Install into ~/cylc-run/<WORKFLOW_NAME>/runN
--symlink-dirs=SYMLINK_DIRS
                      Enter a comma-delimited list, in the form
                      'log=path/to/store, share = $HOME/some/path, ...'. Use
                      this option to override the global.cylc configuration
                      for local symlinks for the run, log, work, share and
                      share/cycle directories. Enter an empty list '' to
                      skip making localhost symlink dirs.
-r RUN_NAME, --run-name=RUN_NAME
                      Give the run a custom name instead of automatically
                      numbering it.
--no-run-name         Install the workflow directly into ~/cylc-
                      run/<workflow_name>, without an automatic run number
                      or custom run name.
--no-ping             When scanning for active instances of the workflow, do
                      not attempt to contact the schedulers to get status.
-q, --quiet           Decrease verbosity.
-v, --verbose         Increase Verbosity
--debug               Equivalent to -v -v
--no-timestamp        Don't timestamp logged messages.
--color=WHEN, --color=WHEN
                      When to use color/bold text in terminal output.
                      Options are 'never', 'auto' and 'always'.
--comms-timeout=SEC   Set a timeout for network connections to the running
                      workflow. The default is no timeout. For task
                      messaging connections see site/user config file
                      documentation.

Rose Stem Specific Options:
  -t PATH/TO/FLOW, -g PATH/TO/FLOW, --task=PATH/TO/FLOW, --group=PATH/TO/FLOW
                      Specify a group name to run. Additional groups can be
                      specified with further `--group` arguments. The suite
                      will then convert the groups into a series of tasks to
                      run.
  -s PATH/TO/FLOW, --source=PATH/TO/FLOW
                      Specify a source tree to include in a rose-stem suite.
                      The first source tree must be a working copy, as the
                      location of the suite and fcm-make config files are
                      taken from it. Further source trees can be added with
                      additional `--source` arguments. The project which is
                      associated with a given source is normally
                      automatically determined using FCM, however the
                      project can be specified as '<project-name>=<project-
                      path>'. Defaults to `.` if not specified.

Usage in suites§

Usage: rose task-env [options]

eval $(rose task-env)

Provide an environment for cycling suite task.

Print KEY=VALUE of the following to the STDOUT:

ROSE_SUITE_DIR

The path to the root directory of the running suite.

ROSE_SUITE_DIR_REL

The path to the root directory of the running suite relative to $HOME.

ROSE_SUITE_NAME

The name of the running suite.

ROSE_TASK_NAME

The name of the suite task.

ROSE_TASK_CYCLE_TIME

The cycle time of the suite task, if there is one.

ROSE_CYCLING_MODE

The cycling mode of the running suite.

ROSE_TASK_LOG_ROOT

The root path for log files of the suite task.

ROSE_DATA

The path to the data directory of the running suite.

ROSE_DATAC

The path to the data directory of this cycle time in the running suite.

ROSE_DATAC????

The path to the data directory of the cycle time with an offset relative to the current cycle time. ???? is a duration:

A __ (double underscore) prefix denotes a cycle time in the future (because a minus sign cannot be used in an environment variable). Otherwise, it is a cycle time in the past.

The rest should be either an ISO 8601 duration, such as:

P2W - 2 weeks
PT12H - 12 hours
P1DT6H - 1 day, 6 hours
P4M - 4 months
PT5M - 5 minutes

Or, for the case of integer cycling suites:

P1 - 1 cycle before the current cycle
P5 - 5 cycles before the current cycle

Deprecated syntax:

nW denotes n weeks.
n or nD denotes n days.
Tn or TnH denotes n hours.
TnM denotes n minutes.
TnS denotes s seconds.

E.g. ROSE_DATACPT6H is the data directory of 6 hours before the current cycle time.

E.g. ROSE_DATACP1D and ROSE_DATACPT24H are both the data directory of 1 day before the current cycle time.

ROSE_ETC

The path to the etc directory of the running suite.

ROSE_TASK_PREFIX

The prefix in the task name.

ROSE_TASK_SUFFIX

The suffix in the task name.

-t TIME, --cycle=TIME
                      Specify current cycle time.

                      If not defined, use the cycle time provided by the 
                      suite environment. `TIME` can be in an ISO date/time 
                      format, `CCYYMMDDhh` (deprecated) date/time format, or
                       a `TIME-DELTA` string described in the`--cycle-
                      offset=TIME-DELTA` option.
-T TIME-DELTA, --cycle-offset=TIME-DELTA
                      Specify one or more cycle offsets to determine what 
                      `ROSE_DATAC????` environment variables to export.

                      The `TIME-DELTA` argument uses the syntax explainedin 
                      the `ROSE_DATAC????` environment variable.

                      E.g. `--cycle-offset=PT3H --cycle-offset=PT6H` will 
                      tell `rose task-env` to export `ROSE_DATACPT3H` and 
                      `ROSE_DATACPT6H`.

                      NOTE: The main usage of this option is to reference a 
                      cycle time in the past, so a positive offset is used 
                      to go backward in time, and a negative offset is used 
                      to go forward in time.

                      E.g. `--cycle-offset=-PT3H` will tell `rose task-env` 
                      to export `ROSE_DATAC__PT3H` for `ROSE_DATAC` of 3 
                      hours ahead of the current cycle time.
-h, --help            show this help message and exit
-P PATTERN, --path=PATTERN
                      Specify glob patterns for paths to prepend to an 
                      environment variable called `NAME` (or `PATH` if 
                      `NAME` is not specified).

                      Can be used multiple times.

                      If a relative path is given, it is relative to 
                      `$ROSE_SUITE_DIR`. An empty value resets the default 
                      and any previous `--path=PATTERN` settings.

                      (Default for `PATH` is `"share/fcm[_-]make*/*/bin"` 
                      and `"work/fcm[_-]make*/*/bin"`)
--prefix-delim=DELIMITER
                      Specify the delimiter used to determine the task name 
                      prefix. Default=`_`
--suffix-delim=DELIMITER
                      Specify the delimiter used to determine the task name 
                      suffix. (Default=`_`.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

rose task-env can be used to make environment variables available to a suite by defining its flow.cylc env-script option as env-script = eval $(rose task-env).

rose tutorial§

# Print list of available suites.
rose tutorial
# Copy SUITE to DIR (defaults to ~/cylc-run/SUITE).
rose tutorial SUITE [DIR]

Make a copy of one of the tutorial SUITE in the cylc-run directory.

rose config-edit§

Warning

The Rose Edit GUI has not yet been reimplemented in Rose 2.

The old Rose 2019 (Python 2) GUI remains compatible with Rose 2 configurations.

rose suite-run§

This command has been replaced by cylc validate; cylc install; cylc play.

rose suite-restart§

This command has been replaced by cylc play.

etc/bin/rose-test-battery§

$ROSE_DEVELOPER_DIR/etc/bin/rose-test-battery

Run Rose self tests.

n.b. This will only work where a developer has downloaded and installed their own copy of Rose using pip install -e .

Change directory to Rose source tree, and runs this shell command:

exec prove -j "$NPROC" -s -r "${@:-t}"

where NPROC is the number of processors on your computer (or the setting [t]prove-options in the site/user configuration file). If you do not want to run the full test suite, you can specify the names of individual test files or their containing directories as extra arguments.

EXAMPLES

# Run the full test suite with the default options.
rose test-battery
# Run the full test suite with 12 processes.
rose test-battery -j 12
# Run only tests under "t/rose-app-run/" with 12 processes.
rose test-battery -j 12 t/rose-app-run
# Run only "t/rose-app-run/07-opt.t" in verbose mode.
rose test-battery -v t/rose-app-run/07-opt.t

SEE ALSO

prove(1)

Rosie Commands§

Options§

Usage: rosie checkout [OPTIONS] ID ...

Checkout local copies of suites.

For each ID in the argument list, checkout a working copy of the suite identified by ID to the standard location.

-f, --force    If working copy for suite identified by `ID` already exists, 
               remove it. Continue to the next `ID` if checkout of a suite 
               fails.
-h, --help     show this help message and exit
--debug        Report trace back on error.
--profile      Switch on profiling.
-q, --quiet    Decrement verbosity.
-v, --verbose  Increment verbosity.

Options§

Usage: rosie create [OPTIONS]

    rosie copy [OPTIONS] ID-OF-EXISTING-SUITE

rosie create: Create a new suite rosie copy : Create a new suite and copy content from an existing one.

Assign a new ID and create the directory structure in the central repository for a new suite.

The location of the repository for the new suite is determined in order of preference:

--prefix=PREFIX option
prefix of the ID-OF-EXISTING-SUITE
[rosie-id]prefix-default option in the site/user configuration.

If ID-OF-EXISTING-SUITE is specified, copy items from the existing suite ID-OF-EXISTING-SUITE when the suite is created. It is worth noting that revision history of the copied items can only be preserved if ID-OF-EXISTING-SUITE is in the same repository of the new suite

The syntax of the ID-OF-EXISTING-SUITE is PREFIX-xxNNN[/BRANCH][@REV] (e.g. my-su173, my-su173/trunk, my-su173/trunk@HEAD). If REV is not specified, the last changed revision of the branch is used. If BRANCH is not specified, “trunk” is used.

NOTE: ID-OF-EXISTING-SUITE is _not_ a filepath.

-h, --help            show this help message and exit
--info-file=FILE      Specify the discovery information file.

                      If `FILE` is `-`, read from STDIN. The default 
                      behaviour is to open an editor to add suite discovery 
                      information.
--meta-suite          (Admin-only) Create the special suite in the 
                      repository containing discovery metadata and known 
                      keys.
--no-checkout         Do not checkout a working copy of the newly created 
                      suite. Default is to checkout.
-y, --non-interactive, --yes
                      Switch off interactive prompting.
--prefix=PREFIX       Specify the name of the suite repository.
--project=PROJECT     Create using project metadata.

                      Specify a project to check/query any available 
                      metadata. The default behaviour is to use noproject 
                      and metadata.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Options§

Usage: rosie delete [OPTIONS] [--] [ID ...]

Delete suites.

Check the standard working copy location for a checked out suite matching ID and remove it if there is no uncommitted change (or if --force is specified).

Delete the suite directory structure from the HEAD of the central repository matching the ID.

If no ID is specified and $PWD is a working copy of a suite, use the ID of the suite in the working copy.

-f, --force           Remove working copies even if there are uncommitted 
                      changes.

                      Continue with the next `ID` if delete of a suite 
                      fails.
-h, --help            show this help message and exit
--local-only          Delete only the local copy of a suite.
-y, --non-interactive, --yes
                      Switch off interactive prompting.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Arguments§

Usage: rosie graph [OPTIONS] [ID]

Graph suite copy ancestry.

-d DISTANCE, --distance=DISTANCE
                      The maximum distance (graph depth) for suites related 
                      to `ID` to be plotted. For example, if the distance is
                       1, only the parents and children (but not siblings) 
                      of`ID` will be plotted.  If not given, this is 
                      unlimited.Requires `ID` to be specified.
-h, --help            show this help message and exit
-o FILE, --output=FILE
                      The name of the file for dumping the output.

                      Otherwise, the output will go to a temporary file 
                      which will get tidied up.

                      The extension of the filename determines the output 
                      format - see graphviz AGraph.draw documentation.
--prefix=PREFIX       Specify the name of the suite repository.
-p PROPERTY, --property=PROPERTY
                      Specify a property.
--text                Print graph in text format

                      Prints parent and child suites of a suite `ID`.

                      For example, for a suite "bar" you may get 
                      resultslike:

                      * `[parent] foo`

                      * `[child1] baz`

                      * `[child1] qux`

                      * `[child2] quux`

                      * `[child3] corge`

                      where "foo" is the parent of "bar", "baz" and "qux" 
                      its first generation children, "quux" its second 
                      generation child and "corge" its third generation 
                      child.

                      Also supports use of the `--property` option for 
                      producing output. Requires `ID` to be specified.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

ID: A suite id to graph. If given, only the suites that are connected to this id by copy history will be graphed.

Options§

Usage: rosie hello [options]

Set up connection to one or more Rosie web service servers.

-h, --help       show this help message and exit
--prefix=PREFIX  Specify the Rosie web service names.
--debug          Report trace back on error.
--profile        Switch on profiling.
-q, --quiet      Decrement verbosity.
-v, --verbose    Increment verbosity.

Options§

Usage: rosie id [options]

Utility for working with suite IDs.

# Print the repository URL of a given suite ID
rosie id --to-origin mo1-abc45

# Print the local location of a given suite ID
rosie id --to-local-copy mo1-abc45

# Print the web URL of a given suite ID
rosie id --to-web mo1-abc45

# Print suite ID of working copy in $PWD
rosie id

# Print suite ID of working copy in a directory
rosie id /path/to/working/copy

# Print suite ID of a given URL
rosie id svn://fcm1/rose_mo1_svn/a/b/c/4/5

# Print latest suite ID in the default repository
rosie id --latest

# Print latest suite ID in the given repository
rosie id --latest mot

# Print next suite ID in the default repository
rosie id --next

-h, --help       show this help message and exit
--latest         Print the latest ID in the repository.
--next           Print the next available ID in the repository.
--to-local-copy  Convert ID to to the local copy path
--to-origin      Convert ID to the origin URL
--to-web         Convert ID to the web source URL
--debug          Report trace back on error.
--profile        Switch on profiling.
-q, --quiet      Decrement verbosity.
-v, --verbose    Increment verbosity.

Options§

Usage: rosie lookup [OPTIONS] LOOKUP-TEXT ...

Find suites in the suite discovery database.

Search for suites using an address, a query or search words and display the information of the matching suites.

Unless an option is used to specify the initial search type the argument is interpreted as follows:

A string beginning with “http”: an address
A string not beginning with “http”: search words

An address URL may contain shell meta characters, so remember to put it in quotes.

The default output format includes a local working copy status field (%local) in the first column.

A blank field means there is no related suite checked out.
= means that the suite is checked out at this branch and revision.
< means that the suite is checked out but at an older revision.
> means that the suite is checked out but at a newer revision.
S means that the suite is checked out but on a different branch.
M means that the suite is checked out and modified.
X means that the suite is checked out but is corrupted.

Search strings may contain SQL wildcard characters. E.g:

% (percent) is a substitute for zero or more characters.
_ (underscore) is a substitute for a single character.

-A, -U, --address-mode, --url
                      Shorthand for --lookup-mode=address
--all-revs            Specify whether to search deleted suites and 
                      superceded suites.
-h, --help            show this help message and exit
-m MODE, --lookup-mode=MODE, --mode=MODE
                      Specify the lookup mode.

                      `MODE` can be `address`, `query` or `search`.
-H, --no-headers      Do not print column headers.
--prefix=PREFIX       Specify the Rosie web service names.
-f FORMAT, --print-format=FORMAT, --format=FORMAT
                      Specify the format for printing results.

                      Control the output format of the results using a 
                      string containing column names or properties preceded 
                      by `%`.

                      For example: `rosie ls --format="%idx from %owner"` 
                      might give: `abc01 from daisy`
-Q, --query           Shorthand for --lookup-mode=query.
-r, --reverse         Reverse sort order
-S, --search          Shorthand for --lookup-mode=search.
-s FIELD, --sort=FIELD
                      Sort results by the field `FIELD` instead of revision.
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Increment verbosity.

Options§

Usage: rosie ls [options]

List the local suites.

Search for locally checked out suites and print their details.

The default format includes a local working copy status field (%local) in the first column. A blank field means there is no related suite checked out.

= means that the suite is checked out at this branch and revision.
< means that the suite is checked out but at an older revision.
> means that the suite is checked out but at a newer revision.
S means that the suite is checked out but on a different branch.
M means that the suite is checked out and modified.
X means that the suite is checked out but is corrupted.

-h, --help            show this help message and exit
-H, --no-headers      Do not print column headers.
--prefix=PREFIX       Specify the Rosie web service names.
-f FORMAT, --print-format=FORMAT, --format=FORMAT
                      Specify the format for printing results.

                      Control the output format of the results using a 
                      string containing column names or properties preceded 
                      by `%`.

                      For example: `rosie ls --format="%idx from %owner"` 
                      might give: `abc01 from daisy`
-r, --reverse         Reverse sort order
-s FIELD, --sort=FIELD
                      Sort results by the field `FIELD` instead of revision.
-u USER, --user=USER  Specify another user whose roses directory you want to
                       list e.g. `--user=~bob`
--debug               Report trace back on error.
--profile             Switch on profiling.
-q, --quiet           Decrement verbosity.
-v, --verbose         Display full info for each returned suite.

Command Reference§

Rose Commands§

Environment variables§

Environment variables§

Options§

Environment variables§

Configuration§

Options§

Print format§

Options§

Configuration§

Examples§

Environment variables§

Arguments§

Arguments§

Diagnostics§

Options§

Arguments§

Options§

Usage in suites§

See also§

rose tutorial§

rose config-edit§

rose suite-run§

rose suite-restart§

etc/bin/rose-test-battery§

Rosie Commands§

Options§

Options§

Options§

Arguments§

Options§

Options§

Options§

Options§