rund

Run CLI apps in detached terminal popup window with configurable size, position, and smart behavior.

A lightweight, cross-platform terminal launcher that opens CLI applications in separate terminal with automatic positioning, smart pause detection, and per-app configuration. Perfect for creating temporary workspaces, viewing files, or running quick scripts without cluttering your main terminal.

Features

• 🚀 Detached Terminal Windows - Launch apps in separate terminal windows that don't block your workflow
• 📐 Configurable Geometry - Set custom window size and position (per-app or globally)
• 🎯 Smart Pause Detection - Automatically determines when to pause based on app type and file size
• 💾 Automatic Backups - Creates backups when files are modified
• 📋 Clipboard Integration - Edit clipboard content directly
• 🎨 Per-App Configuration - Different geometry settings for different applications
• 🪟 Windows Terminal Support - Full support for both cmd.exe and Windows Terminal (wt)
• 🐧 Cross-Platform - Works on Windows, macOS, and Linux
• 🔧 Highly Customizable - Configure app classifications, pause behavior, and more

Installation

From Source

git clone https://github.com/cumulus13/rund
cd rund
cargo build --release

The binary will be at target/release/rund (or rund.exe on Windows).

Add to PATH

Windows:

# Add the directory containing rund.exe to your PATH
$env:Path += ";C:\path\to\rund"

Linux/macOS:

# Copy to a directory in PATH
sudo cp target/release/rund /usr/local/bin/

From Crates.io

cargo install rund

you may need to add Cargo's bin directory to your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Quick Start

# View a file with bat
rund bat file.txt

# Edit a file with nvim
rund nvim document.md

# Edit clipboard content
rund -c -o temp.txt nvim

# Run a Python script
rund "python -m http.server 8000"

# Use specific output file
rund -o C:\temp\notes.txt nvim

Usage

rund [OPTIONS] [APP] [ARGS...]

Options

• -c, --clipboard - Read clipboard content to file before launching
• -o, --output FILE - Specify output file path
• -b, --backup DIR - Override backup directory
• -t, --top - Always-on-top window (macOS/Linux only)
• --config - Show config file location
• -h, --help - Show help message

Examples

# View file with bat (auto-size detection)
rund bat README.md

# Edit file with specific geometry (if configured)
rund nvim config.toml

# Edit clipboard and save to specific path
rund -c -o C:\temp\script.py bat

# Run command with arguments (relative paths work!)
rund bat ..\README.md

# Python REPL with auto-pause
rund python

# Node script with output
rund "node script.js --verbose"

Configuration

Configuration file is automatically created at:

• Windows: %APPDATA%\rund\config.toml or <exe_dir>\config.toml
• Linux: ~/.config/rund/config.toml
• macOS: ~/Library/Application Support/rund/config.toml

Basic Configuration

[terminal]
# Default window geometry
width = 800
height = 600
x = 100
y = 100
auto_position = false

# Windows only: Terminal type
terminal = "cmd"  # or "wt" for Windows Terminal

# Pause behavior: "never", "always", or "auto"
pause_behavior = "auto"

# Backup directory
backup_dir = "backups"

# Default app (optional)
# default_app = "nvim"

App Classifications

Customize which apps are editors, viewers, or always need pause:

# Editors: NEVER pause (they're interactive)
editor_apps = "vim, nvim, nano, emacs, micro, helix, hx, code, subl"

# Viewers: Pause ONLY for small files (<30 lines)
viewer_apps = "bat, less, more, cat, type"

# Always pause: For scripts/interpreters that produce output
always_pause_apps = "python, python3, node, ruby, perl, php"

Per-App Geometry

Configure specific geometry for individual apps:

[bat]
width = 1200
height = 800
x = 200
y = 150
auto_position = false

[nvim]
width = 1000
height = 700
auto_position = true  # Let system decide position

[python]
width = 900
height = 600
x = 300
y = 200

Note: Per-app geometry works with:

• ✅ Windows Terminal (wt)
• ✅ Linux terminals (alacritty, kitty, etc.)
• ✅ macOS Terminal.app
• ⚠️ Windows cmd.exe (position via registry, less reliable)

Smart Pause Behavior

The auto pause behavior intelligently determines when to pause:

App Type	Small File (<30 lines)	Large File (≥30 lines)
Editors (vim, nvim, nano)	No pause	No pause
Viewers (bat, less, cat)	Pause → close	Interactive pager → close
Always Pause (python, node)	Pause → close	Pause → close
Unknown	Pause → close	Pause → close

No manual terminal closing required! All windows auto-close after use.

Platform-Specific Features

Windows

• cmd.exe: Uses registry for position control
• Windows Terminal (wt): Full position and size control

  terminal = "wt"  # Enable Windows Terminal

• Auto-position: When auto_position = true, omits position parameters
• Type command: Automatically pipes large files through more

Linux

Supports multiple terminal emulators (auto-detected):

• alacritty (full geometry control)
• kitty (full geometry control)
• gnome-terminal
• konsole
• xterm

macOS

• Uses AppleScript to control Terminal.app
• Full geometry control with bounds

Advanced Features

Clipboard Editing

Edit your clipboard content in your favorite editor:

# Edit clipboard in nvim
rund -c nvim

# Edit clipboard in bat (view-only)
rund -c bat

# Save to specific file
rund -c -o C:\temp\clipboard.txt bat

Automatic Backups

When editing files with -o or -c flags, rund automatically:

1. Calculates initial file hash
2. Monitors the process
3. Creates timestamped backup if file changed

Backups are saved to ./backups/ (or configured directory):

backups/
  ├── file_1703001234.txt
  ├── file_1703005678.txt
  └── ...

Relative Path Support

Relative paths are automatically converted to absolute paths:

# These work from any directory!
rund bat ..\README.md
rund nvim ..\..\config.toml
rund less ./docs/guide.md

Custom App Detection

Add your own apps to classifications:

# Add custom editor
editor_apps = "vim, nvim, nano, kak, joe, micro"

# Add custom viewer
viewer_apps = "bat, less, glow, mdcat"

# Add custom script interpreter
always_pause_apps = "python, python3, node, deno, bun"

Use Cases

Quick File Viewing

# View with syntax highlighting
rund bat document.md

# View log files
rund less app.log

Temporary Editing

# Edit config quickly
rund nvim config.yaml

# Edit from clipboard
rund -c -o temp.py nvim

Script Running

# Run Python script with visible output
rund "python script.py --verbose"

# Start local server
rund "python -m http.server 8000"

# Run Node script
rund "node build.js"

Code Review

# Different geometry for different tools
rund bat large_file.rs    # Wide window (if configured)
rund nvim small_fix.rs     # Standard editor window

Troubleshooting

Windows Terminal Issues

If you get errors with Windows Terminal:

# Try cmd.exe instead
terminal = "cmd"

Relative Paths Not Working

Make sure you're using the latest version - older versions didn't support relative path conversion.

Terminal Not Closing

Check your pause_behavior setting:

# For apps like bat/less, use:
pause_behavior = "auto"  # or "never"

# NOT:
pause_behavior = "always"  # This requires manual close

File Not Found with Type Command

For large files, use a proper pager:

# Instead of: rund type largefile.txt
rund bat largefile.txt  # Better paging support

Building from Source

Prerequisites

• Rust 1.70 or later
• Cargo

Dependencies

• arboard - Clipboard support
• sha2 - File hashing for backups

Compile

cargo build --release

For smaller binary size:

cargo build --release
strip target/release/rund  # Linux/macOS

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Areas for improvement:

• Additional terminal emulator support
• More smart detection heuristics
• GUI configuration editor
• Plugin system for custom behaviors

License

MIT License - see LICENSE file for details

💻 Author

Hadi Cahyadi

• GitHub: @cumulus13
• Email: cumulus13@gmail.com

Support me on Patreon

Links

• Repository: https://github.com/cumulus13/rund
• Issues: https://github.com/cumulus13/rund/issues
• Documentation: https://docs.rs/rund

Star ⭐ this repo if you find it useful!