Skip to content
| Marketplace
Sign in
Visual Studio Code>Programming Languages>Cylc Flow LinkerNew to Visual Studio Code? Get it now.
Cylc Flow Linker

Cylc Flow Linker

Tim Pillinger

| (0) | Free
Convert Jinja2 imports, app-key references, and optional config keys to navigable links in Cylc flow files
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Cylc Flow Linker

A VSCode extension that converts references to Cylc configuration items into navigable links.

Features

1. Jinja2 Import Links

Converts Jinja2 import/include statements to links pointing to the imported files:

{% import "include/runtime.cylc" as runtime %}
{%- import "include/meta.cylc" -%}
{% include "include/parameters.cylc" %}

Cylc's native %include "include/runtime.cylc" lines are linked in the same way.

Clicking on the file path will open the corresponding file in your repository.

2. App Key Links

Converts --app-key= references to links pointing to the respective rose-app.conf:

[[my_task]]
    script = rose task-run --app-key=myapp -vv

Clicking on myapp will open app/myapp/rose-app.conf.

3. Optional Config Key Links

Converts -O/--opt-conf-key and ROSE_APP_OPT_CONF_KEYS environment variables to links pointing to optional config files:

[[my_task]]
    script = rose task-run --app-key=myapp --opt-conf-key=dump -vv
    [[[environment]]]
        ROSE_APP_OPT_CONF_KEYS = first

Clicking on dump or first will open the corresponding optional config file at:

  • app/myapp/opt/rose-app-dump.conf
  • app/myapp/opt/rose-app-first.conf

4. Graph Task Links

Links task names in the [scheduling] [[dependencies]] or [[graph]] sections to matching [[task_name]] definitions in [runtime]. Definitions in directly imported Jinja files are also supported. If a runtime task has no --app-key and a same-named app exists, its [[task_name]] header links to app/<task_name>/rose-app.conf; graph links still go to the runtime definition.

5. Jinja2 Python Imports

Links Python modules imported from lib/python ({% import mymodule %}, {% from "mymodule" import myfunc %}) to the module file. For from imports, each imported name links to its def, class or assignment line.

How It Works

Task Parameter Tooltips

Hover over parameter names in task references such as garden_<my_param> to see their [task parameters] definitions and, when configured, their [[templates]] entries. Definitions are read from the current document, without expanding values.

Variable Tooltips

Hover over a variable in a Jinja expression or statement to see its value from rose-suite.conf under [template variables], or an earlier {% set NAME = value %} in the current document. For example, tooltips show FOO = 45 or BAR = [1, 1, 3, 5]. Set expressions take precedence over Rose values. Values are displayed as written, without evaluating Jinja or Python; template scope, conditional execution, and assignments in included files are not resolved.

The extension:

  1. Scans each line of .cylc files for recognized patterns
  2. Validates that target files exist before creating links
  3. For optional config keys, automatically detects the app context by searching backwards for the most recent --app-key= reference
  4. Converts valid references into clickable links using VSCode's document link provider

Installation

From the VS Code Marketplace

(Coming soon)

Manual Installation (Development)

  1. Clone this repository:

    git clone https://github.com/wxtim/cylc-flow-linker.git
    cd cylc-flow-linker
    
  2. Install dependencies:

    npm install
    
  3. Build the extension:

    npm run build
    
  4. Open the repository folder in VS Code and press F5 to launch the Extension Development Host with the example/ folder and example/example-flow.cylc open. The launch configuration builds the extension before starting it.

Usage

  1. Open a Cylc workflow repository in VS Code. To try the included demo, open the example/ folder.
  2. Open example/example-flow.cylc for the demo, or any .cylc file in your workflow
  3. Hover over or click on linked items:
    • File paths in Jinja2 imports (e.g., "include/runtime.cylc")
    • App names after --app-key= (e.g., myapp)
    • Config keys after -O, --opt-conf-key, or in ROSE_APP_OPT_CONF_KEYS (e.g., dump, first)

The extension will navigate to the corresponding file when clicked.

Supported Patterns

Jinja2 Imports

  • {% import "path/file.cylc" as var %}
  • {%- import "path/file.cylc" -%}
  • {% include "path/file.cylc" %}

Jinja2 Python Imports

  • {% import module %} / {% import "module" %}
  • {% from module import func, other as alias %}

Cylc Includes

  • %include "path/file.cylc" (quotes optional; resolved relative to the including file, then the workspace root)

App Key References

  • --app-key=app_name

Optional Config Key References

  • -O=key_name or -O key_name
  • --opt-conf-key=key_name or --opt-conf-key key_name
  • ROSE_APP_OPT_CONF_KEYS = key1 key2 key3 (space-separated)
  • ROSE_APP_OPT_CONF_KEYS=key_name (environment variable assignment)

Graph Task References

  • Task names in [scheduling] [[dependencies]] or [[graph]] sections that have a matching runtime definition
  • Runtime task headers without --app-key link to a same-named existing app/<task_name>/rose-app.conf

License

MIT

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft