# `Ghostty.PTY`
[🔗](https://github.com/dannote/ghostty_ex/blob/v0.5.0/lib/ghostty/pty.ex#L1)

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

# `option`

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

# `child_spec`

Returns a child spec for use in supervision trees.

# `close`

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

Closes the PTY and terminates the child process.

Raises if the server does not exist.

# `resize`

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

Resizes the PTY and sends SIGWINCH to the child.

# `start_link`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*