rund-0.1.1 is not a library.

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:

Calculates initial file hash
Monitors the process
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

rund 0.1.1