`cylc pause` CLI docs confusion

Cylc Cylc Support
1

Hi,

When I do cylc help pause it states that the command can take task, globs, selectors as an argument, as shown at the end of this message. However, if I try to do that, I get an error. Or, am I misreading the usage instructions? The instructions say “Not to be confused with cylc hold.” which is just above the comments about This command can operate on ..., but I read This in the context of the command being queried for usage instructions. Perhaps instead of This it should say “The cylc hold command …” or similar? My best guess is though that there is potential for confusion by using the word This just after mentioning cylc hold, and the section about working on multiple tasks should be removed.

$ cylc pause rewind '//3/d_012'
InputError: IDs must be workflows

CLI usage instructions for cylc pause

$ cylc help pause
Usage: cylc pause [OPTIONS] WORKFLOW ...

Pause a workflow.

This suspends submission of tasks.

Examples:
  # pause my_flow
  $ cylc pause my_flow

  # resume my_flow
  $ cylc play my_flow

Not to be confused with `cylc hold`.

This command can operate on multiple workflows, globs may also be used:
    Multiple Workflows:
        # Operate on two workflows
        workflow-1 workflow-2

    Globs (note: globs should be quoted):
        # Match all workflows
        '*'

        # Match the workflows foo-1, foo-2
        'foo-[12]'

    See `cylc help id` for more details.

This command can operate on multiple tasks, globs and selectors may
be used:
    Multiple Tasks:
        # Operate on two tasks
        workflow //cycle-1/task-1 //cycle-2/task-2

    Globs (note: globs should be quoted and only match active tasks):
        # Match any the active task "foo" in all cycles
        '//*/foo'

        # Match the tasks "foo-1" and "foo-2"
        '//*/foo-[12]'

    Selectors (note: selectors only match active tasks):
        # match all failed tasks in cycle "1"
        //1:failed

    See `cylc help id` for more details.
2

Hi @tomc

The cylc pause command pauses workflows. The first bit of documentation is correct (and refers to cylc pause not cylc hold):

This command can operate on multiple workflows …

Not to be confused with the cylc hold command, which prevents individual tasks from submitting in a running workflow.

The second part of the documentation is wrong for this command (although it does apply to cylc hold):

This command can operate on multiple tasks, globs

It’s being printed to the command help because of a a one-line error in the command script. I’ll put a fix up now…

Thanks for raising this.

[UPDATE] Cylc pause help fix by hjoliver · Pull Request #5685 · cylc/cylc-flow · GitHub

1 Like