Terminal User Interface (TUI)

The Torc TUI provides a full-featured terminal interface for managing workflows, designed for HPC users working in terminal-over-SSH environments.

Quick Start

# Option 1: Connect to an existing server
torc-server run &   # Start server in background
torc tui            # Launch the TUI

# Option 2: Standalone mode (auto-starts server)
torc tui --standalone

# Option 3: Start TUI without server (manual connection)
torc tui            # Shows warning, use 'S' to start server

Standalone Mode

Use --standalone for single-machine development or testing:

# Basic standalone mode
torc tui --standalone

# Custom port
torc tui --standalone --port 8090

# Custom database location
torc tui --standalone --database /path/to/workflows.db

In standalone mode, the TUI automatically starts a torc-server process with the specified configuration.

Features

• Workflow Management: Create, initialize, run, submit, cancel, reset, and delete workflows
• Job Management: View details, logs, cancel, terminate, or retry jobs
• Real-time Monitoring: Auto-refresh, manual refresh, color-coded status
• Live Event Streaming: Server-Sent Events (SSE) for real-time job and compute node events
• Server Management: Start/stop torc-server directly from the TUI
• File Viewing: Preview workflow files with search and navigation
• DAG Visualization: Text-based dependency graph

Interface Overview

When the TUI starts, you'll see:

┌─ Torc Management Console ────────────────────────────────────────┐
│ ?: help | n: new | i: init | I: reinit | R: reset | x: run ...  │
└──────────────────────────────────────────────────────────────────┘
┌─ Server ─────────────────────────────────────────────────────────┐
│ http://localhost:8080/torc-service/v1  S: start | K: stop | O: output │
└──────────────────────────────────────────────────────────────────┘
┌─ User Filter ────────────────────────────────────────────────────┐
│ Current: yourname  (press 'w' to change, 'a' for all users)     │
└──────────────────────────────────────────────────────────────────┘
┌─ Workflows [FOCUSED] ────────────────────────────────────────────┐
│ >> 1  | my-workflow    | yourname | Example workflow            │
│    2  | data-pipeline  | yourname | Data processing pipeline    │
└──────────────────────────────────────────────────────────────────┘

Basic Navigation

Workflow Actions

Select a workflow and use these keys:

Most destructive actions show a yes/no confirmation dialog. Recovery (V) is gated by the multiplier prompt modal instead — pressing Enter in that modal both applies the multipliers and confirms the recovery (Esc cancels).

Recovery Prompt

Pressing V or v opens a small modal that pre-fills the default --memory-multiplier (1.5) and --runtime-multiplier (1.4). Tab switches between the two fields, Enter applies them and launches the recovery (Esc cancels). The modal accepts only digits and a single decimal point; invalid input is reported inline.

Handling Existing Output Files

When initializing or re-initializing a workflow, if existing output files are detected, the TUI will show a confirmation dialog listing the files that will be deleted. Press y to proceed with --force or n to cancel.

Job Management

Navigate to the Jobs tab (→ then Tab if needed) to manage individual jobs:

Job Status Colors

• Green: Completed
• Yellow: Running
• Red: Failed
• Magenta: Canceled/Terminated
• Blue: Pending/Scheduled
• Cyan: Ready
• Gray: Blocked

Log Viewer

Press l on a job to view its logs:

File Viewer

Navigate to the Files tab and press Enter on a file to view its contents. The file viewer supports:

• Files up to 1MB
• Binary files show a hex dump preview
• Same navigation keys as the log viewer

Filtering and Sorting

Filtering

When a filter is active, the table title shows it in magenta so you don't lose track of why rows are missing — for example, ▶ Jobs │ filter: Status~failed.

The = shortcut maps the focused pane to a primary column and applies the filter using the selected row's value: Workflows → User, Jobs → Status, Results → Status, Events → Event Type, Files → Name, Compute Nodes → Hostname, Scheduled Nodes → Status. Use it to quickly narrow down to "rows like this one."

Sorting

The Jobs and Results tables support cycling sort indicators in their column headers.

Selection is preserved across sort changes and refreshes — re-sorting the table keeps the row you were looking at highlighted.

Results Tab

The Results tab shows execution results for completed and failed jobs:

Use m and p to surface jobs that exceeded their resource allocation (sort descending and the worst offenders rise to the top).

Events Tab (SSE Live Streaming)

The Events tab shows real-time events from the server using Server-Sent Events (SSE). When you select a workflow and navigate to the Events tab, the TUI establishes a live connection to receive events as they occur.

Event types displayed:

• job_started / job_completed / job_failed - Job lifecycle events
• compute_node_started / compute_node_stopped - Worker node lifecycle
• workflow_started / workflow_reinitialized - Workflow initialization events
• scheduler_node_created - Slurm scheduler events

Features:

• Events appear instantly without polling
• Newest events shown at the top
• Filter by Event Type or Data content using f
• Title shows "[SSE Live]" indicator when connected

Server Management

The TUI can start and manage a torc-server instance:

The server status indicator in the connection bar shows:

• ● (green): Server is running (managed by TUI)
• ○ (yellow): Server was started but has stopped
• No indicator: External server (not managed by TUI)

Connection Settings

Auto-Refresh

Press A to toggle auto-refresh (30-second interval). When enabled, the workflow list and details refresh automatically.

Configuration

The TUI respects Torc's layered configuration system:

1. Interactive changes in TUI (press u to change server URL)
2. Environment variables (TORC_CLIENT__API_URL)
3. Local config file (./torc.toml)
4. User config file (~/.config/torc/config.toml)
5. System config file (/etc/torc/config.toml)
6. Default values

Troubleshooting

"Could not connect to server"

1. Ensure the Torc server is running: torc-server run
2. Check the server URL: press u to update if needed
3. Verify network connectivity

"No log content available"

Logs may not be available if:

• The job hasn't run yet
• You're on a different machine than where jobs ran
• The output directory is in a different location

Screen rendering issues

• Ensure your terminal supports UTF-8 and 256 colors
• Try resizing your terminal window
• Press r to force a refresh

TUI vs Web Dashboard

Choose the TUI for: SSH sessions, HPC environments, quick operations, low-bandwidth connections.

Choose torc-dash for: Rich visualizations, resource plots, team dashboards.