Yet another Open Source run-tui

An interactive terminal UI for running npm scripts concurrently with real-time log viewing

---

Table of Contents

$3

- Overview
- Key Features
- Installation
- Usage

$3

- Available Scripts
- Tech Stack
- Project Structure

---

Overview

yaos-run-tui is a terminal-based user interface for running multiple npm scripts simultaneously. It provides a tabbed interface where you can monitor the output of each script in real-time, switch between tasks, filter logs by type, and manage running processes—all from your terminal.

$3

- Interactive TUI: Navigate between running scripts using arrow keys
- Real-time Logs: Watch stdout and stderr output as it happens
- Log Filtering: Toggle between all logs, stdout only, or stderr only
- Process Management: Kill individual processes or all at once
- Regex Support: Match multiple scripts using regex patterns
- Multiple Package Managers: Works with npm, yarn, pnpm, and bun

---

Key Features

$3

- Tabbed Interface: Each script runs in its own tab with status indicators
- Live Log Streaming: Real-time output from all running processes
- Log Type Filtering: Filter logs by stdout, stderr, or show all
- Stderr Notifications: Visual indicator when a background tab has new stderr output
- Process Control: Kill individual scripts or all running processes
- Graceful Shutdown: Confirmation prompt before killing running tasks

$3

- Simple CLI: Just specify the scripts you want to run
- Regex Patterns: Use -r flag to match scripts by pattern
- Package Manager Agnostic: Works with npm, yarn, pnpm, or bun
- Keyboard Shortcuts: Fast navigation and control

---

Installation

``bash


Install globally from npm

npm install -g @yaos-git/run-tui

Or install as a dev dependency

npm install -D @yaos-git/run-tui
`

$3

`bash


Clone the repository

git clone https://github.com/YAOSGit/run-tui.git
cd run-tui

Install dependencies

npm install

Build the project

npm run build

Link globally (optional)

npm link
`

---

Usage

$3

`bash


Run specific scripts

run-tui dev test

Run scripts matching a regex pattern

run-tui -r "dev." "test."

Use a different package manager

run-tui -p yarn dev test
run-tui -p pnpm dev test
run-tui -p bun dev test
`

$3

| Key | Action |
|-----|--------|
| ← → | Switch between tabs |
| ↑ ↓ | Scroll logs up/down |
| Page Up / Page Down | Scroll logs by page |
| Home / End | Jump to top/bottom of logs |
| n | Add a new script to run |
| x | Close completed task tab |
| k | Kill the current task |
| r | Restart the current task |
| f | Toggle log filter (all → stdout → stderr) |
| q / Esc | Quit (with confirmation if tasks are running) |
| y / n | Confirm or cancel quit |

$3

| Option | Description |
|--------|-------------|
| -v, --version | Display version information |
| -r, --regex | Treat arguments as regex patterns |
| -p, --package-manager | Package manager to use (npm, yarn, pnpm, bun) |
| -k, --keep-alive | Keep TUI open even with no scripts (allows adding scripts with n key) |
| -h, --help | Display help information |

---

Available Scripts

$3

| Script | Description |
|--------|-------------|
| npm run dev | Run TypeScript in watch mode |
| npm run dev:typescript | Run TypeScript type checking in watch mode |
| npm run dev:test | Run tests in watch mode |

$3

| Script | Description |
|--------|-------------|
| npm run build | Bundle the CLI with esbuild |

$3

| Script | Description |
|--------|-------------|
| npm run lint | Run type checking, linting, and formatting |
| npm run lint:check | Check code for linting issues with Biome |
| npm run lint:fix | Check and fix linting issues with Biome |
| npm run lint:format | Format all files with Biome |
| npm run lint:types | Run TypeScript type checking only |

$3

| Script | Description |
|--------|-------------|
| npm test | Run all tests (unit, react, types, e2e) |
| npm run test:unit | Run unit tests |
| npm run test:react | Run React component tests |
| npm run test:types | Run TypeScript type tests |
| npm run test:e2e | Run end-to-end tests |
| npm run ui:vitest | Open Vitest UI with coverage |
| npm run coverage | Run tests with coverage report |

---

Tech Stack

$3

- React 19 - UI component library
- Ink 6 - React for CLIs
- TypeScript 5 - Type-safe JavaScript
- Commander - CLI argument parsing

$3

- esbuild - Fast bundler
- Vitest - Unit testing framework
- Biome - Linter and formatter

$3

- @inkjs/ui - Ink UI components
- Chalk - Terminal string styling

---

Project Structure

`
run-tui/
├── src/
│ ├── app/ # Application entry points
│ │ ├── cli.tsx # CLI entry point
│ │ ├── app.tsx # Main application component
│ │ ├── providers.tsx # Context providers composition
│ │ └── index.tsx # App exports
│ ├── components/ # React components
│ │ ├── TabBar/ # Tab navigation
│ │ ├── LogView/ # Log display area
│ │ ├── Footer/ # Status bar and shortcuts
│ │ ├── ConfirmDialog/ # Generic confirmation dialog
│ │ └── ScriptSelector/ # Script selection UI
│ ├── commands/ # Keyboard command handlers
│ │ ├── closeTab/ # Close tab command
│ │ ├── filter/ # Log filter command
│ │ ├── kill/ # Kill process command
│ │ ├── navigation/ # Tab navigation commands
│ │ ├── newScript/ # Add new script command
│ │ ├── quit/ # Quit application command
│ │ ├── restart/ # Restart process command
│ │ └── scroll/ # Log scroll commands
│ ├── hooks/ # Custom React hooks
│ │ ├── useProcessManager/ # Process spawning and management
│ │ ├── useLogs/ # Log storage and filtering
│ │ ├── useTasksState/ # Task status tracking
│ │ ├── useUIState/ # UI state management
│ │ └── useView/ # View/scroll state management
│ ├── providers/ # React context providers
│ │ ├── CommandsProvider/ # Command registry and execution
│ │ ├── LogsProvider/ # Log entries context
│ │ ├── TasksProvider/ # Task state context
│ │ ├── UIStateProvider/ # UI state context
│ │ └── ViewProvider/ # View state context
│ └── types/ # TypeScript type definitions
│ ├── Command/ # Command type definitions
│ ├── KeyBinding/ # Key binding types
│ ├── LogEntry/ # Log entry types
│ ├── LogType/ # Log type constants
│ ├── PackageManager/ # Package manager types
│ ├── TaskState/ # Task state types
│ ├── TaskStatus/ # Task status constants
│ └── VisibleCommand/ # Visible command types
├── e2e/ # End-to-end tests
│ ├── cli-args.e2e.ts # CLI argument tests
│ ├── keyboard.e2e.ts # Keyboard interaction tests
│ ├── process-lifecycle.e2e.ts # Process lifecycle tests
│ ├── state-transitions.e2e.ts # State transition tests
│ └── utils/ # E2E test utilities
├── dist/ # Built output
├── biome.json # Biome configuration
├── tsconfig.json # TypeScript configuration
├── vitest.config.ts # Vitest configuration
├── vitest.unit.config.ts # Unit test configuration
├── vitest.react.config.ts # React test configuration
├── vitest.type.config.ts # Type test configuration
├── vitest.e2e.config.ts # E2E test configuration
└── package.json
`

---

Versioning

This project uses a custom versioning scheme: MAJORYY.MINOR.PATCH

| Part | Description | Example |
|------|-------------|---------|
| MAJOR | Major version number | 1 |
| YY | Year (last 2 digits) | 25 for 2025 |
| MINOR | Minor version | 0 |
| PATCH | Patch version | 0 |

Example: 125.0.0` = Major version 1, released in 2025, minor 0, patch 0

This format allows you to quickly identify both the major version and the year of release at a glance.

---

License

ISC