User Guide

This guide will help you install, configure, and use tuirunner (tuir).

---

Installation

To install tuirunner, run the following command:

cargo install tuirunner

This compiles and installs the tuir binary into your Cargo bin directory (e.g., ~/.cargo/bin), which should be in your system's PATH.

---

Quick Start

Create a project directory, generate a configuration, and run all configured tasks:

mkdir my-project && cd my-project
tuir init
tuir run

tuir init does not overwrite an existing runner.config.toml, runner.config.yaml, runner.config.yml, or runner.config.json. Choose a format with --format toml, --format yaml, or --format json.

---

Usage

By default, tuir looks for a configuration file named runner.config.toml in the current working directory.

# Show help message
tuir

# Run all tasks (starts TUI or runs in CLI mode as configured)
tuir run

# Run specific tasks and their dependency subgraphs
tuir run build test

# Run a single specific task directly (short for `tuir run <task-name>`)
# Note: Multiple tasks are not supported in this direct mode.
tuir build

# Run without TUI mode (CLI mode)
tuir --no-tui run

# Specify a custom configuration file path (JSON, YAML, or TOML)
tuir --config custom-config.yaml run
tuir -c custom-config.json run

# Initialize a new configuration file
tuir init

CLI Subcommands

• init: Initialize a new configuration file in the current working directory (default: TOML format).
  • --format <format>: Format of the configuration file (toml, yaml, json).
  • --toml, --yaml, --json: Flags to choose the configuration format.
• run: Execute tasks.
  • [TARGETS]...: Specific task name(s) to run. If none are specified, all tasks defined in the configuration are executed.
• schema: Output the JSON schema of the configuration file and exit immediately. Useful for editor integration.
• completions <shell>: Generate shell completion script to stdout.

Global Options

• -c, --config <path>: Path to the configuration file (default: runner.config.toml).
• --no-tui: Bypass the TUI interface and execute tasks directly in the CLI.

When run with --no-tui, tuir exits with a non-zero status if a selected task fails. This makes the same configuration usable in shell scripts and CI jobs.

---

Configuration

tuirunner supports configuration files in TOML, YAML, and JSON formats.

Example: TOML Configuration (runner.config.toml)

#:schema ./runner.schema.json

tui = true

[tasks.clean]
description = "Clean up the build directory"
run = "echo 'Cleaning build directory...'; sleep 1; echo 'Cleaned!'"

[tasks.codegen]
description = "Generate source code"
run = "echo 'Running codegen...'; sleep 1.5; echo 'Codegen done!'"

[tasks.build]
description = "Build the application"
run = "echo 'Building...'; sleep 2"
depends_on = ["clean", "codegen"]

[tasks.test]
description = "Run test suite"
cmd = "echo 'Running unit tests...'; cargo test" # Prints command execution to logs/console
depends_on = ["build"]

[tasks.deploy]
description = "Deploy the application"
cmd = [
    "echo 'Deploying release...'",
    "sleep 1",
    "echo 'Deployed!'"
]
depends_on = ["build"]
working_dir = "./deploy_script"

Configuration Fields

• tui (boolean, default: true): Enable or disable the TUI mode by default.
• tasks (map of objects): A map defining the tasks, where the key is the task name.
  • description (string, optional): A brief explanation of the task's purpose. Shown for the selected task in the TUI output pane.
  • run (string or list of strings): Command(s) to execute silently. The command strings are executed under sh -c. (Mutually exclusive with cmd).
  • cmd (string or list of strings): Command(s) to execute. Similar to run, but prints the command invocation itself to the logs/console. (Mutually exclusive with run).
  • working_dir (string, optional): The directory where the commands will be executed.
  • depends_on (list of strings, optional): List of task names that must finish successfully before this task can start.

Task names must be unique, cannot be named run, and every depends_on entry must name another configured task. run and cmd are mutually exclusive.

JSON Schema Integration

To enable editor autocompletion and validation for your configuration files, you can generate a schema file:

tuir schema > runner.schema.json

Then reference it at the top of your configuration file:

• TOML: #:schema ./runner.schema.json
• JSON: Add "$schema": "./runner.schema.json" at the root.
• YAML: Use IDE-specific comments or workspace settings to map the schema.

---

Interactive TUI Keybindings

When running in TUI mode, you can use the following keybindings to interact with the application:

Key	Action
↑ / ↓ / j / k	Move selection in the Task List
r / Enter	Run the selected task (and its dependencies)
A	Run all tasks in the list
s	Stop execution of the selected task (skips downstream tasks)
S (Shift+S)	Stop execution of the selected task and continue downstream tasks
c	Clear output logs of the selected task
C (Shift+C)	Clear output logs of all tasks
PgUp / PgDn	Scroll logs up/down by 10 lines
Shift + ↑ / Shift + ↓	Scroll logs up/down line by line
i	Enter "Interactive Input Mode" for the selected running task
Esc (interactive mode)	Exit Interactive Input Mode and return to standard TUI control
q / Esc	Quit the application

---

Known Limitations & Constraints

Platform Compatibility (Windows Native Support)

Currently, tuirunner relies on Unix shell features (sh -c) and POSIX signal handling (libc::kill to negative process group IDs) for task execution and termination (such as stopping tasks via s/S or performing graceful shutdown).

• Windows Limitation: Running tuir directly in a native Windows cmd/PowerShell environment is not fully supported and may lead to execution failures or orphaned background processes when stopping tasks.
• Recommendation: On Windows, it is highly recommended to run tuir within a Unix-like environment, such as WSL (Windows Subsystem for Linux) or Git Bash.

Interactive Input Mode (No PTY)

The "Interactive Input Mode" (triggered by pressing i in the TUI) works by piping key presses directly to the running task's standard input stream.

• Since this does not allocate or wrap the execution inside a true pseudo-terminal (PTY) wrapper, fullscreen terminal applications (like vim, nano), interactive shell prompts, or tools requiring term size queries may fail, render incorrectly, or refuse to run interactively.

Log Persistence

Logs are kept in memory for the current TUI session only. Closing tuir discards them; redirect command output yourself if you need files or long-term retention.

---

Future Roadmap

We plan to implement the following features in upcoming releases:

1. Native Windows Support: Execute commands via cmd.exe /C or PowerShell, and implement Windows-native process tree termination.
2. Log File Archiving: Add a configuration option and a CLI parameter (--log-dir) to persist task execution outputs to log files.
3. PTY Support Investigation: Explore integrating a pseudo-terminal (PTY) library (such as portable-pty) to support full interactive terminal applications inside the TUI.