---
title: "terminal"
description: "The terminal namespace — the engine's Luau API reference for terminal."
section: "API Reference"
slug: "api-terminal"
canonical: "https://origozero.ai/docs/api-terminal"
updated: "2026-08-22T18:22:38.422752126+00:00"
tags: ["api", "reference"]
---

# terminal

The `terminal` namespace — 8 functions.

## terminal/create {#terminal-create}

```lua
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}

```lua
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}

```lua
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}

```lua
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}

```lua
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}

```lua
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}

```lua
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}

```lua
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