Pseudo-terminal for running interactive programs.
Uses forkpty() to create a real PTY — programs like vim, top,
and htop work correctly. The child process gets a proper TTY with
the requested dimensions.
Output is sent as {:data, binary} messages to the calling process.
Exit is reported as {:exit, status} when the child exits naturally.
Calling close/1 may suppress the exit message if the child is
terminated before the reader thread observes the exit.
Examples
{:ok, pty} = Ghostty.PTY.start_link(cmd: "/bin/bash")
Ghostty.PTY.write(pty, "echo hello\n")
receive do: ({:data, data} -> IO.write(data))With a terminal
{:ok, term} = Ghostty.Terminal.start_link(cols: 80, rows: 24)
{:ok, pty} = Ghostty.PTY.start_link(cmd: "/bin/bash", cols: 80, rows: 24)
# In a loop: forward PTY output to terminal, encode key events back to PTYSummary
Functions
Returns a child spec for use in supervision trees.
Closes the PTY and terminates the child process.
Resizes the PTY and sends SIGWINCH to the child.
Starts a PTY process linked to the caller.
Writes data to the PTY (child's stdin).
Types
@type option() :: {:cmd, Path.t()} | {:args, [String.t()]} | {:cols, pos_integer()} | {:rows, pos_integer()} | {:name, GenServer.name()}
Functions
Returns a child spec for use in supervision trees.
@spec close(GenServer.server()) :: :ok
Closes the PTY and terminates the child process.
Raises if the server does not exist.
@spec resize(GenServer.server(), pos_integer(), pos_integer()) :: :ok
Resizes the PTY and sends SIGWINCH to the child.
@spec start_link([option()]) :: GenServer.on_start()
Starts a PTY process linked to the caller.
Output and exit messages are sent to the calling process.
Options
:cmd— command to run (default:$SHELLor/bin/sh):args— argument list (default:[]):cols— terminal width in columns (default:80):rows— terminal height in rows (default:24):name— GenServer name registration
@spec write(GenServer.server(), iodata()) :: :ok
Writes data to the PTY (child's stdin).