Command Line Interface
Does This Change Affect Me?
This will affect you if you use the Cylc command line interface.
Overview
Some commands have been renamed e.g.
cylc run
->cylc play
.Some tools have been added or removed.
A new task ID format has been introduced.
For a quick side by side comparison see the Cheat Sheet.
Full List Of Command Changes
The command line has been simplified from Cylc 7 with some commands being renamed or removed.
Commands that have been removed entirely:
cylc checkpoint
Database checkpoints are no longer needed.
All task state changes are written to the database when they occur.
Remaining use cases can be handled by starting a new flow which allow a new execution of the graph to be started from an arbitrary point in the graph.
cylc documentation
We no longer include a command for locating this documentation.
cylc edit
Use a text editor to edit the workflow configuration file.
cylc jobscript
It is no longer possible generate a jobscript from outside of a workflow.
cylc nudge
No longer required.
cylc register
Registration is no longer required, all workflows in the
~/cylc-run
directory are “registered” automatically.To install a workflow from a working copy use
cylc install
.
cylc review
The read-only
cylc review
web GUI has been removed.The latest Cylc 7 version of
cylc review
is Cylc 8 compatible so can still be used to monitor both Cylc 7 and Cylc 8 workflows side by side.
cylc search
Use
grep
or a text editor to search the workflow configuration or source directory.
cylc submit
It is no longer possible to submit a job from outside of a workflow.
cylc warranty
The Cylc license remains unchanged from Cylc 7.
Commands that have been replaced:
cylc conditions
See the license file for conditions of usage, or
cylc help license
The Cylc license remains unchanged from Cylc 7.
cylc get-config
,Replaced by
cylc config
.
cylc get-*-config
(Where
*
issite
,suite
orglobal
)Replaced by
cylc config
.
cylc graph-diff
Replaced by
cylc graph <flow1> --diff <flow2>
cylc insert
Task insertion is now automatic, use
cylc trigger
.
cylc monitor
There is now a new more powerful terminal user interface (TUI).
Try
cylc tui
.
cylc print
Equivalent to
cylc scan --states=all
.
cylc reset
cylc reset
has been replaced bycylc set
At Cylc 8 we override task’s prerequisites & outputs rather than modifying the task state directly.
cylc restart
Replaced by
cylc play
.
cylc run
Replaced by
cylc play
.
cylc spawn
Spawning is now performed automatically, on demand. Use
cylc trigger
to run a task, orcylc set
to spawn tasks that depend on specified outputs.
cylc suite-state
Renamed as
cylc workflow-state
.
Commands that have changed:
cylc hold
Now used on tasks only; use
cylc pause
to pause an entire workflow (i.e. to halt all job submissions).
cylc release
Now used only to release held tasks; use
cylc play
to resume a paused workflow.
Graphical User Interfaces (GUIs):
The GTK based GUI based GUIs have been removed, please use the new web based GUI. Consequently the following commands have also been removed:
cylc gpanel
cylc gscan
cylc gcylc
The cylc gui
command remains, it launches a standalone version of the
web GUI (providing the Cylc UI Server is installed).
Additionally, there are two “compound commands” which automate common working practices, namely:
cylc vip
Validate, install and play a workflow. This is similar to what
rose suite-run
did.cylc vr
Validate, reinstall, then either reload (if the workflow is running) or restart (if it is stopped) the workflow. This is similar to what
rose suite-run --reload
androse suite-run --restart
did.
Cylc 8 Standardised IDs
In Cylc 7 there were two ways to specify a task:
task.cycle
cycle/task
In Cylc 8 the former is now deprecated, and the latter has been extended to provide a unique identifier for all workflows, cycles, tasks and jobs using a standard format:
~user/workflow//cycle/task/job
Consequently task IDs have changed:
# old
cycle.task
# new
cycle/task
An example using cylc trigger
:
# old
cylc trigger workflow task.cycle
# new
cylc trigger workflow//cycle/task
Cylc 8 still supports the old format, however, the new format unlocks extra functionality e.g:
# stop all running workflows
cylc stop '*'
# pause all running workflows
cylc pause '*'
# (re-)trigger all failed tasks in all running workflows
cylc trigger '*//*:failed'
# hold all tasks in the cycle "2000" in workflows with IDs
# beginning with "model"
cylc hold 'model*//2000'
# delete the run directories for all workflows with IDs
# beginning with "model_a/"
cylc clean 'model_a/*'
For more information run cylc help id
.
For a quick overview of the motivation see the ID post on Discourse.