Ghostty.PTY (Ghostty v0.4.7)

Copy Markdown View Source

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 PTY

Summary

Types

option()

Functions

child_spec(init_arg)

Returns a child spec for use in supervision trees.

close(pty)

Closes the PTY and terminates the child process.

resize(pty, cols, rows)

Resizes the PTY and sends SIGWINCH to the child.

start_link(opts \\ [])

Starts a PTY process linked to the caller.

write(pty, data)

Writes data to the PTY (child's stdin).

Types

option()

@type option() ::
  {:cmd, Path.t()}
  | {:args, [String.t()]}
  | {:cols, pos_integer()}
  | {:rows, pos_integer()}
  | {:reader_start_timeout, timeout()}
  | {:name, GenServer.name()}

Functions

child_spec(init_arg)

Returns a child spec for use in supervision trees.

close(pty)

@spec close(GenServer.server()) :: :ok

Closes the PTY and terminates the child process.

Raises if the server does not exist.

resize(pty, cols, rows)

@spec resize(GenServer.server(), pos_integer(), pos_integer()) :: :ok

Resizes the PTY and sends SIGWINCH to the child.

start_link(opts \\ [])

@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: $SHELL or /bin/sh)
  • :args — argument list (default: [])
  • :cols — terminal width in columns (default: 80)
  • :rows — terminal height in rows (default: 24)
  • :reader_start_timeout — how long to wait for the PTY reader thread to start (default: 1_000)
  • :name — GenServer name registration

write(pty, data)

@spec write(GenServer.server(), iodata()) :: :ok

Writes data to the PTY (child's stdin).