Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superfly/sprites-go/llms.txt

Use this file to discover all available pages before exploring further.

Some programs — interactive shells, pagers, text editors, and full-screen TUI applications — require a pseudo-terminal (TTY) to behave correctly. Without one, they may buffer output differently, disable colour rendering, or refuse to start at all. The Sprites Go SDK lets you attach a TTY to any Cmd with a single method call before you start the process.

​
Enabling TTY mode

Call cmd.SetTTY(true) before cmd.Start() to request a pseudo-terminal for the remote process. The method panics if called after the process has already started. 
cmd := sprite.Command("bash")
cmd.SetTTY(true)

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

if err := cmd.Wait(); err != nil {
    log.Fatal(err)
}
SetTTY must be called before Start. Calling it after the process has started causes a panic.

​
Setting terminal dimensions

By default the remote TTY uses the server’s default size. Pass explicit dimensions with cmd.SetTTYSize(rows, cols).

​
Before Start — set the initial size

Call SetTTYSize before Start to negotiate the terminal size at launch time. SetTTYSize returns an error if TTY mode is not enabled. 
cmd := sprite.Command("bash")
cmd.SetTTY(true)

if err := cmd.SetTTYSize(24, 80); err != nil {
    log.Fatal(err)
}

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

​
After Start — resize a running terminal

Call SetTTYSize again on a running command to send a resize event to the remote process. This is how you respond to the local terminal window being resized. 
// Detect a resize event (e.g., from os/signal SIGWINCH) and update
if err := cmd.SetTTYSize(30, 120); err != nil {
    log.Printf("resize failed: %v", err)
}
SetTTYSize works both before and after Start. It is the preferred way to control terminal dimensions in new code.

​
cmd.Resize (deprecated)

Resize is an older method that only works after Start and was superseded by SetTTYSize. It is kept for compatibility but new code should use SetTTYSize instead. 
// Deprecated — use SetTTYSize instead
err = cmd.Resize(30, 100)
Calling Resize before Start returns an error. Use SetTTYSize to set the initial size before starting the process.

​
When to use TTY mode

TTY mode is needed whenever the remote program checks whether its standard streams are connected to a terminal:
  • Interactive shells (bash, sh, zsh)
  • Pagers (less, more)
  • Text editors (vi, vim, nano)
  • Full-screen TUI applications (htop, ncdu, custom curses apps)
  • Programs that use terminal escape codes for colour or cursor control
Plain commands like echo, ls, grep, or cat do not need TTY mode and will work fine without it.

​
Running bash interactively

The example below attaches the local process’s stdin and stdout to a remote bash session, giving the user a fully interactive shell.
1

Enable TTY and set the initial terminal size

cmd := sprite.Command("bash")
cmd.SetTTY(true)

if err := cmd.SetTTYSize(24, 80); err != nil {
    log.Fatal(err)
}
2

Attach local stdin and stdout

cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
3

Start and wait

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

if err := cmd.Wait(); err != nil {
    log.Fatal(err)
}
4

Handle runtime resizes (optional)

Listen for SIGWINCH on Unix and forward new terminal dimensions while the command runs.
sigCh := make(chan os.Signal, 1)
signal.Notify(sigCh, syscall.SIGWINCH)

go func() {
    for range sigCh {
        ws, err := term.GetSize(int(os.Stdout.Fd()))
        if err != nil {
            continue
        }
        _ = cmd.SetTTYSize(uint16(ws.Height), uint16(ws.Width))
    }
}()

​
Using context with TTY commands

TTY mode works with CommandContext. If the context is cancelled — for example, because the user pressed a cancel button in a UI — the remote process is killed. 
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

cmd := sprite.CommandContext(ctx, "bash")
cmd.SetTTY(true)

if err := cmd.SetTTYSize(24, 80); err != nil {
    log.Fatal(err)
}

cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

// cancel() called elsewhere will terminate the remote shell
if err := cmd.Wait(); err != nil {
    log.Fatal(err)
}

​
Sending signals to interactive processes

With TTY mode enabled you can still use cmd.Signal to deliver signals to the remote process — useful when you need to interrupt or terminate a long-running interactive command programmatically rather than waiting for user input. 
// Interrupt the running process (equivalent to Ctrl-C)
if err := cmd.Signal("INT"); err != nil {
    log.Printf("signal error: %v", err)
}
Valid signal names: INT, TERM, HUP, KILL, QUIT, USR1, USR2.

Build docs developers (and LLMs) love

Get started for freeTalk to us