Command Reference¶

Rose Commands¶

rose app-run¶

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.

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

rose app-upgrade¶

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.

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

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 w/o prompting
rose bush              # print status of ad-hoc web service server

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 check-software¶

rose check-software [OPTIONS]

Check software dependencies for the rose documentation builder.

OPTIONS

rose config¶

# 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

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¶

# 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]

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 of metadata options, 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 PATH1 or PATH2 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 ...

rose config-dump¶

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

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.

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¶

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

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:

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.
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. WARNING-TYPE may be:

version: Suppress “Could not find metadata for app/version, using app/HEAD” warnings.

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.

ENVIRONMENT VARIABLES

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

rose date¶

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

OPTIONS

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

CALENDAR MODE

The calendar mode is determined (in order) by:

The --calendar=MODE option.
The ROSE_CYCLING_MODE environment variable.
Default to “gregorian”.

ENVIRONMENT VARIABLES

ROSE_CYCLING_MODE=gregorian|360day|365day|366day: Specify the calendar mode.
ROSE_TASK_CYCLE_TIME: 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 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: %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¶

Alias - see rose config-edit

rose env-cat¶

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.

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¶

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

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

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.

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

rose macro¶

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.

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 --fix, --validate are 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 make-docs¶

rose make-docs [OPTIONS] [BUILD...]

Build the rose documentation in the requested BUILD format(s).

OPTIONS

--venv: Build virtualenv for temporarilly installing python dependencies if necessary.
--dev: Development mode, don’t remove virtualenv after build.
--strict: Disable cache forcing a complete re-build and turn warnings into errors.
--debug: Run make with the –debug option.
--default-version=VERSION: By default the current version is symlinked as the default version, provide an alternative version to override this.

BUILD

The format(s) to build the documentation in - default html. Avaliable formats are listed in the sphinx documentation (http://www.sphinx-doc.org/en/stable/builders.html). The most commonly used formats are:

html: For building standalone HTML files.
singlehtml: For building a single page HTML document.
latexpdf: For building PDF documentation.
clean: Removes all built documentation for the current rose version. (use rm -rf doc to remove all documentation).

DEVELOPMENT BUILDS

For development purposes use the following BUILDs:

doctest: Runs any doctest examples present in documented python modules.
linkcheck: Checks external links.

SOFTWARE ENVIRONMENT

The software dependencies can be found by running the command:

$ rose check-software --docs

Rose provides two ways of installing the Python dependencies for the Rose documentation builder:

Virtual Environment:

Rose will automatically build a Python virtual environment when the –venv flag is used with this command. The virtual environment will be created in rose/venv and will be destroyed after use. Use the –dev flag to prevent the environment being destroyed for future use. Example:

$ rose make-docs --venv --dev html  # create and keep a virtualenv

Conda

An environment file for creating a conda env can be found in etc/rose-docs-env.yaml. Example usage:

$ conda env create -f etc/rose-docs-env.yaml  # create conda env
$ source activate rose-docs  # activate conda env
$ rose make-docs html  # make docs as normal

rose metadata-check¶

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

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. If specified, only this section will be checked.

rose metadata-gen¶

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

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¶

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

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 e.g. 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¶

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.

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

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

DIAGNOSTICS

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

rose namelist-dump¶

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.

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 sgc¶

Alias - see rose suite-gcontrol

rose slv¶

Alias - see rose suite-log

rose stem¶

rose stem [options]

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, --source=PROJECT=SOURCE, -s PROJECT=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 revision of fcm-make config files.

rose suite-clean¶

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

Remove items created by “rose suite-run”.

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

Correctly remove 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¶

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

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

OPTIONS

--name=NAME, -n NAME: Specify the suite NAME.
--quiet, -q: Decrement verbosity.
--verbose, -v: Increment verbosity.

rose suite-gcontrol¶

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

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.
--name=SUITE-NAME: Specify the suite name.
--quiet, -q: Decrement verbosity.
--verbose, -v: Increment verbosity.

rose suite-hook¶

# Cylc interface
rose suite-hook [OPTIONS] EVENT SUITE MSG
rose task-hook [OPTIONS] EVENT SUITE TASK_ID MSG

Deprecated. Use cylc built-in event handlers instead.

Provide a common event hook for cylc suites and tasks.

(Task event only) Retrieve 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-init¶

Alias - see rose suite-run

rose suite-log¶

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

View or update suite log.

Launch web browser to view suite log. If “rose bush” is not configured, the command will offer to start it.
Pull back task job logs from any remote hosts for specified cycle times or task names or IDs.
Archive (tar-gzip) job logs at 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, instead of using basename of $PWD.
--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 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¶

Alias - see rose suite-log

rose suite-restart¶

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

# Restart cylc suite with name equal to basename of $PWD.
rose suite-restart

# Restart cylc suite NAME
rose suite-restart --name=NAME

# Restart cylc suite NAME with a given state dump
rose suite-restart --name=NAME -- state.20141118T161121.195326Z

# Restart cylc suite NAME on given host
rose suite-restart --name=NAME --host=my-suite-host

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

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

ARGUMENTS

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¶

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

# Install and run a Cylc suite in $PWD.
rose suite-run

# As above, but start the suite in simulation mode.
rose suite-run -- --mode=simulation

# Install and run the suite in $PWD, and register it as "my.suite".
rose suite-run -n my.suite

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

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 --name=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 --define-suite.
--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.
--validate-suite-only: Install the suite in a temporary location. Do not setup any directories. Do not run any jobs. Implies –no-gcontrol. Overrides –install-only and –local-install-only.
--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.
--name=NAME, -n NAME: Specify the suite NAME in Cylc, instead of using the basename of the configuration directory.
--new, -N: (Re-)create suite runtime locations. 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.
--reload: Shorthand for --run=reload.
--restart: Shorthand for --run=restart.
--run=reload|restart|run: Invoke cylc reload|restart|run according to this option. (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.

SUITE VARIABLES

rose suite-run provides the following variables to the suite as: template variables (i.e. Jinja2 or EmPy).
ROSE_ORIG_HOST: The name of the host where the rose suite-run command was invoked.
ROSE_SUITE_VARIABLES: Dictionary containing all suite variables inserted via [jinja2:suite.rc] or [empy:suite.rc] section.

SEE ALSO

cylc help gui
cylc help register
cylc help run

rose suite-scan¶

rose suite-scan [...]

Run cylc scan [...].

rose suite-shutdown¶

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

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 also deals 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.
--name=SUITE-NAME: Specify the suite name.
--non-interactive, --yes, -y: Switch off interactive prompting (=answer yes to everything)
--quiet, -q: Decrement verbosity.
--verbose, -v: Increment verbosity.
-- --EXTRA-ARGS: See the cylc documentation, cylc shutdown for options and details on EXTRA-ARGS.

rose suite-stop¶

Alias - see rose suite-shutdown

rose task-env¶

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.

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 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-hook¶

Alias - see rose suite-hook

rose task-run¶

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

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. All environment variables documented in rose task-env are passed to the application rose task-run runs. The following environment variables are used by rose task-run:

ROSE_TASK_APP: Specify a named application configuration.

SEE ALSO

rose app-run
rose task-env

rose test-battery¶

rose test-battery

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.

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)

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.

Rosie Commands¶

rosie checkout¶

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.

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¶

Alias - see rosie checkout

rosie copy¶

Alias - see rosie create

rosie create¶

rosie create [OPTIONS]
rosie copy [OPTIONS] FROM-ID

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:

--prefix=PREFIX option
prefix of the FROM-ID
[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.
--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.
--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 metadata.
--quiet, -q: Decrement verbosity.
--verbose, -v: Increment verbosity.

rosie delete¶

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.

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¶

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 w/o prompting
rosie disco              # print status of ad-hoc web service server

Start/stop ad-hoc Rosie suite 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¶

rosie go [OPTIONS] [...]

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.

% (percent) is a substitute for zero or more characters.
_ (underscore) 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¶

rosie graph [OPTIONS] [ID]

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 for producing output. 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¶

rosie hello [--prefix=PREIFX]

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¶

rosie id [OPTIONS]

# 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 output directory of a given suite ID
rosie id --to-output 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

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¶

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.

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¶

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.

OPTIONS

--prefix=PREFIX: Display locally checked out suites from only the specified web services. This option can be used multiple times.
--no-headers, -H: Do not print column headers.
--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.