terminal

The terminal namespace — 8 functions.

terminal/create

terminal.create(title)

Allocate a terminal (an empty vt100 grid, no process yet) and return its id. Render it with Z.terminal(id); run a process in it with terminal.spawn.

Parameters

• title string — Display title

Returns number — Terminal id

terminal/destroy

terminal.destroy(id)

Kill the child (if any) and remove the terminal from the registry. Raises when no terminal carries id.

Parameters

• id number — Terminal id

terminal/kill

terminal.kill(id)

Terminate the terminal's child process, if running. Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id

terminal/list

terminal.list()

List live terminals as { {id: number, title: string, running: boolean} }.

Returns { {id: number, title: string, running: boolean} } — Live terminals

terminal/poll

terminal.poll()

Drain one-shot lifecycle events as { {id: number, event: string, note: string, ok: boolean} }. event is "exited" when a child ends, note is the reason shown in the pane's ended bar, and ok is whether that child reported success — the difference between someone quitting the program in the pane and the program falling over. Each event is returned once.

Returns { {id: number, event: string, note: string, ok: boolean} } — Lifecycle events

terminal/resize

terminal.resize(id, rows, cols)

Request a PTY resize (rows x cols). The widget resizes automatically; this is for programmatic sizing. Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id
• rows number — Rows
• cols number — Columns

terminal/spawn

terminal.spawn(id, opts)

Open a PTY and run a process in terminal id. opts = {cmd, args?, cwd?, env?, envRemove?} — the full process spec; the engine has no knowledge of what runs. Editor profile only: a shipped runtime never spawns host processes. Raises on platforms with no PTY backend (web).

Parameters

• id number — Terminal id from terminal.create
• opts table — {cmd: string, args: {string}?, cwd: string?, env: {[string]: string}?, envRemove: {string}?}

Returns boolean — true on success

terminal/write

terminal.write(id, bytes)

Queue keystroke bytes to the terminal's PTY (programmatic input; routine typing flows through the focused Z.terminal widget). Raises with no PTY backend, and raises when no terminal carries id.

Parameters

• id number — Terminal id
• bytes string — Bytes to send