# Torc TUI - Terminal User Interface
A full-featured terminal user interface for managing Torc workflows, designed for HPC users working
in terminal-over-SSH environments. Built with [ratatui](https://ratatui.rs/).
## Quick Start
```bash
# Make sure the Torc server is running
torc-server run
# Launch the TUI
torc tui
```
## Features
### Workflow Management
- **Create workflows** from YAML, JSON, or JSON5 spec files
- **Initialize** workflows to set up job dependencies
- **Run** workflows locally or **submit** to HPC schedulers (Slurm)
- **Cancel**, **reset**, or **delete** workflows
- All destructive actions require confirmation
### Job Management
- **View job details** including full command and status
- **View job logs** (stdout/stderr) with search and navigation
- **Cancel**, **terminate**, or **retry** individual jobs
- Color-coded job status for quick visual scanning
### Real-time Monitoring
- **Auto-refresh** toggle for live updates (30-second interval)
- **Manual refresh** with `r` key
- **Status bar** with operation feedback
- **Color-coded results** showing pass/fail status
### Navigation
- **Two-pane interface**: Workflows list and detail view
- **Tabbed detail views**: Jobs, Files, Events, Results, DAG
- **Column filtering** for all table views
- **Keyboard-driven** interface optimized for SSH
---
## Tutorial
### 1. Starting the TUI
First, ensure the Torc server is running:
```bash
# Start the server
torc-server run
# In another terminal, set server URL (optional)
export TORC_API_URL="http://localhost:8080/torc-service/v1"
# Launch the TUI
torc tui
```
When the TUI starts, you'll see the main interface:
```
┌─ Torc Management Console ────────────────────────────────────────┐
┌─ Server ─────────────────────────────────────────────────────────┐
│ http://localhost:8080/torc-service/v1 (press 'u' to change) │
└──────────────────────────────────────────────────────────────────┘
┌─ 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 │
└──────────────────────────────────────────────────────────────────┘
```
### 2. Basic Navigation
| `↑` / `↓` | Move up/down in the current table |
| `←` / `→` | Switch focus between Workflows and Details panes |
| `Tab` | Switch between detail tabs (Jobs → Files → Events → Results → DAG) |
| `Enter` | Load details for selected workflow |
| `q` | Quit (or close popup/dialog) |
| `?` | Show help popup with all keybindings |
**Try it:** Use arrow keys to select a workflow, press `Enter` to load its details.
### 3. Creating a Workflow
Press `n` to create a new workflow from a spec file:
```
┌─ Create Workflow from Spec File ─────────────────────────────────┐
│ Workflow spec file: ~/workflows/my-workflow.yaml_ │
| `TORC_CLIENT__API_URL` | Torc server API URL | `http://localhost:8080/torc-service/v1` |
| `USER` | Default username filter | Current system user |
### Log File Locations
Job logs are stored in the `output` directory by default:
```
output/
└── job_stdio/
├── job_{workflow_id}_{job_id}_{run_id}.o # stdout
└── job_{workflow_id}_{job_id}_{run_id}.e # stderr
```
---
## 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
### Job actions not working
- Ensure you have the correct permissions
- Check that the server is responsive (press `r` to refresh)
- Some actions only apply to certain job states (e.g., can't retry a completed job)
### Screen rendering issues
- Ensure your terminal supports UTF-8 and 256 colors
- Try resizing your terminal window
- Press `r` to force a refresh
---
## Architecture
The TUI is organized into these modules:
```
src/tui/
├── mod.rs # Entry point and event loop
├── app.rs # Application state and business logic
├── api.rs # Synchronous API client
├── ui.rs # UI rendering with ratatui
├── dag.rs # DAG layout computation
└── components.rs # Reusable UI components
# (dialogs, log viewer, status bar)
```
The TUI is completely synchronous, using the blocking reqwest client—no async runtime overhead,
perfect for resource-constrained HPC environments.
---
## Comparison with torc-dash
| Environment | Terminal/SSH | Web browser |
| Startup | Instant | ~2 seconds |
| Dependencies | None (single binary) | None (single binary) |
| Workflow actions | ✅ | ✅ |
| Job actions | ✅ | ✅ |
| Log viewing | ✅ | ✅ |
| DAG visualization | Text-based | Interactive graph |
| Resource plots | Planned | ✅ |
| Event monitoring | Planned | ✅ |
| File preview | Via logs | ✅ |
Choose the **TUI** for: SSH sessions, HPC environments, quick operations, low-bandwidth connections.
Choose **torc-dash** for: Rich visualizations, file previews, resource plots, team dashboards.