runner

Documentation

Overview

Package runner runs an interactive subprocess from inside a Bubble Tea program: it suspends the TUI (releasing the terminal so the subprocess can take over stdin/stdout/stderr), executes the command, then re-enters the alt-screen once the subprocess exits.

Use it for editors ($EDITOR), pagers (less, man), full-screen TUIs (htop, k9s), or one-shot interactive commands (ssh, kubectl exec). For the duration of the run the TUI is fully suspended — the subprocess owns the terminal.

Usage:

// dispatch from a screen's Update on some key:
cmd := exec.Command(os.Getenv("EDITOR"), "/tmp/scratch")
return s, runner.Run(cmd)

// receive the result on a later Update tick:
case runner.Result:
    s.last = msg // msg.Cmd.ProcessState is populated; msg.Err is the run error

Index

• func Run(cmd *exec.Cmd) tea.Cmd
• func RunWith(opts Options) tea.Cmd
• func RunWithNotice(cmd *exec.Cmd, notice string) tea.Cmd
• type Options
• type Result

Functions

func Run

func Run(cmd *exec.Cmd) tea.Cmd

Run returns a tea.Cmd that suspends the program, runs cmd connected to the controlling terminal, and posts a Result when the subprocess exits. The screen is cleared before the subprocess starts (use RunWith with NoClear=true to opt out).

Plumbing the runner takes care of:

• Stdin/Stdout/Stderr default to os.Stdin/Stdout/Stderr (real TTY file descriptors) when not already set, so the subprocess gets direct terminal access and TIOCGWINSZ works.
• LINES and COLUMNS env vars are populated from the current terminal size, as a fallback for ncurses-style programs that miss the post-resume SIGWINCH on some terminal emulators (htop, top, less are the usual suspects).

func RunWith

func RunWith(opts Options) tea.Cmd

RunWith runs an interactive subprocess with the given options. See Options for the available knobs (notice, screen-clear).

func RunWithNotice

func RunWithNotice(cmd *exec.Cmd, notice string) tea.Cmd

RunWithNotice is shorthand for RunWith(Options{Cmd: cmd, Notice: notice}). The screen is cleared before the notice is printed.

Types

type Options

type Options struct {
	// Cmd is the subprocess to run. Required.
	Cmd *exec.Cmd
	// Notice, when non-empty, is printed once to stderr after the TUI
	// suspends and before the subprocess starts. Use it for slow handoffs
	// (kubectl exec, ssh, anything with a perceptible connect latency) so
	// the user sees feedback instead of a blank gap. The subprocess is
	// free to clear the screen on startup; that's fine, the goal is
	// feedback during the handoff, not a persistent banner.
	Notice string
	// NoClear suppresses the screen clear that normally precedes the
	// subprocess. By default the terminal is cleared so the alt-screen
	// exit doesn't leave TUI artifacts visible during commands that
	// don't repaint (sh -c, echo, short scripts). Set NoClear=true to
	// preserve whatever was on the normal screen prior to the TUI.
	NoClear bool
}

Options configures RunWith. The zero value clears the screen and prints no notice — the right defaults for typical interactive subprocesses.

type Result

type Result struct {
	Cmd *exec.Cmd
	Err error
}

Result is delivered to your screen's Update when the subprocess exits. Cmd is the same *exec.Cmd you submitted (its ProcessState is populated by the OS); Err is non-nil when the process failed to start or exited with a non-zero status (the typical *exec.ExitError).