From 1c485a8a6d7d1ab5b93bc691c45460648f0a3968 Mon Sep 17 00:00:00 2001 From: Hilary James Oliver Date: Mon, 13 Mar 2023 15:58:46 +1300 Subject: [PATCH] Tweak scan CLI help [skip ci] --- cylc/flow/scripts/scan.py | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/cylc/flow/scripts/scan.py b/cylc/flow/scripts/scan.py index ea2885140c..ea7eec9c20 100644 --- a/cylc/flow/scripts/scan.py +++ b/cylc/flow/scripts/scan.py @@ -17,15 +17,23 @@ # along with this program. If not, see . """cylc scan [OPTIONS] -List Cylc workflows. +List workflows. -By default this shows only running or paused workflows. +By default, list running (or paused) workflows as recorded in contact files: + ~/cylc-run//.service/contact. + +Schedulers may occasionally leave contact files behind after an unclean shut +down. With the `--ping` option, scan will attempt to connect to the scheduler +and will remove the contact file if the workflow is not running. + +Source workflows (--source), and installed ones that are not currently +running (--state=stopped) can also be listed. Examples: - # list all "active" workflows (i.e. running or paused) + # list all active workflows (i.e. running or paused) $ cylc scan - # show more information about these workflows + # show more information about active workflows (connects to the schedulers) $ cylc scan -t rich # don't rely on colour for job state totals @@ -41,11 +49,11 @@ # filter workflows by name $ cylc scan --name '^f.*' # show only flows starting with "f" - # list source workflows in a tree + # list source workflows in tree format # (looks in the dirs configured by "global.cylc[install]source dirs") $ cylc scan --source -t tree - # get results in JSON format + # get contact file contents in JSON format $ cylc scan -t json """ @@ -207,7 +215,7 @@ def get_option_parser() -> COP: 'Set the output format.' ' (rich: multi-line, human readable)' ' (plain: single-line)' - ' (json: machine readable)' + ' (json: machine readable contact file contents)' ' (tree: display registration hierarchy as a tree)' ' (name: just show flow names, machine readable)' ),