Skip to main content

Terminal

O tty​

Low-level terminal control. Writes go directly to the attached PTY and are mirrored to the daemon event stream.

PTY required

Every tty.* method other than tty.size() will throw when no PTY is attached — for example when stdout is piped or when running under a CI runner. Scripts that need to support both modes should probe at startup:

let hasTTY = true;
try { tty.write(''); } catch { hasTTY = false; }

Fall back to console.log if hasTTY is false.

F tty.write​

write(...args: any[]): void

Writes raw data to the TTY. Arguments are joined with spaces.

tty.write("hello world\n");

F tty.size​

size(): { rows: number; cols: number }

Safe to call without a PTY — defaults to { rows: 24, cols: 80 }.

const { rows, cols } = tty.size();

F tty.clear​

clear(): void

Clears the screen and moves the cursor to the top-left.

F tty.move​

move(row: number, col: number): void

Moves the cursor to the given position (0-based).

F tty.hideCursor​

hideCursor(): void

Hides the terminal cursor.

F tty.showCursor​

showCursor(): void

Shows the terminal cursor.

F tty.alt​

alt(): void

Switches to the alternate screen buffer.

F tty.main​

main(): void

Switches back to the main screen buffer.

F tty.eraseLine​

eraseLine(): void

Erases the current line and returns the cursor to the start of it.

F tty.title​

title(str: string): void

Sets the terminal window title.

F tty.frame​

frame(callback: () => void): void
beginFrame(): void
endFrame(): void

Buffers all tty.* writes and flushes them in a single atomic write, wrapped in Synchronized Output Mode escapes. Capable terminals defer repaint until the end, so the user never sees a half-drawn frame.

function render() {
  const { rows, cols } = tty.size();
  tty.frame(() => {
    tty.move(0, 0);
    tty.write(style.bold("DASHBOARD"));
    // ...all your draw calls...
  });
}
  • Frames nest — only the outermost frame emits the sync begin/end and flushes.
  • Exception-safe — if the callback throws, the buffer is still flushed.
  • Not a compositor — frames coalesce bytes, not cells. The runtime has no virtual screen and won't elide redundant moves or overdraws.

tty.beginFrame() / tty.endFrame() are available if you need to span a frame across an async boundary.

O style​

(text: string) => string        // all color and formatting helpers
style.fg(text: string, r: number, g: number, b: number) => string
style.bg(text: string, r: number, g: number, b: number) => string

Pure-string ANSI styling utilities. Functions can be nested.

console.log(style.bold(style.green("success")));

Foreground colors​

F style.black

black(text: string): string

F style.red

red(text: string): string

F style.green

green(text: string): string

F style.yellow

yellow(text: string): string

F style.blue

blue(text: string): string

F style.magenta

magenta(text: string): string

F style.purple

purple(text: string): string

F style.cyan

cyan(text: string): string

F style.white

white(text: string): string

F style.brightBlack

brightBlack(text: string): string

F style.brightRed

brightRed(text: string): string

F style.brightGreen

brightGreen(text: string): string

F style.brightYellow

brightYellow(text: string): string

F style.brightBlue

brightBlue(text: string): string

F style.brightMagenta

brightMagenta(text: string): string

F style.brightCyan

brightCyan(text: string): string

F style.brightWhite

brightWhite(text: string): string

Background colors​

F style.bgBlack

bgBlack(text: string): string

F style.bgRed

bgRed(text: string): string

F style.bgGreen

bgGreen(text: string): string

F style.bgYellow

bgYellow(text: string): string

F style.bgBlue

bgBlue(text: string): string

F style.bgMagenta

bgMagenta(text: string): string

F style.bgCyan

bgCyan(text: string): string

F style.bgWhite

bgWhite(text: string): string

F style.bgBrightBlack

bgBrightBlack(text: string): string

F style.bgBrightRed

bgBrightRed(text: string): string

F style.bgBrightGreen

bgBrightGreen(text: string): string

F style.bgBrightYellow

bgBrightYellow(text: string): string

F style.bgBrightBlue

bgBrightBlue(text: string): string

F style.bgBrightMagenta

bgBrightMagenta(text: string): string

F style.bgBrightCyan

bgBrightCyan(text: string): string

F style.bgBrightWhite

bgBrightWhite(text: string): string

F style.bold​

bold(text: string): string

Bold text.

F style.dim​

dim(text: string): string

Dimmed text.

F style.italic​

italic(text: string): string

Italic text.

F style.underline​

underline(text: string): string

Underlined text.

blink(text: string): string

Blinking text. Terminal support varies.

F style.reversed​

reversed(text: string): string

Swaps foreground and background colors.

F style.hidden​

hidden(text: string): string

Hidden text.

F style.strikethrough​

strikethrough(text: string): string

Strikethrough text.

F style.reset​

reset(text: string): string

Strips all styling.

F style.fg​

fg(text: string, r: number, g: number, b: number): string

Applies a foreground color using an RGB triple (0–255 each).

Quantized to 16-color ANSI

These helpers do not emit 24-bit truecolor escapes. Each RGB triple is quantized to the closest ANSI 16-color code. Smooth gradients will collapse to a handful of distinct colors. Probe with JSON.stringify(style.fg('x', r, g, b)) to see the actual escape sequence.

F style.bg​

bg(text: string, r: number, g: number, b: number): string

Applies a background color using an RGB triple (0–255 each).