Rose Reference Guide: CLI

Overview

• Rose Commands
• Rosie Commands

Rose Commands

rose provides the following utilities:

rose app-run

Run an application according to its configuration.

rose app-upgrade

Upgrade or downgrade an application according to metadata.

rose bush

Start/stop ad-hoc Rose Bush web service server.

rose config

Parse a set of rose configuration files.

rose config-diff

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

rose config-dump

Re-dump Rose configuration files in the common format.

rose config-edit

Launch the GTK+ GUI to edit a suite or application configuration.

rose date

Display the current or the specified DATE-TIME with an optional offset.

rose edit

(=config-edit)

rose env-cat

Substitute environment variables in input files and print.

rose host-select

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

rose macro

List or run macros associated with a suite or application.

rose metadata-check

Validate configuration metadata

rose metadata-gen

Automatically generate metadata from an application or suite

rose metadata-graph

Graph configuration metadata

rose mpi-launch

Provide a portable way to launch an MPI command.

rose namelist-dump

Convert namelist files into a Rose application configuration snippet.

rose rug-brief-tour

Populate the current directory for Rose User Guide: A Brief Tour.

rose stem

Run a suitable suite with the specified source tree and tasks(s).

rose sgc

(=suite-gcontrol)

rose slv

(=suite-log)

rose suite-clean

Remove items created by the previous suite runs.

rose suite-cmp-vc

Compare VCS information of a suite source between installation and now.

rose suite-gcontrol

Launch suite engine's suite control GUI for a suite.

rose suite-hook

Deprecated. Use cylc built-in event handlers instead.

rose suite-log

Launch web browser to display suite logs.

rose suite-log-view

(=suite-log)

rose suite-restart

Restart a shutdown suite from its last known state without reinstalling it.

rose suite-run

Install and run a cylc suite.

rose suite-scan

Scan for running suites.

rose suite-shutdown

Shutdown a running suite.

rose suite-stop

(=suite-shutdown)

rose task-env

Provide an environment for cycling suite task.

rose task-run

Provide an environment to run a suite task.

rose test-battery

Run Rose self tests.

Rosie Commands

rosie provides the following utilities:

rosie checkout

Checkout local copies of suites.

rosie co

(=checkout)

rosie copy

(=create)

rosie create

Create a new suite, and optionally copy items from an existing one.

rosie delete

Delete suites.

rosie disco

Start/stop ad-hoc Rosie Discovery web service server.

rosie go

Launch the Rosie client GTK+ GUI.

rosie graph

Graph suite copy ancestry.

rosie hello

Set up connection to a Rosie web service server.

rosie id

Utility for working with suite IDs.

rosie lookup

Find suites in the suite discovery database.

rosie ls

List the local suites.

General Usage

The tools and utilities discussed in this chapter are accessed via Unix/Linux commands that have a common syntax:

rose UTIL [OPTS] [ARG ...]
rosie UTIL [OPTS] [ARG ...]

All the commands described in this chapter accept the following standard options:

--debug

This option is useful for debugging purposes as it would instruct the system to print a traceback on error.

--quiet, -q

Each --quiet or -q on the command line decrements the verbosity of the command output by 1. The default verbosity is 1. If you want the command to only print what is essential to STDOUT and suppress warnings on STDERR, you can specify a single --quiet to reduce the verbosity to 0 (the loweest verbosity).

--verbose, -v

Each --verbose or -v on the command line increments the verbosity of the output by 1. The default verbosity is 1. The highest verbosity is normally 3. A single --verbose would increase the verbosity to STDOUT. A double --verbose --verbose or -v -v would increase the verbosity to the highest level. (More --verbose can be specified on the command line, but would normally have no effect.)

rose app-run

NAME

rose-app-run

SYNOPSIS

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

DESCRIPTION

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:

1. If COMMAND is specified, invoke the command.
2. If the --command-key=KEY option is defined, invoke the command specified in [command]KEY.
3. 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.
4. 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.
5. Invoke the command specified in [command]default.

OPTIONS

--app-mode=MODE

Run a builtin application identified by MODE. The default MODE is command.

--config=DIR, -C DIR

Specify the configuration directory of the application. (default=$PWD)

--command-key=KEY, -c KEY

Invoke the command specified in [command]KEY.

--define=[SECTION]KEY=VALUE, -D [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].

--install-only, -i

Install files only. Do not invoke the run.

--new, -N

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.

--opt-conf-key=KEY, -O KEY, --opt-conf-key='(KEY)', -O '(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.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

ENVIRONMENT VARIABLES

optional ROSE_APP_COMMAND_KEY

Switch to a particular command specified in [command]KEY

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.

rose app-upgrade

NAME

rose-app-upgrade

SYNOPSIS

rose app-upgrade [OPTIONS] [VERSION]

DESCRIPTION

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.

OPTIONS

--all-versions, -a

Use all tagged versions.

--config=DIR, -C DIR

Use configuration in DIR instead of $PWD.

--downgrade, -d;

Downgrade the version instead of upgrade.

--meta-path=PATH, -M PATH

Prepend PATH to the metadata search path (look here first). This option can be used repeatedly to load multiple paths.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything).

--output=DIR, -O DIR

The location of the output directory.

--quiet, -q

Reduce verbosity.

ARGUMENTS

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.

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

rose bush

NAME

rose bush

SYNOPSIS

rose bush start [PORT]

Start ad-hoc web service server (on PORT)

rose bush stop

Stop ad-hoc web service server

rose bush stop -y

Stop ad-hoc web service server without prompting

rose bush

Print status of ad-hoc web service server

DESCRIPTION

Start/stop ad-hoc Rose Bush web service server.

For rose bush start, if PORT is not specified, use port 8080.

Rose Bush is a web service for browsing users' Rose suite logs via an HTTP interface.

OPTIONS

--non-interactive, --yes, -y

(For stop only.) Switch off interactive prompting (=answer yes to everything).

--service-root, -R

(For start only.) Include web service name under root of URL.

rose config

NAME

rose config

SYNOPSIS

rose config SECTION OPTION

Print the value of OPTION in SECTION.

rose config --file=FILE SECTION OPTION

Print the value of OPTION in SECTION in FILE.

rose config --default=VALUE SECTION OPTION

Print the value of OPTION in SECTION if exists, or VALUE otherwise.

rose config SECTION

Print the OPTION=VALUE pairs in SECTION.

rose config OPTION

Print the value of a top level OPTION.

rose config --keys SECTION

Print the OPTION keys in SECTION.

rose config --keys

Print the SECTION keys.

rose config -q SECTION OPTION

Exit with 0 if OPTION exists in SECTION, or 1 otherwise.

rose config -q SECTION

Exit with 0 if SECTION exists, or 1 otherwise.

rose config --file=FILE1 --file=FILE2

Combine the configurations in FILE1 and FILE2, and dump the result.

rose config --file=FILE --meta SECTION OPTION

Print the value of OPTION in SECTION of the metadata associated with the specified config FILE.

rose config --meta-key=KEY

Print the value of a specified metadata KEY.

DESCRIPTION

Parse and print rose configuration files.

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

OPTIONS

--default

Specify a default value.

--env-var-process, -E

Process environment variable substitution. (Only works when returning a string value.)

--file=FILE, -f FILE

Each of these specifies a configuration file. If none specified, read from $THIS/../etc/rose.conf and $HOME/.metomi/rose.conf (where $THIS is the location of this command).

--keys, -k

If specified, only print the SECTION keys in the configuration file or the OPTION keys in a SECTION.

--meta

If specified, operate on the metadata associated with the configuration FILE.

--meta-key=KEY

If specified, 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

If specified, prints result as a Rose configuration file snippet. This allows the output to be concatenated into another Rose configuration file.

--print-ignored, -i

If specified, the program will print ignored !OPTION=VALUE where relevant.

--quiet, -q

Exit with 0 if the specified SECTION and/or OPTION exist in the configuration, or 1 otherwise.

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

rose config-diff

NAME

rose config-diff

SYNOPSIS

rose config-diff FILE1 FILE2

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

rose config-diff DIR1 DIR2

Display the metadata-annotated diff between two Rose config files in these directories.

rose config-diff --ignore=namelist:foo FILE1 FILE2

Display the diff, ignoring particular setting patterns.

rose config-diff --diff-tool=kdiff3 FILE1 FILE2

Display the diff with a particular diff tool.

rose config-diff FILE1 FILE2 -- [DIFF_OPTIONS] [DIFF_ARGUMENTS]

Display the diff with some diff tool specific options/arguments.

DESCRIPTION

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

OPTIONS

--diff-tool=TOOL

Specify an alternate diff tool like diffuse or kompare.

--graphical, -g

Use a graphical diff tool.

--ignore=PATTERN, -i PATTERN

Ignore settings that contain the regular expression PATTERN in their id. Can be specified more than once. PATTERN may also be a key used in site or user configuration which expands to a list of patterns. See CONFIGURATION below.

--meta-path=PATH, -M PATH

Prepend PATH to the metadata search path (look here first). This option can be used repeatedly to load multiple paths.

--opt-conf-key-1=KEY, --opt-conf-key-1='(KEY)'

opt-conf-key for the file in the first argument. 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.

--opt-conf-key-2=KEY, --opt-conf-key-2='(KEY)'

opt-conf-key for the file in the second argument. 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.

--properties=PROPERTIES, -p PROPERTIES

Only display these metadata properties. This should be a comma separated list such as title,description,help.

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

ARGUMENTS

PATH1, PATH2

Two Rose configuration files or directories to compare. If the path is a directory, look underneath for a Rose configuration file. '-' for FILE1 or FILE2 denotes read in from standard input.

--

Options and arguments after a -- token are passed directly to the diff tool.

CONFIGURATION

[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 and arguments after a -- token are passed directly to the diff tool.

rose config-dump

NAME

rose config-dump

SYNOPSIS

rose config-dump

Re-dump all Rose configuration files in the current directory.

rose config-dump -C /path/to/conf/dir

Re-dump all Rose configuration files in /path/to/conf/dir

rose config-dump -f /path/to/file1 -f /path/to/file2

Re-dump /path/to/file1 and /path/to/file2

DESCRIPTION

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. Parse a set of rose configuration files.

OPTIONS

--config=DIR, -C DIR

Change directory to DIR before looking for configuration files. (default=$PWD)

--file=FILE, -f FILE

Each of these specifies a configuration file. If --config=DIR is specified and FILE is a relative path, FILE is assumed to be relative to DIR.

--no-pretty

Do not apply format-specific pretty-printing.

--quiet, -q

Decrement verbosity. Do not report modified files.

rose config-edit

NAME

rose-config-edit

SYNOPSIS

rose config-edit [OPTIONS]... [PAGE_PATH]...

DESCRIPTION

Launch the GTK+ GUI to edit a suite or application configuration.

If a suite contains more than 10 applications then they will only be loaded after startup, on demand.

OPTIONS

--config=DIR, -C DIR

A path to either

1. a directory containing a suite with a file named suite.rc and a directory called app containing subdirectories with files named rose-app.conf, in the format specified in the Rose pages.
2. a directory containing a single "application" - a file named rose-app.conf and an optional subdirectory called file with other application files.

--load-all-apps

Force loading of all applications on startup.

--load-no-apps

Load applications in the suite on demand.

--meta-path=PATH, -M PATH

Prepend PATH to the search path for metadata (look here first). This option can be used repeatedly to load multiple paths.

--new

Launch, ignoring any configuration.

--no-metadata

Launch with metadata switched off.

--no-warn=WARNING-TYPE

Suppress warnings of the provided type.

ARGUMENTS

PAGE_PATH

One or more paths to open on load, pages may be full or partial namespaces e.g. 'foo/bar/env' or 'env'.
NOTE: Opens the shortest namespace that matches the provided string.

OPTIONS

--no-warn WARNING_TYPE

Suppress warnings of type WARNING_TYPE. WARNING_TYPE may be:

• version: 'could not find metadata for app/version, using app/HEAD' warnings.

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

rose date

NAME

rose-date

SYNOPSIS

# 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

DESCRIPTION

Parse and print a date time point or a duration.

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

OPTIONS

--as-total=TIME_FORMAT

Used to express an ISO 8601 duration in the specified time format, hours H, minutes M or seconds S.

--calendar=gregorian|360day|365day|366day

Specify the calendar mode. See CALENDER 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, -f FORMAT

Specify a format for print 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.

CALENDER MODE

The calendar mode is determined (in order) by:

1. The --calendar=MODE option.
2. The ROSE_CYCLING_MODE environment variable.
3. Default to gregorian.

OFFSET FORMAT

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 following deprecated syntax is supported: OFFSET in the form nU where U is the unit (w for weeks, d for days, h for hours, m for minutes and s for seconds) and n is a positive or negative integer.

PARSE FORMAT

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 (deprecated mode)

%Y%m%d%H

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

PRINT FORMAT

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'

rose edit

See rose config-edit.

rose env-cat

NAME

rose env-cat

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

--match-mode=MODE, -m MODE

Specify the match mode, which can be brace or default.

--output=FILE, -o FILE

Specify an output file. If no output file is specified or if FILE is -, write output to STDOUT.

--unbound=STRING, --undef=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.

rose host-select

NAME

rose host-select

SYNOPSIS

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

DESCRIPTION

Select a host from a set of groups or names by load, by free memory or by random. Use settings in $ROSE_HOME/etc/rose.conf and $HOME/.metomi/rose.conf to determine the ranking method.

Print the selected host name.

OPTIONS

--choice=N

Choose from any of the top N hosts.

--debug

Print stack trace on error.

--quiet, -q

Decrement verbosity.

--rank-method=METHOD[:METHOD-ARG]

Specify the method for ranking a list of hosts. The method can be:

• load (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 (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 (by largest amount of free memory):
  • Uses free -m to return memory in Mb
• random

--threshold=[METHOD[:METHOD-ARG]:]VALUE

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.

--verbose, -v

Increment verbosity.

CONFIGURATION

The command reads its settings from the [rose-host-select] section in $ROSE_HOME/etc/rose.conf and $HOME/.metomi/rose.conf. All settings are optional. 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)

Type rose config rose-host-select to print settings.

rose macro

NAME

rose-macro

SYNOPSIS

rose macro [OPTIONS] [MACRO_NAME ...]

DESCRIPTION

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 validation 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.

OPTIONS

--config=DIR, -C DIR

Use configuration in DIR instead of $PWD.

--fix, -F

Prepend all internal transformer (fixer) macros. to the argument list.

--meta-path=PATH, -M PATH

Prepend PATH to the metadata search path (look here first). This option can be used repeatedly to load multiple paths.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything).

--output=DIR, -O DIR

The location of the output directory. Only meaningful if there is at least one transformer in the argument list.

--quiet, -q

Reduce verbosity.

--suite-only

Run only for suite level macros.

--transform, -T

Prepend all transformer macros to the argument list.

--validate, -V

Prepend all validator macros to the argument list.

ARGUMENTS

MACRO_NAME ...

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

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

rose metadata-check

NAME

rose metadata-check

SYNOPSIS

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

DESCRIPTION

Validate configuration metadata.

OPTIONS

--config=DIR, -C DIR

The directory containing the configuration metadata i.e. containing the rose-meta.conf file, amongst other things. If not specified, the current directory will be used.

--property=PROPERTY, -p PROPERTY

Only check a certain property e.g. trigger. This can be specified more than once.

ARGUMENTS

ID ...

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

rose metadata-gen

NAME

rose metadata-gen

SYNOPSIS

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

DESCRIPTION

Automatically generate metadata from an application or suite configuration. An aid for metadata development. WARNING - May Contain Thorns.

OPTIONS

--auto-type

Add a 'best guess' for the type and length metadata.

--config=DIR, -C DIR

The directory containing the application or suite configuration to read in. If not specified, the current directory will be used.

--output=DIR, -O DIR

A directory to output the metadata to. If not specified, output to the application or suite metadata directory.

ARGUMENTS

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.

rose metadata-graph

NAME

rose-metadata-graph

SYNOPSIS

rose metadata-graph [OPTIONS] [SECTION ...]

DESCRIPTION

Graph configuration metadata.

OPTIONS

--config=DIR, -C DIR

The directory containing either the configuration or the configuration metadata. If the configuration is given, the metadata will be looked up in the normal way (see also --meta-path, ROSE_META_PATH). If the configuration metadata is given, there will be no configuration data used in the graphing. If not specified, the current directory will be used.

--meta-path=PATH, -M PATH

Prepend PATH to the metadata search path (look here first). This option can be used repeatedly to load multiple paths.

--property=PROPERTY, -p PROPERTY

Graph a certain property such as trigger. If specified, only this property will be graphed

ARGUMENTS

SECTION

One or more configuration sections to graph. If specified, only these sections will be checked.

ENVIRONMENT VARIABLES

optional ROSE_META_PATH

Prepend $ROSE_META_PATH to the metadata search path.

rose mpi-launch

NAME

rose-mpi-launch

SYNOPSIS

1. rose mpi-launch -f FILE
2. rose mpi-launch
3. rose mpi-launch COMMAND [ARGS ...]

DESCRIPTION

Provide a portable way to launch an MPI command.

1. 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.
2. 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.
3. In the final form, it will attempt to submit COMMAND with the MPI launcher command.

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

OPTIONS

--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.

CONFIGURATION

The command reads its settings from the [rose-mpi-launch] section in $ROSE_HOME/etc/rose.conf and $HOME/.metomi/rose.conf. 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-preopts.LAUNCHER=OPTION-TEMPLATE
launcher-postopts.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 $NPROC

ENVIRONMENT VARIABLES

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. 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.

DIAGNOSTICS

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

rose namelist-dump

NAME

rose-namelist-dump

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

--case=MODE

Output names in lower case (MODE="upper"), upper case (MODE="lower") or unchanged (default).

--lower, -l

Shorthand for --case=lower.

--output=FILE, -o FILE

The name of the file for dumping the output. Default is "-", i.e. the standard output.

-u, --upper

Shorthand for --case=upper.

rose rug-brief-tour

NAME

rose-rug-brief-tour

SYNOPSIS

rose rug-brief-tour

DESCRIPTION

Populate the current directory for Rose User Guide: A Brief Tour.

rose stem

NAME

rose stem

SYNOPSIS

rose stem [options]

DESCRIPTION

Run a suitable suite with a specified set of source tree(s). 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

OPTIONS

All options of rose suite-run are supported. Additional options are:

--source=SOURCE, -s SOURCE

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 by putting the project name as the first part of this argument separated by an equals sign as in the third example above. Defaults to '.' if not specified.

--group=GROUP[,GROUP2[,...]], -g GROUP[,GROUP2[,...]]

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.

--task=TASK[,TASK2[,...]], -t TASK[,TASK2[,...]]

Synonym for --group.

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 location of fcm-make config files.

rose sgc

See rose suite-gcontrol.

rose slv

See rose suite-log.

rose suite-clean

NAME

rose suite-clean

SYNOPSIS

rose suite-clean [OPTIONS] [SUITE-NAME [...]]

DESCRIPTION

Remove items created by rose suite-run.

If no argument is specified, use the base-name of $PWD as the suite name.

Correctly remove suite runtime directories created by rose suite-run including those on remote job hosts.

OPTIONS

--name=NAME, -n NAME

Append NAME to the argument list.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything).

--only=ITEM

If one or more --only=ITEM option is specified, only files and/or directories matching an ITEM will be removed. An ITEM should be a glob pattern (bash extglob) for matching a relative path in the run directory of the suite(s).

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

DIAGNOSTICS

Return the difference between the number of arguments and number of successfully cleaned suites, i.e. 0 if all successful.

rose suite-cmp-vc

NAME

rose suite-cmp-vc

SYNOPSIS

Compare source info of a named suite:

rose suite-cmp-vc NAME
rose suite-cmp-vc --name=NAME

If CYLC_SUITE_NAME is exported, compare source info of the current suite from within a suite task if no name is specified.

rose suite-cmp-vc

DESCRIPTION

Compare VCS information of a suite source between installation and now.

Version control system information of a suite is installed under log/rose-suite-run.version file. This command attempts to regenerate the information from the recorded source, and compare the original file with the latest information.

Return 0 if no difference. Print unified diff and return 1 if difference found. Return 2 on other errors.

ARGUMENTS

Specify the suite NAME.

OPTIONS

--name=NAME, -n NAME

Specify the suite NAME.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-gcontrol

NAME

rose suite-gcontrol

SYNOPSIS

rose suite-gcontrol [OPTIONS] [--name=SUITE-NAME] [-- EXTRA-ARGS ...]

DESCRIPTION

Launch suite engine's suite control GUI for a suite.

If --name=SUITE-NAME is not specified, the name will be determined by locating a rose-suite.conf file in $PWD or its nearest parent directories. In a normal suite, the basename of the (nearest parent) directory containing the rose-suite.conf file is assumed to be the suite name. In a project containing a rose stem suite, the basename of the (nearest parent) directory containing the rose-stem/rose-suite.conf file is assumed to be the suite name.

This wrapper is to deal with the use case where a suite may be running on dedicated servers at a site. The wrapper will make an attempt to detect where the suite is running or last run.

OPTIONS

--all

Open a suite control GUI for each running suite.

--host=HOST

Specify a host.

--name=SUITE-NAME

Specify the suite name.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-hook

NAME

rose-suite-hook

SYNOPSIS

cylc interface:

rose suite-hook [OPTIONS] EVENT SUITE MSG

DESCRIPTION

Deprecated. Use cylc built-in event handlers instead.

Provide a common event hook for cylc suites and tasks.

• (Task event only) Pull remote task logs back to server host.
• Email user if --mail specified.
• Shutdown suite if --shutdown specified.

OPTIONS

--debug

Switch on debug mode.

--mail-cc=LIST

Only useful if the --mail option is specified. Specify a comma separated list of additional addresses to email.

--mail

Trigger an email notification to the user.

--retrieve-job-logs

Retrieve remote task job logs.

--shutdown

Trigger a shutdown of the suite.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-log

NAME

rose suite-log

SYNOPSIS

1. rose suite-log [--view]
2. rose suite-log --update [ITEM ...]
   rose suite-log --update '*' # all task jobs
3. rose suite-log --archive CYCLE ...
   rose suite-log --archive '*' # all cycles

DESCRIPTION

View or update suite log.

1. Launch web browser to view suite log. If rose bush is not configured, the command will offer to start it.
2. Pull back task's job logs back from any remote hosts for specified cycle times or task names or IDs.
3. Archive (tar-gzip) job logs at or older than the specified cycle time.

If --name=SUITE-NAME is not specified, the name will be determined by locating a rose-suite.conf file in $PWD or its nearest parent directories. In a normal suite, the basename of the (nearest parent) directory containing the rose-suite.conf file is assumed to be the suite name. In a project containing a rose stem suite, the basename of the (nearest parent) directory containing the rose-stem/rose-suite.conf file is assumed to be the suite name.

OPTIONS

--archive

Archive (tar-gzip) job logs at specified cycle times. Implies --update.

--force, -f

Same as rose suite-log --update '*'.

--name=SUITE-NAME, -n SUITE-NAME

Specify the suite name.

--prune-remote

If specified, remove job logs from remote hosts after pulling them to suite host.

--tidy-remote

Deprecated. Use --prune-remote instead.

--update, -U

Update job logs and index for items specified in arguments.

--user=USER-NAME, -u USER-NAME

View mode only. View logs of a suite of a different user.

--view

Launch web browser to view suite log.

rose suite-log-view

See rose suite-log.

rose suite-restart

NAME

rose suite-restart

SYNOPSIS

rose suite-restart [OPTIONS] [[--] CYLC-RESTART-ARGS]

Restart a cylc suite with name equal to the base name of current working directory.

rose suite-restart --name=foobar

Restart cylc suite foobar

rose suite-restart --name=foobar -- state.20141118T161121.195326Z

Restart cylc suite foobar with a given state dump

rose suite-restart --name=foobar --host=my-suite-host

Restart cylc suite foobar on given host

DESCRIPTION

Restart a shutdown suite from its last known state without reinstalling it.

If re-installation is required, use rose suite-run --restart.

ARGUMENTS

Arguments (and options after --) are passed to cylc restart.

OPTIONS

--host=HOST

Specify a host for restarting the suite.

--name=NAME, -n NAME

Specify the suite NAME in cylc, instead of using the basename of the current working directory.

--no-gcontrol

Do not run cylc gui. Default is to run cylc gui if the suite is running and the DISPLAY environment variable is defined.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-run

NAME

rose suite-run

SYNOPSIS

rose suite-run [OPTIONS] [[--] CYLC-RUN-ARGS]

Install the suite in $PWD, and register it using basename of $PWD.

rose suite-run

Install and run a cylc suite in $PWD.

rose suite-run -- --mode=simulation

As above, but start the suite in simulation mode.

rose suite-run -n my.suite

Install and run the suite in $PWD, and register it as my.suite.

rose suite-run -C /dir/to/my.suite

Install and run suite in /dir/to/my.suite. Equivalent to (cd /dir/to/my.suite && rose suite-run).

DESCRIPTION

Install and run a cylc suite.

Install a suite (in $PWD), register it in cylc using the basename of the configuration directory or the option specified in --id=NAME. Invoke cylc run on it. Arguments (and options after --) are passed to cylc run.

OPTIONS

--config=DIR, -C DIR

Specify the configuration directory of the suite. (default=$PWD)

--define=[SECTION]KEY=VALUE, -D [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]. See also --suite-define.

--define-suite=KEY=VALUE, -S KEY=VALUE

As --define, but with an implicit [SECTION] for suite variables.

--host=HOST

Specify a host for running the suite.

--install-only, -i

Install the suite. Do not run it. Implies --no-gcontrol.

--local-install-only, -l

Install the suite locally. Do not install to job hosts. Do not run it. Implies --no-gcontrol.

--name=NAME, -n NAME

Specify the suite NAME in cylc, instead of using the basename of the configuration directory.

--log-keep=DAYS

Specify the number of days to keep log directories/archives. Do not housekeep if not specified. Named log directories (created by --log-name=NAME in previous runs) will not be housekept.

--log-name=NAME

Specify a name for the log directory of the current run. If specified, it will create a symbolic link log.NAME to point to the log directory of the current run. Named log directories will not be automatically archived or housekept. Only works with --run=run.

--new, -N

(Re-)create working directories. This option is equivalent to running rose suite-clean -y && rose suite-run and will remove previous runs. Users may want to take extra care when using this option.

--no-gcontrol

Do not run cylc gui. Default is to run cylc gui if the suite is running and the DISPLAY environment variable is defined.

--no-log-archive

Do not archive (tar-gzip) old log directories.

--no-overwrite

Do not overwrite existing files.

--no-strict

Do not validate (suite engine configuration) in strict mode.

--opt-conf-key=KEY, -O KEY, --opt-conf-key='(KEY)', -O '(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.

--quiet, -q

Decrement verbosity.

--restart

Invoke cylc restart instead of cylc run.

--reload

Shorthand for --run=reload.

--restart

Shorthand for --run=restart.

--run=reload|restart|run

Invoke cylc reload, cylc restart or cylc run according to this option. See cylc User Guide for detail. (default=run)

--verbose, -v

Increment verbosity.

ENVIRONMENT VARIABLES

rose suite-run provides the following environment variables to the suite:

ROSE_ORIG_HOST

The name of the host where the rose suite-run command was invoked.

optional ROSE_SUITE_OPT_CONF_KEYS

Each KEY in this space delimited list switches on an optional configuration. The configurations are applied first-to-last.

JINJA2

rose suite-run provides the following Jinja2 variables to the suite:

ROSE_ORIG_HOST

The name of the host where the rose suite-run command was invoked.

SEE ALSO

cylc help gui

cylc help register

cylc help run

rose suite-scan

NAME

rose suite-scan

SYNOPSIS

rose suite-scan [HOST ...]

DESCRIPTION

Scan for running suites.

If no HOST specified, use [rose-suite-run] hosts setting in site/user configuration. If no configuration defined, use localhost.

OPTIONS

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-shutdown

NAME

rose suite-shutdown

SYNOPSIS

rose suite-shutdown [OPTIONS] [--name=SUITE-NAME] [[--] EXTRA-ARGS ...]

DESCRIPTION

Shutdown a running suite.

If --name=SUITE-NAME is not specified, the name will be determined by locating a rose-suite.conf file in $PWD or its nearest parent directories. In a normal suite, the basename of the (nearest parent) directory containing the rose-suite.conf file is assumed to be the suite name. In a project containing a rose stem suite, the basename of the (nearest parent) directory containing the rose-stem/rose-suite.conf file is assumed to be the suite name.

This wrapper is to deal with the use case where a suite may be running on dedicated servers at a site. The wrapper will make an attempt to detect where the suite is running or last run.

OPTIONS

--all

Shutdown all running suites. You will be prompted to confirm shutting down each affected suite.

--host=HOST

Specify a host.

--name=SUITE-NAME

Specify the suite name.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything).

-- --EXTRA-ARGS

See the cylc documentation, cylc shutdown for options and details on EXTRA-ARGS.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rose suite-stop

See rose suite-shutdown.

rose task-env

NAME

rose-task-env

SYNOPSIS

rose task-env [OPTIONS]

eval $(rose task-env)

DESCRIPTION

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_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 n 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.

OPTIONS

--cycle=TIME, -t TIME

Specify the cycle time. If not defined, use the cycle time provided by the suite environment. TIME can be in an ISO 8601 date/time format, CCYYMMDDhh (deprecated) date/time format or a TIME-DELTA string described in the --cycle-offset=TIME-DELTA option.

--cycle-offset=TIME-DELTA, -T TIME-DELTA

Specify one or more cycle offsets to determine what ROSE_DATAC???? environment variables to export. The TIME-DELTA argument uses the syntax explained above in 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.

--path=[NAME=]PATTERN, -P [NAME=]PATTERN

Each of these specify a glob pattern for paths to prepend to an environment variable called NAME (or PATH if NAME is not specified). 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=_)

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

USAGE IN SUITES

rose task-env can be used to make environment variables available to a suite by defining its suite.rc env-script option as:

env-script = "eval $(rose task-env)"

rose task-run

NAME

rose-task-run

SYNOPSIS

rose task-run [OPTIONS] [--] [APP-COMMAND ...]

DESCRIPTION

Provide an environment to run a suite task.

Provides environment variables documented in rose task-env. It is worth noting that if the environment variables are already provided by rose task-env, this command will not override them.

Normally, the suite task will select a Rose application configuration that has the same name as the task. This can be overridden by the --app-key=KEY option or the ROSE_TASK_APP environment variable.

OPTIONS

All options of rose app-run and rose task-env are supported.

Additional options are:

--app-key=KEY

Specify a named application configuration.

ENVIRONMENT VARIABLES

All environment variables of rose app-run and rose task-env are supported.

The following environment variables are used by rose task-run:

ROSE_TASK_APP

Specify a named application configuration.

All environment variables documented in rose task-env are passed to the application rose task-run runs.

SEE ALSO

rose app-run

rose task-env

rose test-battery

NAME

rose-test-battery

SYNOPSIS

rose test-battery [-v] [UTIL ...]

DESCRIPTION

Run Rose self tests.

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.

EXAMPLE

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 checkout

NAME

rosie checkout

SYNOPSIS

rosie checkout [OPTIONS] ID ...

DESCRIPTION

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.

OPTIONS

--force, -f

If working copy for suite identified by ID already exists, remove it. Continue to the next ID if checkout of a suite fails.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rosie co

See rosie checkout.

rosie copy

NAME

rosie create

SYNOPSIS

rosie create [OPTIONS]

rosie copy [OPTIONS] FROM-ID

DESCRIPTION

Create a new suite, and optionally copy items from an existing one.

Assign an 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:

1. --prefix=PREFIX option
2. prefix of the FROM-ID
3. [rosie-id]prefix-default option in the site/user configuration.

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

The syntax of the FROM-ID 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.

OPTIONS

--info-file=FILE

Specify a FILE containing the discovery information for the new suite. If FILE is -, read from STDIN. The default behaviour is to open an editor to add suite discovery information.

--no-checkout

Do not checkout a working copy of the newly created suite. Default is to checkout.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything)

--prefix=PREFIX

Specify the prefix (i.e. the suite repository) to use.

--project=PROJECT

Specify a project to check/query any available metadata. The default behaviour is to use no project and no metadata.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rosie create

NAME

rosie create

SYNOPSIS

rosie create [OPTIONS]

rosie copy [OPTIONS] FROM-ID

DESCRIPTION

Create a new suite, and optionally copy items from an existing one.

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

OPTIONS

--info-file=FILE

Specify a FILE containing the discovery information for the new suite. If FILE is -, read from STDIN. The default behaviour is to open an editor to add suite discovery information.

--no-checkout

Do not checkout a working copy of the newly created suite. Default is to checkout.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything)

--prefix=PREFIX

Specify the prefix (i.e. the suite repository) to use. The default behaviour is to use the site default.

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rosie delete

NAME

rosie delete

SYNOPSIS

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

DESCRIPTION

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.

OPTIONS

--force, -f

Remove working copies even if there are uncommitted changes. Continue with the next ID if delete of a suite fails.

--local-only

Remove only the working copy of a suite.

--non-interactive, --yes, -y

Switch off interactive prompting (=answer yes to everything)

--quiet, -q

Decrement verbosity.

--verbose, -v

Increment verbosity.

rosie disco

NAME

rosie disco

SYNOPSIS

rosie disco start [PORT]

Start ad-hoc web service server (on PORT)

rosie disco stop

Stop ad-hoc web service server

rosie disco stop -y

Stop ad-hoc web service server without prompting

rosie disco

Print status of ad-hoc web service server

DESCRIPTION

Start/stop ad-hoc Rosie Discovery web service server.

For rosie disco start, if PORT is not specified, use port 8080.

OPTIONS

--non-interactive, --yes, -y

(For stop only.) Switch off interactive prompting (=answer yes to everything).

--service-root, -R

(For start only.) Include web service name under root of URL.

rosie go

NAME

rosie go

SYNOPSIS

rosie go [OPTIONS] [SEARCH]

DESCRIPTION

Launch the Rosie client GTK+ GUI.

If arguments are specified, rosie go will perform an initial lookup based on the arguments, which can be an address, a query, or search words. See rosie lookup for detail.

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.

Search strings may contain SQL wildcard characters. E.g. A percent sign % is a substitute for zero or more characters. An underscore sign _ is a substitute for a single character.

If no argument is specified, rosie go will display a list of all your locally checked out suites.

OPTIONS

--address-mode, --url, -A, -U

Shorthand for --lookup-mode=address.

--all-revs

Specify whether to search deleted suites and superceded suites.

--lookup-mode=MODE

Specify the initial lookup mode. MODE can be address, query or search.

--prefix=PREFIX

Specify the name of a Rosie web service to use. This option can be used multiple times.

--query, -Q

Shorthand for --lookup-mode=query.

--search, -S

Shorthand for --lookup-mode=search.

SEE ALSO

rosie lookup

rosie ls

rosie graph

NAME

rosie graph

SYNOPSIS

rosie graph [OPTIONS] [ID]

DESCRIPTION

Graph suite copy ancestry.

OPTIONS

--distance=DISTANCE, -d 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.

--output=FILE, -O 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

Display suites from only the specified web services. This option can be used multiple times.

--text

Print parent and child suites of a suite ID. For example, for a suite "bar" you may get results like:

[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. Requires ID to be specified.

--property=PROPERTY, -p PROPERTY

Add a certain suite property to the node labels - e.g. owner or title. This option can be used multiple times.

ARGUMENTS

ID

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

rosie hello

NAME

rosie hello

SYNOPSIS

rosie hello [--prefix=PREFIX]

DESCRIPTION

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

OPTIONS

--prefix=PREFIX

Specify the name of one or more Rosie web service servers to use. This option can be used multiple times.

rosie id

NAME

rosie id

SYNOPSIS

rosie id [OPTIONS]

rosie id --to-origin [ID]

Print the repository URL of a given suite ID

rosie id --to-local-copy [ID]

Print the local location of a given suite ID

rosie id --to-output [ID]

Print the output directory of a given suite ID

rosie id --to-web [ID]

Print the web URL of a given suite ID

rosie id

Print suite ID of working copy in $PWD

rosie id /path/to/working/copy

Print suite ID of working copy in a directory

rosie id svn://fcm1/rose_mo1_svn/a/b/c/4/5

Print suite ID of a given URL

rosie id --latest

Print latest suite ID in the default repository

rosie id --latest mot

Print latest suite ID in the given repository

rosie id --next

Print next suite ID in the default repository

DESCRIPTION

Utility for working with suite IDs.

OPTIONS

--latest

Print the latest suite ID in the repository

--to-local-copy

Print the local location of a given suite ID

--to-origin

Print the repository URL of a given suite ID

--to-output

Print the output directory of a given suite ID

--to-web

Print the web URL of a given suite ID

--next

Print the next available suite ID in the repository

rosie lookup

NAME

rosie lookup

SYNOPSIS

rosie lookup [OPTIONS] LOOKUP-TEXT ...

DESCRIPTION

Find suites in the suite discovery database.

Search for suites using either 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

Unless an option is used to specify the lookup type the input is interpreted by default as follows:

• string beginning with "http": url
• string not beginning with "http": search

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.

Search strings may contain SQL wildcard characters. E.g. A percent sign % is a substitute for zero or more characters. An underscore sign _ is a substitute for a single character.

OPTIONS

--address-mode, --url, -A, -U

Shorthand for --lookup-mode=address.

--all-revs

Specify whether to search deleted suites and superceded suites.

--no-headers, -H

Do not print column headers.

--lookup-mode=MODE

Specify the initial lookup mode. MODE can be address, query or search.

--prefix=PREFIX

Specify the name of a Rosie web service to use. This option can be used multiple times.

--print-format=FORMAT, --format=FORMAT, -f FORMAT

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

For example: rosie lookup daisy --format="%idx from %owner" might give:

abc01 from daisy

--query, -Q

Shorthand for --lookup-mode=query.

--quiet, -q

Shorthand for --format="%idx".

--reverse, -r

Reverse sort order.

--search, -S

Shorthand for --lookup-mode=search.

--sort=FIELD, -s FIELD

Sort results by the field FIELD instead of revision.

--verbose, -v

Display full info for each returned suite.

rosie ls

NAME

rosie ls

SYNOPSIS

rosie ls [OPTIONS]

DESCRIPTION

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.

OPTIONS

--no-headers, -H

Do not print column headers.

--prefix=PREFIX

Display locally checked out suites from the specified suite repository. This option can be used multiple times.

--print-format=FORMAT, --format=FORMAT, -f FORMAT

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

--quiet, -q

Shorthand for --format="%idx".

--reverse, -r

Reverse sort order.

--sort=FIELD, -s FIELD

Sort results by the field FIELD instead of revision.

--user=~USERNAME, -u ~USERNAME

Specify another user whose roses directory you want to list e.g. --user=~bob

--verbose, -v

Display full info for each returned suite.