.. _CommandReference: Command Reference ================= .. _help: Help ---- .. code-block:: none Cylc ("silk") is a workflow engine for orchestrating complex *suites* of inter-dependent distributed cycling (repeating) tasks, as well as ordinary non-cycling workflows. For detailed documentation see the Cylc User Guide (cylc doc --help). Version 7.9.3 The graphical user interface for cylc is "gcylc" (a.k.a. "cylc gui"). USAGE: % cylc -V,--version,version # print cylc version % cylc version --long # print cylc version and path % cylc help,--help,-h,? # print this help page % cylc help CATEGORY # print help by category % cylc CATEGORY help # (ditto) % cylc help [CATEGORY] COMMAND # print command help % cylc [CATEGORY] COMMAND --help # (ditto) % cylc COMMAND --help # (ditto) % cylc COMMAND [options] SUITE [arguments] % cylc COMMAND [options] SUITE TASK [arguments] Commands can be abbreviated as long as there is no ambiguity in the abbreviated command: % cylc trigger SUITE TASK # trigger TASK in SUITE % cylc trig SUITE TASK # ditto % cylc tr SUITE TASK # ditto % cylc get # Error: ambiguous command TASK IDENTIFICATION IN CYLC SUITES Tasks are identified by NAME.CYCLE_POINT where POINT is either a date-time or an integer. Date-time cycle points are in an ISO 8601 date-time format, typically CCYYMMDDThhmm followed by a time zone - e.g. 20101225T0600Z. Integer cycle points (including those for one-off suites) are integers - just '1' for one-off suites. HOW TO DRILL DOWN TO COMMAND USAGE HELP: % cylc help # list all available categories (this page) % cylc help prep # list commands in category 'preparation' % cylc help prep edit # command usage help for 'cylc [prep] edit' Command CATEGORIES: control ....... Suite start up, monitoring, and control. information ... Interrogate suite definitions and running suites. all ........... The complete command set. task .......... The task messaging interface. license|GPL ... Software licensing information (GPL v3.0). admin ......... Cylc installation, testing, and example suites. preparation ... Suite editing, validation, visualization, etc. hook .......... Suite and task event hook scripts. discovery ..... Detect running suites. utility ....... Cycle arithmetic and templating, etc. Command Categories ------------------ .. _command-cat-admin: admin ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: admin - Cylc installation, testing, and example suites. HELP: cylc [admin] COMMAND help,--help You can abbreviate admin and COMMAND. The category admin may be omitted. COMMANDS: check-software .... Check required software is installed import-examples ... Import example suites your suite run directory profile-battery ... Run a battery of profiling tests test-battery ...... Run a battery of self-diagnosing test suites upgrade-run-dir ... Upgrade a pre-cylc-6 suite run directory .. _command-cat-all: all ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: all - The complete command set. HELP: cylc [all] COMMAND help,--help You can abbreviate all and COMMAND. The category all may be omitted. COMMANDS: 5to6 ........................................ Improve the cylc 6 compatibility of a cylc 5 suite file broadcast|bcast ............................. Change suite [runtime] settings on the fly cat-log|log ................................. Print various suite and task log files cat-state ................................... Print the state of tasks from the state dump check-software .............................. Check required software is installed check-triggering ............................ A suite shutdown event hook for cylc testing check-versions .............................. Compare cylc versions on task host accounts checkpoint .................................. Tell suite to checkpoint its current state client ...................................... (Internal) Invoke HTTP(S) client, expect JSON input conditions .................................. Print the GNU General Public License v3.0 cycle-point|cyclepoint|datetime|cycletime ... Cycle point arithmetic and filename templating diff|compare ................................ Compare two suite definitions and print differences documentation|browse ........................ Display cylc documentation (User Guide etc.) dump ........................................ Print the state of tasks in a running suite edit ........................................ Edit suite definitions, optionally inlined email-suite ................................. A suite event hook script that sends email alerts email-task .................................. A task event hook script that sends email alerts ext-trigger|external-trigger ................ Report an external trigger event to a suite function-run ................................ (Internal) Run a function in the process pool get-directory ............................... Retrieve suite source directory paths get-gui-config .............................. Print gcylc configuration items get-host-metrics ............................ Print localhost metric data get-site-config|get-global-config ........... Print site/user configuration items get-suite-config|get-config ................. Print suite configuration items get-suite-contact|get-contact ............... Print contact information of a suite server program get-suite-version|get-cylc-version .......... Print cylc version of a suite server program gpanel ...................................... Internal interface for GNOME 2 panel applet graph ....................................... Plot suite dependency graphs and runtime hierarchies graph-diff .................................. Compare two suite dependencies or runtime hierarchies gscan|gsummary .............................. Scan GUI for monitoring multiple suites gui ......................................... (a.k.a. gcylc) cylc GUI for suite control etc. hold ........................................ Hold (pause) suites or individual tasks import-examples ............................. Import example suites your suite run directory insert ...................................... Insert tasks into a running suite jobs-kill ................................... (Internal) Kill task jobs jobs-poll ................................... (Internal) Retrieve status for task jobs jobs-submit ................................. (Internal) Submit task jobs jobscript ................................... Generate a task job script and print it to stdout kill ........................................ Kill submitted or running tasks list|ls ..................................... List suite tasks and family namespaces ls-checkpoints .............................. Display task pool etc at given events message|task-message ........................ Report task messages monitor ..................................... An in-terminal suite monitor (see also gcylc) nudge ....................................... Cause the cylc task processing loop to be invoked ping ........................................ Check that a suite is running poll ........................................ Poll submitted or running tasks print ....................................... Print registered suites profile-battery ............................. Run a battery of profiling tests ref-graph ................................... Print text-format "reference graphs" without GTK register .................................... Register a suite for use release|unhold .............................. Release (unpause) suites or individual tasks reload ...................................... Reload the suite definition at run time remote-init ................................. (Internal) Initialise a task remote remote-tidy ................................. (Internal) Tidy a task remote remove ...................................... Remove tasks from a running suite report-timings .............................. Generate a report on task timing data reset ....................................... Force one or more tasks to change state restart ..................................... Restart a suite from a previous state review ...................................... Start/stop ad-hoc Cylc Review web service server. run|start ................................... Start a suite at a given cycle point scan ........................................ Scan a host for running suites scp-transfer ................................ Scp-based file transfer for cylc suites search|grep ................................. Search in suite definitions set-verbosity ............................... Change a running suite's logging verbosity show ........................................ Print task state (prerequisites and outputs etc.) spawn ....................................... Force one or more tasks to spawn their successors stop|shutdown ............................... Shut down running suites submit|single ............................... Run a single task just as its parent suite would suite-state ................................. Query the task states in a suite test-battery ................................ Run a battery of self-diagnosing test suites trigger ..................................... Manually trigger or re-trigger a task upgrade-run-dir ............................. Upgrade a pre-cylc-6 suite run directory validate .................................... Parse and validate suite definitions view ........................................ View suite definitions, inlined and Jinja2 processed warranty .................................... Print the GPLv3 disclaimer of warranty .. _command-cat-control: control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: control - Suite start up, monitoring, and control. HELP: cylc [control] COMMAND help,--help You can abbreviate control and COMMAND. The category control may be omitted. COMMANDS: broadcast|bcast ................ Change suite [runtime] settings on the fly checkpoint ..................... Tell suite to checkpoint its current state client ......................... (Internal) Invoke HTTP(S) client, expect JSON input ext-trigger|external-trigger ... Report an external trigger event to a suite gui ............................ (a.k.a. gcylc) cylc GUI for suite control etc. hold ........................... Hold (pause) suites or individual tasks insert ......................... Insert tasks into a running suite kill ........................... Kill submitted or running tasks nudge .......................... Cause the cylc task processing loop to be invoked poll ........................... Poll submitted or running tasks release|unhold ................. Release (unpause) suites or individual tasks reload ......................... Reload the suite definition at run time remove ......................... Remove tasks from a running suite reset .......................... Force one or more tasks to change state restart ........................ Restart a suite from a previous state run|start ...................... Start a suite at a given cycle point set-verbosity .................. Change a running suite's logging verbosity spawn .......................... Force one or more tasks to spawn their successors stop|shutdown .................. Shut down running suites trigger ........................ Manually trigger or re-trigger a task .. _command-cat-discovery: discovery ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: discovery - Detect running suites. HELP: cylc [discovery] COMMAND help,--help You can abbreviate discovery and COMMAND. The category discovery may be omitted. COMMANDS: check-versions ... Compare cylc versions on task host accounts ping ............. Check that a suite is running scan ............. Scan a host for running suites .. _command-cat-hook: hook ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: hook - Suite and task event hook scripts. HELP: cylc [hook] COMMAND help,--help You can abbreviate hook and COMMAND. The category hook may be omitted. COMMANDS: check-triggering ... A suite shutdown event hook for cylc testing email-suite ........ A suite event hook script that sends email alerts email-task ......... A task event hook script that sends email alerts .. _command-cat-information: information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: information - Interrogate suite definitions and running suites. HELP: cylc [information] COMMAND help,--help You can abbreviate information and COMMAND. The category information may be omitted. COMMANDS: cat-log|log .......................... Print various suite and task log files cat-state ............................ Print the state of tasks from the state dump documentation|browse ................. Display cylc documentation (User Guide etc.) dump ................................. Print the state of tasks in a running suite get-gui-config ....................... Print gcylc configuration items get-host-metrics ..................... Print localhost metric data get-site-config|get-global-config .... Print site/user configuration items get-suite-config|get-config .......... Print suite configuration items get-suite-contact|get-contact ........ Print contact information of a suite server program get-suite-version|get-cylc-version ... Print cylc version of a suite server program gpanel ............................... Internal interface for GNOME 2 panel applet gscan|gsummary ....................... Scan GUI for monitoring multiple suites gui|gcylc ............................ (a.k.a. gcylc) cylc GUI for suite control etc. list|ls .............................. List suite tasks and family namespaces monitor .............................. An in-terminal suite monitor (see also gcylc) review ............................... Start/stop ad-hoc Cylc Review web service server. show ................................. Print task state (prerequisites and outputs etc.) .. _command-cat-license: license ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: license|GPL - Software licensing information (GPL v3.0). HELP: cylc [license|GPL] COMMAND help,--help You can abbreviate license|GPL and COMMAND. The category license|GPL may be omitted. COMMANDS: conditions ... Print the GNU General Public License v3.0 warranty ..... Print the GPLv3 disclaimer of warranty .. _command-cat-preparation: preparation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: preparation - Suite editing, validation, visualization, etc. HELP: cylc [preparation] COMMAND help,--help You can abbreviate preparation and COMMAND. The category preparation may be omitted. COMMANDS: 5to6 ............ Improve the cylc 6 compatibility of a cylc 5 suite file diff|compare .... Compare two suite definitions and print differences edit ............ Edit suite definitions, optionally inlined get-directory ... Retrieve suite source directory paths graph ........... Plot suite dependency graphs and runtime hierarchies graph-diff ...... Compare two suite dependencies or runtime hierarchies jobscript ....... Generate a task job script and print it to stdout list|ls ......... List suite tasks and family namespaces print ........... Print registered suites ref-graph ....... Print text-format "reference graphs" without GTK register ........ Register a suite for use search|grep ..... Search in suite definitions validate ........ Parse and validate suite definitions view ............ View suite definitions, inlined and Jinja2 processed .. _command-cat-task: task ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: task - The task messaging interface. HELP: cylc [task] COMMAND help,--help You can abbreviate task and COMMAND. The category task may be omitted. COMMANDS: jobs-kill .............. (Internal) Kill task jobs jobs-poll .............. (Internal) Retrieve status for task jobs jobs-submit ............ (Internal) Submit task jobs message|task-message ... Report task messages remote-init ............ (Internal) Initialise a task remote remote-tidy ............ (Internal) Tidy a task remote submit|single .......... Run a single task just as its parent suite would .. _command-cat-utility: utility ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none CATEGORY: utility - Cycle arithmetic and templating, etc. HELP: cylc [utility] COMMAND help,--help You can abbreviate utility and COMMAND. The category utility may be omitted. COMMANDS: cycle-point|cyclepoint|datetime|cycletime ... Cycle point arithmetic and filename templating function-run ................................ (Internal) Run a function in the process pool ls-checkpoints .............................. Display task pool etc at given events report-timings .............................. Generate a report on task timing data scp-transfer ................................ Scp-based file transfer for cylc suites suite-state ................................. Query the task states in a suite Commands -------- .. _command-5to6: 5to6 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] 5to6 FILE Suggest changes to a cylc 5 suite file to make it more cylc 6 compatible. This may be a suite.rc file, an include file, or a suite.rc.processed file. By default, print the changed file to stdout. Lines that have been changed are marked with '# UPGRADE'. These marker comments are purely for your own information and should not be included in any changes you make. In particular, they may break continuation lines. Lines with '# UPGRADE CHANGE' have been altered. Lines with '# UPGRADE ... INFO' indicate that manual change is needed. As of cylc 7, 'cylc validate' will no longer print out automatic dependency section translations. At cylc 6 versions of cylc, 'cylc validate' will show start-up/mixed async replacement R1* section(s). The validity of these can be highly dependent on the initial cycle point choice (e.g. whether it is T00 or T12). This command works best for hour-based cycling - it will always convert e.g. 'foo[T-6]' to 'foo[-PT6H]', even where this is in a monthly or yearly cycling section graph. This command is an aid, and is not an auto-upgrader or a substitute for reading the documentation. The suggested changes must be understood and checked by hand. Example usage: # Print out a file path (FILE) with suggested changes to stdout. cylc 5to6 FILE # Replace the file with the suggested changes file. cylc 5to6 FILE > FILE # Save a copy of the changed file. cylc 5to6 FILE > FILE.5to6 # Show the diff of the changed file vs the original file. diff - <(cylc 5to6 FILE) all:FAM -> all:task -> tag:root -> tag:FAM -> tag:task Broadcasts persist, even across suite restarts, until they expire when their target cycle point is older than the oldest current in the suite, or until they are explicitly cancelled with this command. All-cycle broadcasts do not expire. For each task the final effect of all broadcasts to all namespaces is computed on the fly just prior to job submission. The --cancel and --clear options simply cancel (remove) active broadcasts, they do not act directly on the final task-level result. Consequently, for example, you cannot broadcast to "all cycles except Tn" with an all-cycle broadcast followed by a cancel to Tn (there is no direct broadcast to Tn to cancel); and you cannot broadcast to "all members of FAMILY except member_n" with a general broadcast to FAMILY followed by a cancel to member_n (there is no direct broadcast to member_n to cancel). To broadcast a variable to all tasks (quote items with internal spaces): % cylc broadcast -s "[environment]VERSE = the quick brown fox" REG To do the same with a file: % cat >'broadcast.rc' <<'__RC__' % [environment] % VERSE = the quick brown fox % __RC__ % cylc broadcast -F 'broadcast.rc' REG To cancel the same broadcast: % cylc broadcast --cancel "[environment]VERSE" REG If -F FILE was used, the same file can be used to cancel the broadcast: % cylc broadcast -G 'broadcast.rc' REG Use -d/--display to see active broadcasts. Multiple --cancel options or multiple --set and --set-file options can be used on the same command line. Multiple --set and --set-file options are cumulative. The --set-file=FILE option can be used when broadcasting multiple values, or when the value contains newline or other metacharacters. If FILE is "-", read from standard input. Broadcast cannot change [runtime] inheritance. See also 'cylc reload' - reload a modified suite definition at run time. Arguments: REG Suite name Options: -h, --help show this help message and exit -p CYCLE_POINT, --point=CYCLE_POINT Target cycle point. More than one can be added. Defaults to '*' with --set and --cancel, and nothing with --clear. -n NAME, --namespace=NAME Target namespace. Defaults to 'root' with --set and --cancel, and nothing with --clear. -s [SEC]ITEM=VALUE, --set=[SEC]ITEM=VALUE A [runtime] config item and value to broadcast. -F FILE, --set-file=FILE, --file=FILE File with config to broadcast. Can be used multiple times. -c [SEC]ITEM, --cancel=[SEC]ITEM An item-specific broadcast to cancel. -G FILE, --cancel-file=FILE File with broadcasts to cancel. Can be used multiple times. -C, --clear Cancel all broadcasts, or with -p/--point, -n/--namespace, cancel all broadcasts to targeted namespaces and/or cycle points. Use "-C -p '*'" to cancel all all-cycle broadcasts without canceling all specific-cycle broadcasts. -e CYCLE_POINT, --expire=CYCLE_POINT Cancel any broadcasts that target cycle points earlier than, but not inclusive of, CYCLE_POINT. -d, --display Display active broadcasts. -k TASKID, --display-task=TASKID Print active broadcasts for a given task (NAME.CYCLE_POINT). -b, --box Use unicode box characters with -d, -k. -r, --raw With -d/--display or -k/--display-task, write out the broadcast config structure in raw Python form. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-cat-log: cat-log ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] cat-log|log [OPTIONS] REG [TASK-ID] Print, view-in-editor, or tail-follow content, print path, or list directory, of local or remote task job and suite server logs. Batch-system view commands (e.g. 'qcat') are used if defined in global config and the job is running. For standard log types use the short-cut option argument or full filename (e.g. for job stdout "-f o" or "-f job.out" will do). To list the local job log directory of a remote task, choose "-m l" (directory list mode) and a local file, e.g. "-f a" (job-activity.log). If remote job logs are retrieved to the suite host on completion (global config '[JOB-HOST]retrieve job logs = True') and the job is not currently running, the local (retrieved) log will be accessed unless '-o/--force-remote' is used. Custom job logs (written to $CYLC_TASK_LOG_DIR on the job host) are available from the GUI if listed in 'extra log files' in the suite definition. The file name must be given here, but can be discovered with '--mode=l' (list-dir). The correct cycle point format of the suite must be for task job logs. Note the --host/user options are not needed to view remote job logs. They are the general command reinvocation options for sites using ssh-based task messaging. Arguments: REG Suite name [TASK-ID] Task ID Options: -h, --help show this help message and exit -f LOG, --file=LOG Job log: a(job-activity.log), e(job.err), d(job- edit.diff), j(job), o(job.out), s(job.status), x(job.xtrace); default o(out). Or for custom (and standard) job logs. -m MODE, --mode=MODE Mode: c(cat), e(edit), d(print-dir), l(list-dir), p(print), t(tail). Default c(cat). -r INT, --rotation=INT Suite log integer rotation number. 0 for current, 1 for next oldest, etc. -o, --force-remote View remote logs remotely even if they have been retrieved to the suite host (default False). -s INT, -t INT, --submit-number=INT, --try-number=INT Job submit number (default=NN, i.e. latest). -g, --geditor edit mode: use your configured GUI editor. --remote-arg=REMOTE_ARGS (for internal use: continue processing on job host) --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-cat-state: cat-state ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] cat-state [OPTIONS] REG Print the suite state in the old state dump file format to stdout. This command is deprecated; use "cylc ls-checkpoints" instead. Arguments: REG Suite name Options: -h, --help show this help message and exit -d, --dump Use the same display format as the 'cylc dump' command. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-check-software: check-software ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none cylc [admin] check-software [MODULES] Check for Cylc external software dependencices, including minimum versions. With no arguments, prints a table of results for all core & optional external module requirements, grouped by functionality. With module argument(s), provides an exit status for the collective result of checks on those modules. Arguments: [MODULES] Modules to include in the software check, which returns a zero ('pass') or non-zero ('fail') exit status, where the integer is equivalent to the number of modules failing. Run the bare check-software command to view the full list of valid module arguments (lower-case equivalents accepted). .. _command-check-triggering: check-triggering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none cylc [hook] check-triggering ARGS This is a cylc shutdown event handler that compares the newly generated suite log with a previously generated reference log "reference.log" stored in the suite definition directory. Currently it just compares runtime triggering information, disregarding event order and timing, and fails the suite if there is any difference. This should be sufficient to verify correct scheduling of any suite that is not affected by different run-to-run conditional triggering. 1) run your suite with "cylc run --generate-reference-log" to generate the reference log with resolved triggering information. Check manually that the reference run was correct. 2) run reference tests with "cylc run --reference-test" - this automatically sets the shutdown event handler along with a suite timeout and "abort if shutdown handler fails", "abort on timeout", and "abort if any task fails". Reference tests can use any run mode: * simulation mode - tests that scheduling is equivalent to the reference * dummy mode - also tests that task hosting, job submission, job script evaluation, and cylc messaging are not broken. * live mode - tests everything (but takes longer with real tasks!) If any task fails, or if cylc itself fails, or if triggering is not equivalent to the reference run, the test will abort with non-zero exit status - so reference tests can be used as automated tests to check that changes to cylc have not broken your suites. .. _command-check-versions: check-versions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [discovery] check-versions [OPTIONS] SUITE Check the version of cylc invoked on each of SUITE's task host accounts when CYLC_VERSION is set to *the version running this command line tool*. Different versions are reported but are not considered an error unless the -e|--error option is specified, because different cylc versions from 6.0.0 onward should at least be backward compatible. It is recommended that cylc versions be installed in parallel and access configured via the cylc version wrapper as described in the cylc INSTALL file and User Guide. This must be done on suite and task hosts. Users then get the latest installed version by default, or (like tasks) a particular version if $CYLC_VERSION is defined. Use -v/--verbose to see the command invoked to determine the remote version (all remote cylc command invocations will be of the same form, which may be site dependent -- see cylc global config documentation. Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit -e, --error Exit with error status if 7.9.3 is not available on all remote accounts. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-checkpoint: checkpoint ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] checkpoint [OPTIONS] REG CHECKPOINT-NAME Tell suite to checkpoint its current state. Arguments: REG Suite name CHECKPOINT-NAME Checkpoint name Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-client: client ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc client [OPTIONS] METHOD [REG] (This command is for internal use.) Invoke HTTP(S) client, expect JSON from STDIN for keyword arguments. Use the -n option if client function requires no keyword arguments. Arguments: METHOD Network API function name [REG] Suite name Options: -h, --help show this help message and exit -n, --no-input Do not read from STDIN, assume null input --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-conditions: conditions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [license] warranty [--help] Cylc is release under the GNU General Public License v3.0 This command prints the GPL v3.0 license in full. Options: --help Print this usage message. .. _command-cycle-point: cycle-point ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [util] cycle-point [OPTIONS] [POINT] Cycle point date-time offset computation, and filename templating. Filename templating replaces elements of a template string with corresponding elements of the current or given cycle point. Use ISO 8601 or posix date-time format elements: % cylc cyclepoint 2010080T00 --template foo-CCYY-MM-DD-Thh.nc foo-2010-08-08-T00.nc % cylc cyclepoint 2010080T00 --template foo-%Y-%m-%d-T%H.nc foo-2010-08-08-T00.nc Other examples: 1) print offset from an explicit cycle point: % cylc [util] cycle-point --offset-hours=6 20100823T1800Z 20100824T0000Z 2) print offset from $CYLC_TASK_CYCLE_POINT (as in suite tasks): % export CYLC_TASK_CYCLE_POINT=20100823T1800Z % cylc cycle-point --offset-hours=-6 20100823T1200Z 3) cycle point filename templating, explicit template: % export CYLC_TASK_CYCLE_POINT=2010-08 % cylc cycle-point --offset-years=2 --template=foo-CCYY-MM.nc foo-2012-08.nc 4) cycle point filename templating, template in a variable: % export CYLC_TASK_CYCLE_POINT=2010-08 % export MYTEMPLATE=foo-CCYY-MM.nc % cylc cycle-point --offset-years=2 --template=MYTEMPLATE foo-2012-08.nc Arguments: [POINT] ISO8601 date-time, default=$CYLC_TASK_CYCLE_POINT Options: -h, --help show this help message and exit --offset-hours=HOURS Add N hours to CYCLE (may be negative) --offset-days=DAYS Add N days to CYCLE (N may be negative) --offset-months=MONTHS Add N months to CYCLE (N may be negative) --offset-years=YEARS Add N years to CYCLE (N may be negative) --offset=ISO_OFFSET Add an ISO 8601-based interval representation to CYCLE --equal=POINT2 Succeed if POINT2 is equal to POINT (format agnostic). --template=TEMPLATE Filename template string or variable --time-zone=TEMPLATE Control the formatting of the result's timezone e.g. (Z, +13:00, -hh --num-expanded-year-digits=NUMBER Specify a number of expanded year digits to print in the result --print-year Print only CCYY of result --print-month Print only MM of result --print-day Print only DD of result --print-hour Print only hh of result -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-diff: diff ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] diff|compare [OPTIONS] SUITE1 SUITE2 Compare two suite definitions and display any differences. Differencing is done after parsing the suite.rc files so it takes account of default values that are not explicitly defined, it disregards the order of configuration items, and it sees any include-file content after inlining has occurred. Files in the suite bin directory and other sub-directories of the suite definition directory are not currently differenced. Arguments: SUITE1 Suite name or path SUITE2 Suite name or path Options: -h, --help show this help message and exit -n, --nested print suite.rc section headings in nested form. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-documentation: documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] documentation|browse [OPTIONS] [TARGET] View documentation in the browser, as per Cylc global config. % cylc doc [OPTIONS] View local or internet [--www] Cylc documentation URLs. % cylc doc [-t TASK] SUITE View suite or task documentation, if URLs are specified in the suite. This parses the suite definition to extract the requested URL. Note that suite server programs also hold suite URLs for access from the Cylc GUI. Arguments: [TARGET] File or suite name Options: -h, --help show this help message and exit -g, --guides Open the HTML (User & Suite Design) Guides directly. -w, --www Open the cylc internet homepage -t TASK_NAME, --task=TASK_NAME Browse task documentation URLs. -s, --stdout Just print the URL to stdout. --debug Print exception traceback on error. --url=URL URL to view in your configured browser. -v, --verbose Verbose output mode. .. _command-dump: dump ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] dump [OPTIONS] REG Print state information (e.g. the state of each task) from a running suite. For small suites 'watch cylc [info] dump SUITE' is an effective non-GUI real time monitor (but see also 'cylc monitor'). For more information about a specific task, such as the current state of its prerequisites and outputs, see 'cylc [info] show'. Examples: Display the state of all running tasks, sorted by cycle point: % cylc [info] dump --tasks --sort SUITE | grep running Display the state of all tasks in a particular cycle point: % cylc [info] dump -t SUITE | grep 2010082406 Arguments: REG Suite name Options: -h, --help show this help message and exit -g, --global Global information only. -t, --tasks Task states only. -r, --raw, --raw-format Display raw format. -s, --sort Task states only; sort by cycle point instead of name. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). .. _command-edit: edit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] edit [OPTIONS] SUITE Edit suite definitions without having to move to their directory locations, and with optional reversible inlining of include-files. Note that Jinja2 suites can only be edited in raw form but the processed version can be viewed with 'cylc [prep] view -p'. 1/cylc [prep] edit SUITE Change to the suite definition directory and edit the suite.rc file. 2/ cylc [prep] edit -i,--inline SUITE Edit the suite with include-files inlined between special markers. The original suite.rc file is temporarily replaced so that the inlined version is "live" during editing (i.e. you can run suites during editing and cylc will pick up changes to the suite definition). The inlined file is then split into its constituent include-files again when you exit the editor. Include-files can be nested or multiply-included; in the latter case only the first inclusion is inlined (this prevents conflicting changes made to the same file). 3/ cylc [prep] edit --cleanup SUITE Remove backup files left by previous INLINED edit sessions. INLINED EDITING SAFETY: The suite.rc file and its include-files are automatically backed up prior to an inlined editing session. If the editor dies mid-session just invoke 'cylc edit -i' again to recover from the last saved inlined file. On exiting the editor, if any of the original include-files are found to have changed due to external intervention during editing you will be warned and the affected files will be written to new backups instead of overwriting the originals. Finally, the inlined suite.rc file is also backed up on exiting the editor, to allow recovery in case of accidental corruption of the include-file boundary markers in the inlined file. The edit process is spawned in the foreground as follows: % suite.rc Where is defined in the cylc site/user config files. See also 'cylc [prep] view'. Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit -i, --inline Edit with include-files inlined as described above. --cleanup Remove backup files left by previous inlined edit sessions. -g, --gui Force use of the configured GUI editor. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner .. _command-email-suite: email-suite ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [hook] email-suite EVENT SUITE MESSAGE THIS COMMAND IS OBSOLETE - use built-in email event hooks. This is a simple suite event hook script that sends an email. The command line arguments are supplied automatically by cylc. For example, to get an email alert when a suite shuts down: # SUITE.RC [cylc] [[environment]] MAIL_ADDRESS = foo@bar.baz.waz [[events]] shutdown handler = cylc email-suite See the Suite.rc Reference (Cylc User Guide) for more information on suite and task event hooks and event handler scripts. .. _command-email-task: email-task ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [hook] email-task EVENT SUITE TASKID MESSAGE THIS COMMAND IS OBSOLETE - use built-in email event hooks. A simple task event hook handler script that sends an email. The command line arguments are supplied automatically by cylc. For example, to get an email alert whenever any task fails: # SUITE.RC [cylc] [[environment]] MAIL_ADDRESS = foo@bar.baz.waz [runtime] [[root]] [[[events]]] failed handler = cylc email-task See the Suite.rc Reference (Cylc User Guide) for more information on suite and task event hooks and event handler scripts. .. _command-ext-trigger: ext-trigger ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] ext-trigger [OPTIONS] REG MSG ID Report an external event message to a suite server program. It is expected that a task in the suite has registered the same message as an external trigger - a special prerequisite to be satisifed by an external system, via this command, rather than by triggering off other tasks. The ID argument should uniquely distinguish one external trigger event from the next. When a task's external trigger is satisfied by an incoming message, the message ID is broadcast to all downstream tasks in the cycle point as $CYLC_EXT_TRIGGER_ID so that they can use it - e.g. to identify a new data file that the external triggering system is responding to. Use the retry options in case the target suite is down or out of contact. The suite passphrase must be installed in $HOME/.cylc//. Note: to manually trigger a task use 'cylc trigger', not this command. Arguments: REG Suite name MSG External trigger message ID Unique trigger ID Options: -h, --help show this help message and exit --max-tries=INT Maximum number of send attempts (default 5). --retry-interval=SEC Delay in seconds before retrying (default 10.0). --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-function-run: function-run ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none USAGE: cylc function-run INTERNAL USE (asynchronous external trigger function execution) Run a Python function "(*args, **kwargs)" in the process pool. It must be defined in a module of the same name. Positional and keyword arguments must be passed in as JSON strings. is the suite source dir, needed to find local xtrigger modules. .. _command-get-directory: get-directory ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] get-directory REG Retrieve and print the source directory location of suite REG. Here's an easy way to move to a suite source directory: $ cd $(cylc get-dir REG). Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner .. _command-get-gui-config: get-gui-config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [admin] get-gui-config [OPTIONS] Print gcylc configuration settings. By default all settings are printed. For specific sections or items use -i/--item and wrap parent sections in square brackets: cylc get-gui-config --item '[themes][default]succeeded' Multiple items can be specified at once. Options: -h, --help show this help message and exit -i [SEC...]ITEM, --item=[SEC...]ITEM Item or section to print (multiple use allowed). --sparse Only print items explicitly set in the config files. -p, --python Print native Python format. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-get-host-metrics: get-host-metrics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc get-host-metrics [OPTIONS] Get metrics for localhost, in the form of a JSON structure with top-level keys as requested via the OPTIONS: 1. --load 1, 5 and 15 minute load averages (as keys) from the 'uptime' command. 2. --memory Total free RAM memory, in kilobytes, from the 'free -k' command. 3. --disk-space=PATH / --disk-space=PATH1,PATH2,PATH3 (etc) Available disk space from the 'df -Pk' command, in kilobytes, for one or more valid mount directory PATHs (as listed under 'Mounted on') within the filesystem of localhost. Multiple PATH options can be specified via a comma-delimited list, each becoming a key under the top-level disk space key. If no options are specified, --load and --memory are invoked by default. Options: -h, --help show this help message and exit -l, --load 1, 5 and 15 minute load averages from the 'uptime' command. -m, --memory Total memory not in use by the system, buffer or cache, in KB, from '/proc/meminfo'. --disk-space=DISK Available disk space, in KB, from the 'df -Pk' command. .. _command-get-site-config: get-site-config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [admin] get-site-config [OPTIONS] Print cylc site/user configuration settings. By default all settings are printed. For specific sections or items use -i/--item and wrap parent sections in square brackets: cylc get-site-config --item '[editors]terminal' Multiple items can be specified at once. Options: -h, --help show this help message and exit -i [SEC...]ITEM, --item=[SEC...]ITEM Item or section to print (multiple use allowed). --sparse Only print items explicitly set in the config files. -p, --python Print native Python format. --print-run-dir Print the configured cylc run directory. --print-site-dir Print the cylc site configuration directory location. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-get-suite-config: get-suite-config ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] get-suite-config [OPTIONS] SUITE Print parsed suite configuration items, after runtime inheritance. By default all settings are printed. For specific sections or items use -i/--item and wrap sections in square brackets, e.g.: cylc get-suite-config --item '[scheduling]initial cycle point' Multiple items can be retrieved at once. By default, unset values are printed as an empty string, or (for historical reasons) as "None" with -o/--one-line. These defaults can be changed with the -n/--null-value option. Example: |# SUITE.RC |[runtime] | [[modelX]] | [[[environment]]] | FOO = foo | BAR = bar $ cylc get-suite-config --item=[runtime][modelX][environment]FOO SUITE foo $ cylc get-suite-config --item=[runtime][modelX][environment] SUITE FOO = foo BAR = bar $ cylc get-suite-config --item=[runtime][modelX] SUITE ... [[[environment]]] FOO = foo BAR = bar ... Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit -i [SEC...]ITEM, --item=[SEC...]ITEM Item or section to print (multiple use allowed). -r, --sparse Only print items explicitly set in the config files. -p, --python Print native Python format. -a, --all-tasks For [runtime] items (e.g. --item='script') report values for all tasks prefixed by task name. -n STRING, --null-value=STRING The string to print for unset values (default nothing). -m, --mark-up Prefix each line with '!cylc!'. -o, --one-line Print multiple single-value items at once. -t, --tasks Print the suite task list [DEPRECATED: use 'cylc list SUITE']. -u RUN_MODE, --run-mode=RUN_MODE Get config for suite run mode. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-get-suite-contact: get-suite-contact ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] get-suite-contact [OPTIONS] REG Print contact information of running suite REG. Arguments: REG Suite name Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-get-suite-version: get-suite-version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] get-suite-version [OPTIONS] REG Interrogate running suite REG to find what version of cylc is running it. To find the version you've invoked at the command line see "cylc version". Arguments: REG Suite name Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-gpanel: gpanel ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc gpanel [OPTIONS] This is a cylc scan panel applet for monitoring running suites on a set of hosts in GNOME 2. To install this applet, run "cylc gpanel --install" and follow the instructions that it gives you. This applet can be tested using the --test option. To customize themes, copy $CYLC_DIR/etc/gcylc.rc.eg to $HOME/.cylc/gcylc.rc and follow the instructions in the file. To configure default suite hosts, edit "[suite servers]scan hosts" in your global.rc file. Options: -h, --help show this help message and exit --compact Switch on compact mode at runtime. --install Install the panel applet. --test Run in a standalone window. .. _command-graph: graph ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: 1/ cylc [prep] graph [OPTIONS] SUITE [START[STOP]] Plot the suite.rc dependency graph for SUITE. 2/ cylc [prep] graph [OPTIONS] -f,--file FILE Plot the specified dot-language graph file. 3/ cylc [prep] graph [OPTIONS] --reference SUITE [START[STOP]] Print out a reference format for the dependencies in SUITE. 4/ cylc [prep] graph [OPTIONS] --output-file FILE SUITE Plot SUITE dependencies to a file FILE with a extension-derived format. If FILE endswith ".png", output in PNG format, etc. Plot suite dependency graphs in an interactive graph viewer, or (with "--output-file") directly to image file. See also "cylc ref-graph" to generate the plain text "reference" graph format without the need for PyGTK to be installed. If START is given it overrides "[visualization] initial cycle point" to determine the start point of the graph, which defaults to the suite initial cycle point. If STOP is given it overrides "[visualization] final cycle point" to determine the end point of the graph, which defaults to the graph start point plus "[visualization] number of cycle points" (which defaults to 3). The graph start and end points are adjusted up and down to the suite initial and final cycle points, respectively, if necessary. The "Save" button generates an image of the current view, of format (e.g. png, svg, jpg, eps) determined by the filename extension. If the chosen format is not available a dialog box will show those that are available. If the optional output filename is specified, the viewer will not open and a graph will be written directly to the file. GRAPH VIEWER CONTROLS: * Center on a node: left-click. * Pan view: left-drag. * Zoom: +/- buttons, mouse-wheel, or ctrl-left-drag. * Box zoom: shift-left-drag. * "Best Fit" and "Normal Size" buttons. * Left-to-right graphing mode toggle button. * "Ignore suicide triggers" button. * "Save" button: save an image of the view. Family (namespace) grouping controls: Toolbar: * "group" - group all families up to root. * "ungroup" - recursively ungroup all families. Right-click menu: * "group" - close this node's parent family. * "ungroup" - open this family node. * "recursive ungroup" - ungroup all families below this node. Arguments: [SUITE] Suite name or path [START] Initial cycle point (default: suite initial point) [STOP] Final cycle point (default: initial + 3 points) Options: -h, --help show this help message and exit -u, --ungrouped Start with task families ungrouped (the default is grouped). -n, --namespaces Plot the suite namespace inheritance hierarchy (task run time properties). -f FILE, --file=FILE View a specific dot-language graphfile. --filter=NODE_NAME_PATTERN Filter out one or many nodes. -O FILE, --output-file=FILE Output to a specific file, with a format given by --output-format or extrapolated from the extension. '-' implies stdout in plain format. --output-format=FORMAT Specify a format for writing out the graph to --output-file e.g. png, svg, jpg, eps, dot. 'ref' is a special sorted plain text format for comparison and reference purposes. -r, --reference Output in a sorted plain text format for comparison purposes. If not given, assume --output-file=-. --show-suicide Show suicide triggers. They are not shown by default, unless toggled on with the tool bar button. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-graph-diff: graph-diff ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc graph-diff [OPTIONS] SUITE1 SUITE2 -- [GRAPH_OPTIONS_ARGS] Difference 'cylc graph --reference' output for SUITE1 and SUITE2. OPTIONS: Use '-g' to launch a graphical diff utility. Use '--diff-cmd=MY_DIFF_CMD' to use a custom diff tool. SUITE1, SUITE2: Suite names to compare. GRAPH_OPTIONS_ARGS: Options and arguments passed directly to cylc graph. .. _command-gscan: gscan ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc gscan [OPTIONS] This is the cylc scan gui for monitoring running suites on a set of hosts. To customize themes copy $CYLC_DIR/etc/gcylc.rc.eg to ~/.cylc/gcylc.rc and follow the instructions in the file. Arguments: [HOSTS ...] Hosts to scan instead of the configured hosts. Options: -h, --help show this help message and exit -a, --all Scan all port ranges in known hosts. -n PATTERN, --name=PATTERN List suites with name matching PATTERN (regular expression). Defaults to any name. Can be used multiple times. -o PATTERN, --suite-owner=PATTERN List suites with owner matching PATTERN (regular expression). Defaults to just your own suites. Can be used multiple times. --comms-timeout=SEC Set a timeout for network connections to each running suite. The default is 5 seconds. --interval=SECONDS Time interval (in seconds) between full updates --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). .. _command-gui: gui ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc gui [OPTIONS] [REG] [USER_AT_HOST] gcylc [OPTIONS] [REG] [USER_AT_HOST] This is the cylc Graphical User Interface. The USER_AT_HOST argument allows suite selection by 'cylc scan' output: cylc gui $(cylc scan | grep ) Local suites can be opened and switched between from within gcylc. To connect to running remote suites (whose passphrase you have installed) you must currently use --host and/or --user on the gcylc command line. Available task state color themes are shown under the View menu. To customize themes copy /etc/gcylc.rc.eg to ~/.cylc/gcylc.rc and follow the instructions in the file. To see current configuration settings use "cylc get-gui-config". In the graph view, View -> Options -> "Write Graph Frames" writes .dot graph files to the suite share directory (locally, for a remote suite). These can be processed into a movie by $CYLC_DIR/dev/bin/live-graph-movie.sh=. Arguments: [REG] Suite name [USER_AT_HOST] user@host:port, shorthand for --user, --host & --port. Options: -h, --help show this help message and exit -r, --restricted Restrict display to 'active' task states: submitted, submit-failed, submit-retrying, running, failed, retrying; and disable the graph view. This may be needed for very large suites. The state summary icons in the status bar still represent all task proxies. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-hold: hold ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] hold [OPTIONS] REG [TASK_GLOB ...] Hold a suite or tasks: cylc hold REG - hold a suite cylc hold REG TASK_GLOB ... - hold one or more tasks in a suite Held tasks do not submit their jobs even if ready to run. See also 'cylc [control] release'. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit --after=CYCLE_POINT Hold whole suite AFTER this cycle point. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-import-examples: import-examples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc import-examples DIR Copy the cylc example suites to DIR and register them for use under the GROUP suite name group. Arguments: DIR destination directory .. _command-insert: insert ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] insert [OPTIONS] TASK_GLOB [...] Insert new task proxies into the task pool of a running suite, e.g. to allow re-triggering of an earlier task that has already been removed from the pool. NOTE: inserted cycling tasks cycle on as normal, even if another instance of the same task exists at a later cycle (instances of the same task at different cycles can coexist, but a newly spawned task will not be added to the pool if it catches up to another task with the same ID). See also 'cylc submit', for running tasks independently of the scheduler. TASK_GLOB matches task or family names, to insert task instances into the pool at a specific given cycle point. (NOTE this differs from other commands which match name and cycle point patterns against instances already in the pool). * CYCLE-POINT/TASK-NAME-GLOB * CYCLE-POINT/FAMILY-NAME-GLOB * TASK-NAME-GLOB.CYCLE-POINT * FAMILY-NAME-GLOB.CYCLE-POINT For example, to match, within the given cycle point (e.g. '20200202T0000Z'): * all tasks: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks named model_N for some character N: '20200202T0000Z/model_?' or 'model_?.20200202T0000Z' * all tasks in 'BAR' family: '20200202T0000Z/BAR' or 'BAR.20200202T0000Z' * all tasks in 'BAR' or 'BAZ' families: '20200202T0000Z/BA[RZ]' or 'BA[RZ].20200202T0000Z' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name TASK_GLOB [...] Task match pattern(s) Options: -h, --help show this help message and exit --stop-point=CYCLE_POINT, --remove-point=CYCLE_POINT Optional hold/stop cycle point for inserted task. --no-check Add task even if the provided cycle point is not valid for the given task. --no-multitask-compat Disallow backward compatible multitask interface. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-jobs-kill: jobs-kill ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] jobs-kill JOB-LOG-ROOT [JOB-LOG-DIR ...] (This command is for internal use. Users should use "cylc kill".) Read job status files to obtain the names of the batch systems and the job IDs in the systems. Invoke the relevant batch system commands to ask the batch systems to terminate the jobs. Arguments: JOB-LOG-ROOT The log/job sub-directory for the suite [JOB-LOG-DIR ...] A point/name/submit_num sub-directory Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-jobs-poll: jobs-poll ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] jobs-poll JOB-LOG-ROOT [JOB-LOG-DIR ...] (This command is for internal use. Users should use "cylc poll".) Read job status files to obtain the statuses of the jobs. If necessary, Invoke the relevant batch system commands to ask the batch systems for more statuses. Arguments: JOB-LOG-ROOT The log/job sub-directory for the suite [JOB-LOG-DIR ...] A point/name/submit_num sub-directory Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-jobs-submit: jobs-submit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] jobs-submit JOB-LOG-ROOT [JOB-LOG-DIR ...] (This command is for internal use. Users should use "cylc submit".) Submit task jobs to relevant batch systems. On a remote job host, this command reads the job files from STDIN. Arguments: JOB-LOG-ROOT The log/job sub-directory for the suite [JOB-LOG-DIR ...] A point/name/submit_num sub-directory Options: -h, --help show this help message and exit --remote-mode Is this being run on a remote job host? --utc-mode (for remote mode) is the suite running in UTC mode? --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-jobscript: jobscript ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] jobscript [OPTIONS] REG TASK Generate a task job script and print it to stdout. Here's how to capture the script in the vim editor: % cylc jobscript REG TASK | vim - Emacs unfortunately cannot read from stdin: % cylc jobscript REG TASK > tmp.sh; emacs tmp.sh This command wraps 'cylc [control] submit --dry-run'. Other options (e.g. for suite host and owner) are passed through to the submit command. Options: -h, --help Print this usage message. -e --edit Open the jobscript in a CLI text editor. -g --gedit Open the jobscript in a GUI text editor. --plain Don't print the "Task Job Script Generated message." (see also 'cylc submit --help') Arguments: REG Registered suite name. TASK Task ID (NAME.CYCLE_POINT) .. _command-kill: kill ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] kill [OPTIONS] REG [TASK_GLOB ...] Kill jobs of active tasks and update their statuses accordingly. cylc kill REG TASK_GLOB ... - kill one or more active tasks cylc kill REG - kill all active tasks in the suite Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-list: list ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info|prep] list|ls [OPTIONS] SUITE Print runtime namespace names (tasks and families), the first-parent inheritance graph, or actual tasks for a given cycle range. The first-parent inheritance graph determines the primary task family groupings that are collapsible in gcylc suite views and the graph viewer tool. To visualize the full multiple inheritance hierarchy use: 'cylc graph -n'. Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit -a, --all-tasks Print all tasks, not just those used in the graph. -n, --all-namespaces Print all runtime namespaces, not just tasks. -m, --mro Print the linear "method resolution order" for each namespace (the multiple-inheritance precedence order as determined by the C3 linearization algorithm). -t, --tree Print the first-parent inheritance hierarchy in tree form. -b, --box With -t/--tree, using unicode box characters. Your terminal must be able to display unicode characters. -w, --with-titles Print namespaces titles too. -p START[,STOP], --points=START[,STOP] Print actual task IDs from the START [through STOP] cycle points. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-ls-checkpoints: ls-checkpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] ls-checkpoints [OPTIONS] REG [ID ...] In the absence of arguments and the --all option, list checkpoint IDs, their time and events. Otherwise, display the latest and/or the checkpoints of suite parameters, task pool and broadcast states in the suite runtime database. Arguments: REG Suite name [ID ...] Checkpoint ID (default=latest) Options: -h, --help show this help message and exit -a, --all Display data of all available checkpoints. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-message: message ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [task] message [OPTIONS] -- [REG] [TASK-JOB] [[SEVERITY:]MESSAGE ...] Record task job messages. Send task job messages to: - The job stdout/stderr. - The job status file, if there is one. - The suite server program, if communication is possible. Task jobs use this command to record and report status such as success and failure. Applications run by task jobs can use this command to report messages and to report registered task outputs. Messages can be specified as arguments. A '-' indicates that the command should read messages from STDIN. When reading from STDIN, multiple messages are separated by empty lines. Examples: Single message as an argument: % cylc message -- "${CYLC_SUITE_NAME}" "${CYLC_TASK_JOB}" 'Hello world!' Multiple messages as arguments: % cylc message -- "${CYLC_SUITE_NAME}" "${CYLC_TASK_JOB}" \ 'Hello world!' 'Hi' 'WARNING:Hey!' Multiple messages on STDIN: % cylc message -- "${CYLC_SUITE_NAME}" "${CYLC_TASK_JOB}" - <<'__STDIN__' % Hello % world! % % Hi % % WARNING:Hey! %__STDIN__ Note "${CYLC_SUITE_NAME}" and "${CYLC_TASK_JOB}" are made available in task job environments - you do not need to write their actual values in task scripting. Each message can be prefixed with a severity level using the syntax 'SEVERITY: MESSAGE'. The default message severity is INFO. The --severity=SEVERITY option can be used to set the default severity level for all unprefixed messages. Note: to abort a job script with a custom error message, use cylc__job_abort: cylc__job_abort 'message...' (For technical reasons this is a shell function, not a cylc sub-command.) For backward compatibility, if number of arguments is less than or equal to 2, the command assumes the classic interface, where all arguments are messages. Otherwise, the first 2 arguments are assumed to be the suite name and the task job identifier. Arguments: [REG] Suite name [TASK-JOB] Task job identifier CYCLE/TASK_NAME/SUBMIT_NUM [[SEVERITY:]MESSAGE ...] Messages Options: -h, --help show this help message and exit -s SEVERITY, -p SEVERITY, --severity=SEVERITY, --priority=SEVERITY Set severity levels for messages that do not have one --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-monitor: monitor ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] monitor [OPTIONS] REG [USER_AT_HOST] A terminal-based live suite monitor. Exit with 'Ctrl-C'. The USER_AT_HOST argument allows suite selection by 'cylc scan' output: cylc monitor $(cylc scan | grep ) Arguments: REG Suite name [USER_AT_HOST] user@host:port, shorthand for --user, --host & --port. Options: -h, --help show this help message and exit -a, --align Align task names. Only useful for small suites. -r, --restricted Restrict display to active task states. This may be useful for monitoring very large suites. The state summary line still reflects all task proxies. -s ORDER, --sort=ORDER Task sort order: "definition" or "alphanumeric".The default is definition order, as determined by global config. (Definition order is the order that tasks appear under [runtime] in the suite definition). -o, --once Show a single view then exit. -u, --runahead Display task proxies in the runahead pool (off by default). -i SECONDS, --interval=SECONDS Interval between suite state retrievals, in seconds (default 1). --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). .. _command-nudge: nudge ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] nudge [OPTIONS] REG Cause the cylc task processing loop to be invoked in a running suite. This happens automatically when the state of any task changes such that task processing (dependency negotation etc.) is required, or if a clock-trigger task is ready to run. The main reason to use this command is to update the "estimated time till completion" intervals shown in the tree-view suite control GUI, during periods when nothing else is happening. Arguments: REG Suite name Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-ping: ping ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [discovery] ping [OPTIONS] REG [TASK] If suite REG is running or TASK in suite REG is currently running, exit with success status, else exit with error status. Arguments: REG Suite name [TASK] Task NAME.CYCLE_POINT Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-poll: poll ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] poll [OPTIONS] REG [TASK_GLOB ...] Poll (query) task jobs to verify and update their statuses. cylc poll REG - poll all active tasks cylc poll REG TASK_GLOB ... - poll multiple active tasks or families Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit -s, --succeeded Allow polling of succeeded tasks. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-print: print ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] print [OPTIONS] [REGEX] Print registered (installed) suites. Note on result filtering: (a) The filter patterns are Regular Expressions, not shell globs, so the general wildcard is '.*' (match zero or more of anything), NOT '*'. (b) For printing purposes there is an implicit wildcard at the end of each pattern ('foo' is the same as 'foo/*'); use the string end marker to prevent this ('foo$' matches only literal 'foo'). Arguments: [REGEX] Suite name regular expression pattern Options: -h, --help show this help message and exit -t, --tree Print suites in nested tree form. -b, --box Use unicode box drawing characters in tree views. -a, --align Align columns. -x don't print suite definition directory paths. -y Don't print suite titles. --fail Fail (exit 1) if no matching suites are found. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-profile-battery: profile-battery ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc profile-battery [-e [EXPERIMENT ...]] [-v [VERSION ...]] Run profiling experiments against different versions of cylc. A list of experiments can be specified after the -e flag, if not provided the experiment "complex" will be chosen. A list of versions to profile against can be specified after the -v flag, if not provided the current version will be used. Experiments are stored in etc/profile-experiments, user experiments can be stored in .profiling/experiments. Experiments are specified without the file extension, experiments in .profiling/ will be chosen before those in etc/. IMPORTANT: See etc/profile-experiments/example for an experiment template with further details. Versions are any valid git identifiers i.e. tags, branches, commits. To compare results to different cylc versions either: * Supply cylc profile-battery with a complete list of the versions you wish to profile, it will then provide the option to checkout the required versions automatically. * Checkout each version manually running cylc profile-battery against only one version at a time. Once all results have been gathered you can then run cylc profile-battery with a complete list of versions. Profiling will save results to .profiling/results.json where they can be used for future comparisons. To list profiling results run: * cylc profile-battery --ls # list all results * cylc profile-battery --ls -e experiment # list all results for # experiment "experiment". * cylc profile-battery --ls --delete -v 6.1.2 # Delete all results for # version 6.1.2 (prompted). If matplotlib and numpy are installed profiling generates plots which are saved to .profiling/plots or presented in an interactive window using the -i flag. Results are stored along with a checksum for the experiment file. When an experiment file is changed previous results are maintained, future results will be stored separately. To copy results from an older version of an experiment into those from the current one run: * cylc profile-battery --promote experiment@checksum NOTE: At present results cannot be analysed without the experiment file so old results must be "copied" in this way to be re-used. The results output contain only a small number of metrics, to see a full list of results use the --full option. Options: -h, --help show this help message and exit -e, --experiments Specify list of experiments to run. -v, --versions Specify cylc versions to profile. Git tags, branches, commits are all valid. -i, --interactive Open any plots in interactive window rather saving them to files. -p, --no-plots Don't generate any plots. --ls, --list-results List all stored results. Experiments and versions to list can be specified using --experiments and --versions. --delete Delete stored results (to be used in combination with --list-results). -y, --yes Answer yes to any user input. Will check-out cylc versions as required. --full-results, --full Display all gathered metrics. --lobf-order=LOBF_ORDER The order (int)of the line of best fit to be drawn. 0 for no lobf, 1 for linear, 2 for quadratic ect. --promote=PROMOTE Promote results from an older version of an experiment to the current version. To be used when making non- functional changes to an experiment. --test For development purposes, run experiment without saving results and regardless of any prior runs. .. _command-ref-graph: ref-graph ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: Usage: cylc ref-graph SUITE [START] [STOP] Implement the old ``cylc graph --reference command`` for producing a text-format representation of a suite graph. The `--reference` flag is optional here. THIS IS A BACK-PORT OF the Python 3 bin/cylc-graph FOR CYLC 8, TO GENERATE TEXT-FORMAT "REFERENCE GRAPHS" WITHOUT THE NEED FOR PYGTK TO BE INSTALLED. Arguments: [SUITE] Suite name or path [START] Initial cycle point (default: suite initial point) [STOP] Final cycle point (default: initial + 3 points) Options: -h, --help show this help message and exit -u, --ungrouped Start with task families ungrouped (the default is grouped). -n, --namespaces Plot the suite namespace inheritance hierarchy (task run time properties). -r, --reference Output in a sorted plain text format for comparison purposes. --show-suicide Show suicide triggers. They are not shown by default, unless toggled on with the tool bar button. --icp=CYCLE_POINT Set initial cycle point. Required if not defined in suite.rc. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-register: register ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] register [OPTIONS] [REG] [PATH] Register the name REG for the suite definition in PATH. The suite server program can then be started, stopped, and targeted by name REG. (Note that "cylc run" can also register suites on the fly). Registration creates a suite run directory "~/cylc-run/REG/" containing a ".service/source" symlink to the suite definition location. The .service directory is also used for server authentication files at runtime. With the "--run-dir" option "~/cylc-run/REG" can be symlinked to another location. Suite names can be hierarchical, corresponding to path under the run directory. % cylc register dogs/fido PATH Register PATH/suite.rc as dogs/fido, with run directory ~/cylc-run/dogs/fido. % cylc register dogs/fido Register $PWD/suite.rc as dogs/fido. % cylc register Register $PWD/suite.rc as the parent directory name: $(basename $PWD). The same suite can be registered with multiple names; this results in multiple suite run directories that link to the same suite definition. To "unregister" a suite, delete or rename its run directory (renaming it under ~/cylc-run effectively re-registers the original suite with the new name). Use of "--redirect" is required to allow an existing name (and run directory) to be associated with a different suite definition. This is potentially dangerous because the new suite will overwrite files in the existing run directory. You should consider deleting or renaming an existing run directory rather than just re-use it with another suite. Arguments: [REG] Suite name [PATH] Suite definition directory (defaults to $PWD) Options: -h, --help show this help message and exit --redirect Allow an existing suite name and run directory to be used with another suite. --run-dir=RUNDIR Symlink $HOME/cylc-run/REG to RUNDIR/REG. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-release: release ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] release|unhold [OPTIONS] REG [TASK_GLOB ...] Release a held suite or tasks. cylc release REG - release the suite cylc release REG TASK_GLOB ... - release one or more tasks Held tasks do not submit their jobs even if ready to run. See also 'cylc [control] hold'. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-reload: reload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] reload [OPTIONS] REG Tell a suite to reload its definition at run time. All settings including task definitions, with the exception of suite log configuration, can be changed on reload. Note that defined tasks can be be added to or removed from a running suite with the 'cylc insert' and 'cylc remove' commands, without reloading. This command also allows addition and removal of actual task definitions, and therefore insertion of tasks that were not defined at all when the suite started (you will still need to manually insert a particular instance of a newly defined task). Live task proxies that are orphaned by a reload (i.e. their task definitions have been removed) will be removed from the task pool if they have not started running yet. Changes to task definitions take effect immediately, unless a task is already running at reload time. If the suite was started with Jinja2 template variables set on the command line (cylc run --set FOO=bar REG) the same template settings apply to the reload (only changes to the suite.rc file itself are reloaded). If the modified suite definition does not parse, failure to reload will be reported but no harm will be done to the running suite. Arguments: REG Suite name Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-remote-init: remote-init ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [task] remote-init [--indirect-comm=ssh] UUID RUND (This command is for internal use.) Install suite service files on a task remote (i.e. a [owner@]host): .service/contact: All task -> suite communication methods. .service/passphrase: Direct task -> suite HTTP(S) communication only. .service/ssl.cert: Direct task -> suite HTTPS communication only. Content of items to install from a tar file read from STDIN. Return: 0: On success or if initialisation not required: - Print SuiteSrvFilesManager.REMOTE_INIT_NOT_REQUIRED if initialisation not required (e.g. remote has shared file system with suite host). - Print SuiteSrvFilesManager.REMOTE_INIT_DONE on success. 1: On failure. Arguments: UUID UUID of current suite server process RUND The run directory of the suite Options: -h, --help show this help message and exit --indirect-comm=METHOD specify use of indirect communication via e.g. ssh --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-remote-tidy: remote-tidy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [task] remote-tidy RUND (This command is for internal use.) Remove ".service/contact" from a task remote (i.e. a [owner@]host). Remove ".service" directory on the remote if emptied. Arguments: RUND The run directory of the suite Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-remove: remove ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] remove [OPTIONS] REG TASK_GLOB [...] Remove one or more task instances from a running suite. Tasks will be forced to spawn successors before removal if they have not done so already, unless you use '--no-spawn'. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name TASK_GLOB [...] Task match pattern(s) Options: -h, --help show this help message and exit --no-spawn Do not spawn successors before removal. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-report-timings: report-timings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [util] report-timings [OPTIONS] REG Retrieve suite timing information for wait and run time performance analysis. Raw output and summary output (in text or HTML format) are available. Output is sent to standard output, unless an output filename is supplied. Summary Output (the default): Data stratified by host and batch system that provides a statistical summary of 1. Queue wait time (duration between task submission and start times) 2. Task run time (duration between start and succeed times) 3. Total run time (duration between task submission and succeed times) Summary tables can be output in plain text format, or HTML with embedded SVG boxplots. Both summary options require the Pandas library, and the HTML summary option requires the Matplotlib library. Raw Output: A flat list of tabular data that provides (for each task and cycle) the 1. Time of successful submission 2. Time of task start 3. Time of task successful completion as well as information about the batch system and remote host to permit stratification/grouping if desired by downstream processors. Timings are shown only for succeeded tasks. For long-running and/or large suites (i.e. for suites with many task events), the database query to obtain the timing information may take some time. Arguments: REG Suite name Options: -h, --help show this help message and exit -r, --raw Show raw timing output suitable for custom diagnostics. -s, --summary Show textual summary timing output for tasks. -w, --web-summary Show HTML summary timing output for tasks. -O OUTPUT_FILENAME, --output-file=OUTPUT_FILENAME Output to a specific file --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-reset: reset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] reset [OPTIONS] REG [TASK_GLOB ...] Force task instances to a specified state. cylc reset --state=xxx REG - reset all tasks to state xxx cylc reset --state=xxx REG TASK_GLOB ... - reset one or more tasks to xxx Outputs are automatically updated to reflect the new task state, except for custom message outputs which can be manipulated directly with "--output". Prerequisites reflect the state of other tasks; they are not changed except to unset them on resetting state to 'waiting' or earlier. To hold and release tasks use "cylc hold" and "cylc release", not this command. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit -s STATE, --state=STATE Reset task state to STATE, can be succeeded, waiting, submitted, failed, running, submit-failed, expired -O OUTPUT, --output=OUTPUT Find task output by message string or trigger string, set complete or incomplete with !OUTPUT, '*' to set all complete, '!*' to set all incomplete. Can be used more than once to reset multiple task outputs. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-restart: restart ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] restart [OPTIONS] [REG] Start a suite run from the previous state. To start from scratch (cold or warm start) see the 'cylc run' command. The scheduler runs as a daemon unless you specify --no-detach. Tasks recorded as submitted or running are polled at start-up to determine what happened to them while the suite was down. Arguments: [REG] Suite name Options: -h, --help show this help message and exit -n, --no-detach, --non-daemon Do not daemonize the suite -a, --no-auto-shutdown Do not shut down the suite automatically when all tasks have finished. This flag overrides the corresponding suite config item. --auto-shutdown Shut down the suite automatically when all tasks have finished. This flag overrides the corresponding suite config item. --profile Output profiling (performance) information --checkpoint=CHECKPOINT-ID Specify the ID of a checkpoint to restart from --ignore-initial-cycle-point Ignore the initial cycle point in the suite run database. If one is specified in the suite definition it will be used, however. --ignore-final-cycle-point Ignore the final cycle point in the suite run database. If one is specified in the suite definition it will be used, however. --ignore-start-cycle-point Ignore the start cycle point in the suite run database. --ignore-stop-cycle-point Ignore the stop cycle point in the suite run database. --final-cycle-point=CYCLE_POINT, --final-point=CYCLE_POINT, --until=CYCLE_POINT, --fcp=CYCLE_POINT Set the final cycle point. --stop-cycle-point=CYCLE_POINT, --stop-point=CYCLE_POINT Set stop point. Shut down after all tasks have PASSED this cycle point. (Not to be confused with the final cycle point.) --hold Hold suite immediately on starting. --hold-point=CYCLE_POINT, --hold-after=CYCLE_POINT Set hold cycle point. Hold suite AFTER all tasks have PASSED this cycle point. -m STRING, --mode=STRING Run mode: live, dummy, dummy-local, simulation (default live). --reference-log Generate a reference log for use in reference tests. --reference-test Do a test run against a previously generated reference log. --host=HOST Specify the host on which to start-up the suite. If not specified, a host will be selected using the 'suite servers' global config. --user=USER Other user account name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-review: review ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] review [OPTIONS] [start [PORT]] [stop] Start/stop ad-hoc Cylc Review web service server for browsing users' suite logs via an HTTP interface. With no arguments, the status of the ad-hoc web service server is printed. For 'cylc review start', if 'PORT' is not specified, port 8080 is used. Arguments: [start [PORT]] Start ad-hoc web service server. [stop] Stop ad-hoc web service server. Options: -h, --help show this help message and exit -y, --non-interactive, --yes Switch off interactive prompting i.e. answer yes to everything (for stop only). -R, --service-root Include web service name under root of URL (for start only). .. _command-run: run ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] run|start [OPTIONS] [[REG] [START_POINT] ] Start a suite run from scratch, ignoring dependence prior to the start point. WARNING: this will wipe out previous suite state. To restart from a previous state, see 'cylc restart --help'. The scheduler will run as a daemon unless you specify --no-detach. If the suite is not already registered (by "cylc register" or a previous run) it will be registered on the fly before start up. % cylc run REG Run the suite registered with name REG. % cylc run Register $PWD/suite.rc as $(basename $PWD) and run it. (Note REG must be given explicitly if START_POINT is on the command line.) A "cold start" (the default) starts from the suite initial cycle point (specified in the suite.rc or on the command line). Any dependence on tasks prior to the suite initial cycle point is ignored. A "warm start" (-w/--warm) starts from a given cycle point later than the suite initial cycle point (specified in the suite.rc). Any dependence on tasks prior to the given warm start cycle point is ignored. The suite initial cycle point is preserved. Arguments: [REG] Suite name [START_POINT] Initial cycle point or 'now'; overrides the suite definition. Options: -h, --help show this help message and exit -n, --no-detach, --non-daemon Do not daemonize the suite -a, --no-auto-shutdown Do not shut down the suite automatically when all tasks have finished. This flag overrides the corresponding suite config item. --auto-shutdown Shut down the suite automatically when all tasks have finished. This flag overrides the corresponding suite config item. --profile Output profiling (performance) information -w, --warm Warm start the suite. The default is to cold start. --start-cycle-point=CYCLE_POINT, --start-point=CYCLE_POINT Set the start cycle point. Implies --warm.(Not to be confused with the initial cycle point.) --final-cycle-point=CYCLE_POINT, --final-point=CYCLE_POINT, --until=CYCLE_POINT, --fcp=CYCLE_POINT Set the final cycle point. --stop-cycle-point=CYCLE_POINT, --stop-point=CYCLE_POINT Set stop point. Shut down after all tasks have PASSED this cycle point. (Not to be confused with the final cycle point.) --hold Hold suite immediately on starting. --hold-point=CYCLE_POINT, --hold-after=CYCLE_POINT Set hold cycle point. Hold suite AFTER all tasks have PASSED this cycle point. -m STRING, --mode=STRING Run mode: live, dummy, dummy-local, simulation (default live). --reference-log Generate a reference log for use in reference tests. --reference-test Do a test run against a previously generated reference log. --host=HOST Specify the host on which to start-up the suite. If not specified, a host will be selected using the 'suite servers' global config. --user=USER Other user account name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-scan: scan ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [discovery] scan [OPTIONS] [HOSTS ...] Print information about running suites. By default, it will obtain a listing of running suites for the current user from the file system, before connecting to the suites to obtain information. Use the -o/--suite-owner option to get information of running suites for other users. If a list of HOSTS is specified, it will obtain a listing of running suites by scanning all ports in the relevant range for running suites on the specified hosts. If the -a/--all option is specified, it will use the global configuration "[suite servers]scan hosts" setting to determine a list of hosts to scan. Suite passphrases are not needed to get identity information (name and owner). Titles, descriptions, state totals, and cycle point state totals may also be revealed publicly, depending on global and suite authentication settings. Suite passphrases still grant full access regardless of what is revealed publicly. WARNING: a suite suspended with Ctrl-Z will cause port scans to hang until the connection times out (see --comms-timeout). Arguments: [HOSTS ...] Hosts to scan instead of the configured hosts. Options: -h, --help show this help message and exit -a, --all Scan all port ranges in known hosts. -n PATTERN, --name=PATTERN List suites with name matching PATTERN (regular expression). Defaults to any name. Can be used multiple times. -o PATTERN, --suite-owner=PATTERN List suites with owner matching PATTERN (regular expression). Defaults to current user. Use '.*' to match all known users. Can be used multiple times. -d, --describe Print suite metadata if available. -s, --state-totals Print number of tasks in each state if available (total, and by cycle point). -f, --full Print all available information about each suite. -c, --color, --colour Print task state summaries using terminal color control codes. -b, --no-bold Don't use any bold text in the command output. --print-ports Print the port range from the global config file. --comms-timeout=SEC Set a timeout for network connections to each running suite. The default is 5 seconds. --old, --old-format Legacy output format ("suite owner host port"). -r, --raw, --raw-format Parsable format ("suite|owner|host|property|value"). -j, --json, --json-format JSON format. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). .. _command-scp-transfer: scp-transfer ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [util] scp-transfer [OPTIONS] An scp wrapper for transferring a list of files and/or directories at once. The source and target scp URLs can be local or remote (scp can transfer files between two remote hosts). Passwordless ssh must be configured appropriately. ENVIRONMENT VARIABLE INPUTS: $SRCE - list of sources (files or directories) as scp URLs. $DEST - parallel list of targets as scp URLs. The source and destination lists should be space-separated. We let scp determine the validity of source and target URLs. Target directories are created pre-copy if they don't exist. Options: -v - verbose: print scp stdout. --help - print this usage message. .. _command-search: search ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] search|grep [OPTIONS] SUITE PATTERN [PATTERN2...] Search for pattern matches in suite definitions and any files in the suite bin directory. Matches are reported by line number and suite section. An unquoted list of PATTERNs will be converted to an OR'd pattern. Note that the order of command line arguments conforms to normal cylc command usage (suite name first) not that of the grep command. Note that this command performs a text search on the suite definition, it does not search the data structure that results from parsing the suite definition - so it will not report implicit default settings. For case insenstive matching use '(?i)PATTERN'. Arguments: SUITE Suite name or path PATTERN Python-style regular expression [PATTERN2...] Additional search patterns Options: -h, --help show this help message and exit -x Do not search in the suite bin directory --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner .. _command-set-verbosity: set-verbosity ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] set-verbosity [OPTIONS] REG LEVEL Change the logging severity level of a running suite. Only messages at or above the chosen severity level will be logged; for example, if you choose WARNING, only warnings and critical messages will be logged. Arguments: REG Suite name LEVEL INFO, WARNING, NORMAL, CRITICAL, ERROR, DEBUG Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-show: show ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [info] show [OPTIONS] REG [TASK_NAME or TASK_GLOB ...] Query a running suite for: cylc show REG - suite metadata cylc show REG TASK_NAME - task metadata cylc show REG TASK_GLOB - prerequisites and outputs of matched task instances Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_NAME or TASK_GLOB ...] Task names or match patterns Options: -h, --help show this help message and exit --list-prereqs Print a task's pre-requisites as a list. --json Print output in JSON format. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-spawn: spawn ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] spawn [OPTIONS] REG [TASK_GLOB ...] Force task proxies to spawn successors at their own next cycle point. cylc spawn REG - force spawn all tasks in a suite cylc spawn REG TASK_GLOB ... - force spawn one or more tasks in a suite Tasks normally spawn on reaching the "submitted" status. Spawning them early allows running successive instances of the same task out of order. See also the "spawn to max active cycle points" suite configuration. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-stop: stop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] stop|shutdown [OPTIONS] REG [STOP] Tell a suite server program to shut down. In order to prevent failures going unnoticed, suites only shut down automatically at a final cycle point if no failed tasks are present. There are several shutdown methods: 1. (default) stop after current active tasks finish 2. (--now) stop immediately, orphaning current active tasks 3. (--kill) stop after killing current active tasks 4. (with STOP as a cycle point) stop after cycle point STOP 5. (with STOP as a task ID) stop after task ID STOP has succeeded 6. (--wall-clock=T) stop after time T (an ISO 8601 date-time format e.g. CCYYMMDDThh:mm, CCYY-MM-DDThh, etc). Tasks that become ready after the shutdown is ordered will be submitted immediately if the suite is restarted. Remaining task event handlers and job poll and kill commands, however, will be executed prior to shutdown, unless --now is used. This command exits immediately unless --max-polls is greater than zero, in which case it polls to wait for suite shutdown. Arguments: REG Suite name [STOP] a/ task POINT (cycle point), or b/ ISO 8601 date-time (clock time), or c/ TASK (task ID). Options: -h, --help show this help message and exit -k, --kill Shut down after killing currently active tasks. -n, --now Shut down without waiting for active tasks to complete. If this option is specified once, wait for task event handler, job poll/kill to complete. If this option is specified more than once, tell the suite to terminate immediately. -w STOP, --wall-clock=STOP Shut down after time STOP (ISO 8601 formatted) --max-polls=INT Maximum number of polls (default 0). --interval=SECS Polling interval in seconds (default 60). --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. .. _command-submit: submit ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [task] submit|single [OPTIONS] REG TASK [...] Submit a single task to run just as it would be submitted by its suite. Task messaging commands will print to stdout but will not attempt to communicate with the suite (which does not need to be running). For tasks present in the suite graph the given cycle point is adjusted up to the next valid cycle point for the task. For tasks defined under runtime but not present in the graph, the given cycle point is assumed to be valid. WARNING: do not 'cylc submit' a task that is running in its suite at the same time - both instances will attempt to write to the same job logs. Arguments: REG Suite name TASK [...] Family or task ID (NAME.CYCLE_POINT) Options: -h, --help show this help message and exit -d, --dry-run Generate the job script for the task, but don't submit it. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-suite-state: suite-state ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc suite-state REG [OPTIONS] Print task states retrieved from a suite database; or (with --task, --point, and --status) poll until a given task reaches a given state; or (with --task, --point, and --message) poll until a task receives a given message. Polling is configurable with --interval and --max-polls; for a one-off check use --max-polls=1. The suite database does not need to exist at the time polling commences but allocated polls are consumed waiting for it (consider max-polls*interval as an overall timeout). Note for non-cycling tasks --point=1 must be provided. For your own suites the database location is determined by your site/user config. For other suites, e.g. those owned by others, or mirrored suite databases, use --run-dir=DIR to specify the location. Example usages: cylc suite-state REG --task=TASK --point=POINT --status=STATUS returns 0 if TASK.POINT reaches STATUS before the maximum number of polls, otherwise returns 1. cylc suite-state REG --task=TASK --point=POINT --status=STATUS --offset=PT6H adds 6 hours to the value of CYCLE for carrying out the polling operation. cylc suite-state REG --task=TASK --status=STATUS --task-point uses CYLC_TASK_CYCLE_POINT environment variable as the value for the CYCLE to poll. This is useful when you want to use cylc suite-state in a cylc task. Arguments: REG Suite name Options: -h, --help show this help message and exit -t TASK, --task=TASK Specify a task to check the state of. -p CYCLE, --point=CYCLE Specify the cycle point to check task states for. -T, --task-point Use the CYLC_TASK_CYCLE_POINT environment variable as the cycle point to check task states for. Shorthand for --point=$CYLC_TASK_CYCLE_POINT --template=TEMPLATE Remote cyclepoint template (IGNORED - this is now determined automatically). -d DIR, --run-dir=DIR The top level cylc run directory if non-standard. The database should be DIR/REG/log/db. Use to interrogate suites owned by others, etc.; see note above. -s OFFSET, --offset=OFFSET Specify an offset to add to the targeted cycle point -S STATUS, --status=STATUS Specify a particular status or triggering condition to check for. Valid triggering conditions to check for include: 'fail', 'finish', 'start', 'submit' and 'succeed'. Valid states to check for include: 'runahead', 'waiting', 'held', 'queued', 'expired', 'ready', 'submit-failed', 'submit-retrying', 'submitted', 'retrying', 'running', 'failed' and 'succeeded'. -O MSG, -m MSG, --output=MSG, --message=MSG Check custom task output by message string or trigger string. --max-polls=INT Maximum number of polls (default 10). --interval=SECS Polling interval in seconds (default 60). --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. .. _command-test-battery: test-battery ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none cd "/Users/oliver/cylc-flow" Usage: cylc test-battery [...] Run automated Cylc and Parsec tests, under (by default): /Users/oliver/cylc-flow/tests/. Options and arguments are appended to "prove -j $NPROC -s -r ${@:-tests}". NPROC is the number of concurrent processes to run, which defaults to the global config "process pool size" setting. The tests ignore normal site/user global config and instead use the file: /Users/oliver/cylc-flow/etc/global-tests.rc This should specify test job hosts under the [test battery] section, plus any other critical settings settings, including [hosts] configuration for test job hosts (and special batchview commands like qcat if available). Additional global config items can be added on the fly using the create_test_globalrc shell function defined in the test_header. Suite run directories are only cleaned up for passing tests on the suite host. Set "export CYLC_TEST_DEBUG=true" to print failed-test stderr to the terminal. To change the test file comparision command from "diff -u" do (for example): export CYLC_TEST_DIFF_CMD='xxdiff -D' Some test suites submit jobs to the 'at' so atd must be up on the job hosts. Commits or Pull Requests to cylc/cylc-flow on GitHub will trigger Travis CI to run generic (non platform-specific) tests - see /Users/oliver/cylc-flow/.travis.yml. By default all tests are executed. To run just a subset of them: * list individual tests or test directories to run on the comand line * list individual tests or test directories to skip in $CYLC_TEST_SKIP * skip all generic tests with CYLC_TEST_RUN_GENERIC=false * skip all platform-specific tests with CYLC_TEST_RUN_PLATFORM=false List specific tests relative to /Users/oliver/cylc-flow (i.e. starting with "test/"). Some platform-specific tests are automatically skipped, depending on platform. Platform-specific tests must set "CYLC_TEST_IS_GENERIC=false" before sourcing the test_header. Tests requiring the sqlite3 CLI must be skipped if sqlite3 is not installed (it is not otherwise a Cylc software prerequisite): | if ! which sqlite3 > /dev/null; then | # Skip the remaining 3 tests. | skip 3 "sqlite3 not installed?" | purge_suite $SUITE_NAME | exit 0 | fi Options: -h, --help Print this help message and exit. --chunk CHUNK Divide the test battery into chunks and run the specified chunk. CHUNK takes the format 'a/b' where 'b' is the number of chunks to divide the battery into and 'a' is the number of the chunk to run (1 >= a >= b). Examples: Run the full test suite with the default options. cylc test-battery Run the full test suite with 12 processes cylc test-battery -j 12 Run only tests under "tests/cyclers/" cylc test-battery tests/cyclers Run only "tests/cyclers/16-weekly.t" in verbose mode cylc test-battery -v tests/cyclers/16-weekly.t Run only tests under "tests/cyclers/", and skip 00-daily.t export CYLC_TEST_SKIP=tests/cyclers/00-daily.t cylc test-battery tests/cyclers Run the first quarter of the test battery cylc test-battery --chunk '1/4' Re-run failed tests cylc test-battery --state=save cylc test-battery --state=failed .. _command-trigger: trigger ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [control] trigger [OPTIONS] REG [TASK_GLOB ...] Manually trigger tasks. cylc trigger REG - trigger all tasks in a running suite cylc trigger REG TASK_GLOB ... - trigger one or more tasks in a running suite NOTE waiting tasks that are queue-limited will be queued if triggered, to submit as normal when released by the queue; queued tasks will submit immediately if triggered, even if that violates the queue limit (so you may need to trigger a queue-limited task twice to get it to submit immediately). For single tasks you can use "--edit" to edit the generated job script before it submits, to apply one-off changes. A diff between the original and edited job script will be saved to the task job log directory. Multiple TASK_GLOBs can be given. They each match task proxy instances in the current task pool by task or family name pattern, cycle point pattern, and task state. They do NOT match any task at any point in the abstract suite graph; if target task instances do not exist in the current pool you must insert them first with the "cylc insert" command. * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE] * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE] * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE] For example, to match: * all tasks in a cycle: '20200202T0000Z/*' or '*.20200202T0000Z' * all tasks in the submitted status: ':submitted' * retrying 'foo*' tasks in 0000Z cycles: 'foo*.*0000Z:retrying' or '*0000Z/foo*:retrying' * retrying tasks in 'BAR' family: '*/BAR:retrying' or 'BAR.*:retrying' * retrying tasks in 'BAR' or 'BAZ' families: '*/BA[RZ]:retrying' or 'BA[RZ].*:retrying' The old 'MATCH POINT' syntax will be automatically detected and supported. To avoid this, use the '--no-multitask-compat' option, or use the new syntax (with a '/' or a '.') when specifying 2 TASK_GLOB arguments. Arguments: REG Suite name [TASK_GLOB ...] Task match pattern(s) Options: -h, --help show this help message and exit -e, --edit Manually edit the job script before running it. -g, --geditor (with --edit) force use of the configured GUI editor. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --port=INT Suite port number on the suite host. NOTE: this is retrieved automatically if non-interactive ssh is configured to the suite host. --use-ssh Use ssh to re-invoke the command on the suite host. --ssh-cylc=SSH_CYLC Location of cylc executable on remote ssh commands. --no-login Do not use a login shell to run remote ssh commands. The default is to use a login shell. --comms-timeout=SEC, --pyro-timeout=SEC Set a timeout for network connections to the running suite. The default is no timeout. For task messaging connections see site/user config file documentation. --print-uuid Print the client UUID to stderr. This can be matched to information logged by the receiving suite server program. --set-uuid=UUID Set the client UUID manually (e.g. from prior use of --print-uuid). This can be used to log multiple commands under the same UUID (but note that only the first [info] command from the same client ID will be logged unless the suite is running in debug mode). -f, --force Do not ask for confirmation before acting. Note that it is not necessary to use this option if interactive command prompts have been disabled in the site/user config files. -m, --family (Obsolete) This option is now ignored and is retained for backward compatibility only. TASK_GLOB in the argument list can be used to match task and family names regardless of this option. --no-multitask-compat Disallow backward compatible multitask interface. .. _command-upgrade-run-dir: upgrade-run-dir ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [admin] upgrade-run-dir SUITE For one-off conversion of a suite run directory to cylc-6 format. Arguments: SUITE suite name or run directory path Options: -h, --help show this help message and exit .. _command-validate: validate ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] validate [OPTIONS] SUITE Validate a suite definition. If the suite definition uses include-files reported line numbers will correspond to the inlined version seen by the parser; use 'cylc view -i,--inline SUITE' for comparison. Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit --strict Fail any use of unsafe or experimental features. Currently this just means naked dummy tasks (tasks with no corresponding runtime section) as these may result from unintentional typographic errors in task names. -o FILENAME, --output=FILENAME Specify a file name to dump the processed suite.rc. --profile Output profiling (performance) information -u RUN_MODE, --run-mode=RUN_MODE Validate for run mode. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --initial-cycle-point=CYCLE_POINT, --initial-point=CYCLE_POINT, --icp=CYCLE_POINT, --ict=CYCLE_POINT Set the initial cycle point. Required if not defined in suite.rc. .. _command-view: view ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [prep] view [OPTIONS] SUITE View a read-only temporary copy of suite NAME's suite.rc file, in your editor, after optional include-file inlining and Jinja2 preprocessing. The edit process is spawned in the foreground as follows: % suite.rc Where can be set in cylc global config. For remote host or owner, the suite will be printed to stdout unless the '-g,--gui' flag is used to spawn a remote GUI edit session. See also 'cylc [prep] edit'. Arguments: SUITE Suite name or path Options: -h, --help show this help message and exit -i, --inline Inline include-files. -e, --empy View after EmPy template processing (implies '-i/--inline' as well). -j, --jinja2 View after Jinja2 template processing (implies '-i/--inline' as well). -p, --process View after all processing (EmPy, Jinja2, inlining, line-continuation joining). -m, --mark (With '-i') Mark inclusions in the left margin. -l, --label (With '-i') Label file inclusions with the file name. Line numbers will not correspond to those reported by the parser. --single (With '-i') Inline only the first instances of any multiply-included files. Line numbers will not correspond to those reported by the parser. -c, --cat Concatenate continuation lines (line numbers will not correspond to those reported by the parser). -g, --gui Force use of the configured GUI editor. --stdout Print the suite definition to stdout. --mark-for-edit (With '-i') View file inclusion markers as for 'cylc edit --inline'. --user=USER Other user account name. This results in command reinvocation on the remote account. --host=HOST Other host name. This results in command reinvocation on the remote account. -v, --verbose Verbose output mode. --debug Output developer information and show exception tracebacks. --suite-owner=OWNER Specify suite owner -s NAME=VALUE, --set=NAME=VALUE Set the value of a Jinja2 template variable in the suite definition. This option can be used multiple times on the command line. NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. --set-file=FILE Set the value of Jinja2 template variables in the suite definition from a file containing NAME=VALUE pairs (one per line). NOTE: these settings persist across suite restarts, but can be set again on the "cylc restart" command line if they need to be overridden. .. _command-warranty: warranty ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: none Usage: cylc [license] warranty [--help] Cylc is released under the GNU General Public License v3.0 This command prints the GPL v3.0 disclaimer of warranty. Options: --help Print this usage message.