Terminal user interface

This interface is designed for the more technically experienced Requester to create a request.yaml file efficiently and quickly without having to use or depend on the web application.

In many ways, the terminal user interface is similar to the web application in functionality but has some fundamental differences. Graphical user interfaces like web applications in general aren’t well-designed for nor well-suited for building efficient or portable interfaces (e.g., they need a browser to work). Browser-based web applications also don’t usually include custom keyboard shortcuts, which can make it difficult to build one that fits the needs or wants of more technically experienced Requesters. See the user types for more detail about this type of Requester and their needs.

Terminal user interfaces, however, are by their nature better fit for the needs of technically experienced users. For example, they tend to make heavy use of or even require using only the keyboard. They are also more lightweight and portable, since they only need a terminal. So, Propagate’s terminal user interface are designed with these technical users. The focus for the terminal user interface will be on simplicity, minimalism, efficiency, and portability.

We include a terminal user interface as an alternative to the web application for the following reasons:

• More technically experienced users may prefer a faster, more efficient way of creating a request file without having to interact with a graphical web application, especially if they are already familiar with working in a terminal environment.

• An in-editor tool to make it easier to manually edit a request file would allow the most flexibility but also be the most error-prone since it involves manually editing the file. It is also challenging to implement since most of the manual editing experience, e.g. with checks against the metadata, the editor needs to be made aware of a different metadata file for each data package. This means that there must be a configuration option that the user would need to change every single time when making requests from different data packages. It’s easier to design and develop a terminal interface that takes a source metadata file as input and generates a request file as an output.

• Creating a template request.yaml file manually that has all the information filled in from the metadata file, while possible, would not be a pleasant experience for the Requester. This might be fine for small datasets, but for data packages with several resources and hundreds of columns (which is fairly common in research datasets), manually editing an extremely long request file would be very tedious and error-prone. Especially when it comes to correctly writing row conditions, as those fields can’t be pre-filled as easily.

• For requesters on systems with limitations (e.g., IT restrictions and other institutional policies), building and viewing a web application locally may not be possible. A terminal user interface is simpler and has fewer steps involved. For example, it only needs to read the metadata file, display the content on the terminal, and generate a request file, which is much simpler and less likely to be blocked by IT restrictions.

• A web application may not be available on some systems, such as terminal-only servers. A terminal user interface can be used in these types of environments, especially if the only way to make a request is while logged into these systems.

• If the Owner is not allowed (e.g. institutional policy) to use GitHub or to publicly share the metadata file (and consequently the web application). This is quite a common experience for human health and/or sensitive data, which makes up a substantial amount of research data. And usually, these sensitive data are kept on more tightly-managed servers, so options for sharing the metadata file and creating web applications are limited. A terminal user interface is more portable in these cases.

Layout

The terminal user interface uses two panes. The left pane shows a structured representation of the request.yaml file, while the right pane shows information and controls for the item selected in the left pane. The left pane is for navigation only; all information is entered or selected in the right pane.

This design makes the structure of the request visible throughout the process and shows how each choice changes the file. At the same time, it avoids the errors that could occur if the Requester had to edit YAML syntax, indentation, or keys directly. It also gives Propagate control over the editing experience, including which operators and data package fields can be selected, without requiring integration with a particular text editor or constant editor re-configuration for each new data package.

The left pane resembles the structure of request.yaml, but it is not a literal text editor. Long values may be shortened, sections can be collapsed, and summary text such as the number of selected columns may be shown instead of the full YAML. Changes made in the right pane update this representation so that the Requester can see the request take shape as they work. The panes have different visual emphasis depending on which one is active. The active pane must be identifiable without relying on colour alone. A footer shows the shortcuts that apply to the current pane and mode.

Completion status

The left pane shows the state of information that the Requester needs to enter:

• A check mark ([✓]) indicates that the information is filled in and passes its checks.
• A cross ([x]) indicates that information is present but needs correction.
• An empty marker ([ ]) indicates that information has not been filled in.

The same markers can summarize a section. For example, the project section shows a check mark only when its name, title, and description all pass their checks. An explanation is shown in the right pane when a selected value needs correction.

Values managed by Propagate, such as datetime-created, datetime-modified, and the data-package fields, are visually muted to distinguish them from information entered by the Requester. They are shown in the request structure but cannot be edited from the TUI.

Contextual editing

Moving through the left pane automatically updates the right pane with a short explanation of the selected item. Opening the right pane makes its controls active. Text values use either single-line or multiline inputs, while choices derived from the data package use searchable selection lists/dropdowns. This means that a Requester can type part of a resource or column name to filter the dropdown instead of scrolling through a long list.

Edits in the right pane are applied to an in-memory request and reflected in the left pane. The Requester can apply the edits and return to navigation, or cancel them and restore the values that were present when the right pane was opened.

Selecting columns

The columns panel initially offers the choices to request all columns from all resources or to customize the selection. This makes the meaning of an omitted columns key explicit even though Propagate does not need to write that key to the request file when all columns are requested.

When customizing the selection, the Requester chooses resources and then their columns. Selecting a resource without specifying individual columns requests all columns from that resource. Available columns are shown by name and title. The TUI does not reproduce the complete data package documentation because its purpose is to create a request, not to replace interfaces designed for exploring metadata, such as Flower.

Search is available for data packages with many resources or columns. Selected items are kept easy to find, for example by sorting them before unselected items. The left pane summarizes the selection by resource and expands to show individual columns when needed.

Selecting rows

The rows panel initially offers the choices to request all rows or to add row conditions. This makes the meaning of an omitted rows key explicit without requiring the Requester to understand that detail of the file format.

Row conditions use structured controls rather than free-form SQL. A condition contains a column, an operator, a value where applicable, and an option to negate the comparison. The available columns and operators come from the data package and the request format, preventing unsupported combinations from being entered. The initially supported operators are =, >, >=, <, <=, IN, and IS NULL. Selecting IS NULL removes the value input. Selecting IN provides a list in which multiple values can be added or removed.

Conditions can be organized into all and any groups:

• Every condition in an all group must be met.
• At least one condition in an any group must be met.
• Separate groups and conditions across resources are combined with AND.
• Multiple any groups can be used to express logic such as any(A, B) AND any(C, D).

The panel describes this logic in plain language and shows a readable summary of each condition. The Requester does not need to understand how the groups are converted to YAML.

Interaction modes

The TUI has separate navigation and editing modes. Separating the modes allows home-row keys to navigate the request without preventing those letters from being typed into a text input.

In navigation mode (left pane):

Shortcut	Action
j / k or down / up arrow	Move to the next or previous request item.
h / l or left / right arrow	Collapse or expand the selected section.
Enter	Move focus to the contextual panel for the selected item.
s or Ctrl+S	Save the request.
?	Show help for the available shortcuts.
q	Quit, with a prompt if there are unsaved changes.

Collapsing or expanding with h and l changes how much of the request is shown in the left pane. Pressing Enter has a different purpose: it moves focus to the right pane so that the selected value can be changed.

In editing mode (right pane):

Shortcut	Action
Tab / Shift+Tab	Move to the next or previous control.
j / k or down / up arrow	Move through a selection list or dropdown.
Space	Toggle the selected choice.
Enter	Open a dropdown or activate the selected control.
/	Search the current resource or column list.
a	Add an item, such as a condition, group, or IN value.
d	Delete the selected item.
Ctrl+Enter	Apply the edits and return to navigation mode.
Esc	Cancel the edits and return to navigation mode.
Ctrl+S	Apply the current edits and save the request.

The footer only shows shortcuts that are relevant to the active context. The arrow keys and common form-navigation keys are provided alongside the Vim-inspired shortcuts so that the interface remains discoverable to users who do not use Vim.

Saving and continuing requests

Saving writes a request.yaml file and updates the timestamps managed by Propagate. The TUI tracks whether the in-memory request differs from the saved file. If the Requester tries to quit with unsaved changes, the TUI asks whether to save, continue editing, or discard the changes. This avoids accidental data loss without making Esc unexpectedly close the application.

New requests are started from a source metadata file with the create-request CLI command. Existing requests are opened through a CLI option rather than a file picker inside the TUI. Keeping file selection in the CLI makes the source and request explicit before the full-screen interface starts and avoids adding a separate opening screen to the TUI. Propagate checks that an existing request matches the supplied data package before allowing resource, column, or row selections to be changed.

The TUI does not include a separate review screen or a preview of the selected data. The left pane continuously summarizes the request and its completion state, while the saved YAML file provides the final detailed representation. The Requester can reopen that file in the TUI to review or change it.