Console API

Terminal output, ANSI styling, cursor and screen control, and basic input, all exposed as the global Console singleton.

Overview

Console is a singleton that is auto-registered in every script. There is no constructor, and every call is Console.method(...). It covers writing to standard output and standard error, colors and text styles, cursor movement, screen clearing and scrolling, the alternate screen buffer, and line- or byte-level input from standard input.

Console.setColor("green")
Console.writeLine("hello, console")
Console.reset()

Conventions

Singleton. Always called as Console.method(...). There is no constructor; a Console is never created.
Return value. Methods return null. They do not chain. Console.setColor("red").writeLine(...) is a runtime error. Call them as separate statements.
Coordinates. Cursor positions are 1-based: moveCursor(1, 1) is the top-left cell. getWidth() and getHeight() return the current terminal size in cells.
Streams. Plain methods (write, writeLine, writeBuffer, flush) target standard output. The *Err variants (writeErr, writeLineErr, writeBufferErr, isTTYErr) target standard error. ANSI escapes from styling and cursor methods are written to standard output.
Buffers. writeBuffer and writeBufferErr accept a Buffer; raw bytes are emitted as-is, with no encoding conversion.
Booleans. Methods that take a flag (setBold(true), setRawMode(false)) accept a real boolean.
Restore on exit. When the process ends or the Console is finalized, terminal state is restored: SGR is reset, the cursor is shown again, the alternate screen is exited, and raw-mode termios / Windows console mode are restored.
Errors. Bad arguments raise a runtime error in the form Console.method(...): <reason> (e.g. color must be 0..15).

Restore is best-effort: state is put back when the process ends normally or the Console is garbage-collected. A hard kill (SIGKILL) bypasses this. If a script enters raw mode or the alt screen and dies that way, run reset from the shell to recover the terminal.

Windows: the console is switched to UTF-8 and virtual-terminal processing is enabled at first use. Older terminals (legacy cmd.exe without VT support) display escape sequences literally.

Capabilities

Console.getWidth()

Returns the current terminal width in columns. Falls back to 80 if the size can't be queried.

Console.getHeight()

Returns the current terminal height in rows. Falls back to 24 if the size can't be queried.

Console.isTTY()

Returns true if standard output is a terminal.

Console.isTTYErr()

Returns true if standard error is a terminal.

print("size = %nx%n", Console.getWidth(), Console.getHeight())
print("isTTY = %v", Console.isTTY())

Writing

Console.write(s)

Writes s to stdout with no newline.

Console.writeLine(s)

Writes s to stdout followed by \n.

Console.writeErr(s)

Writes s to stderr with no newline.

Console.writeLineErr(s)

Writes s to stderr followed by \n.

Console.writeBuffer(buf)

Writes the raw bytes of a Buffer to stdout. Bytes are emitted as-is, with no encoding conversion.

buf (Buffer) — the buffer whose bytes are written

Console.writeBufferErr(buf)

Writes the raw bytes of a Buffer to stderr.

Console.flush()

Flushes pending stdout. Useful before reading input or before sleeping, since a prompt written without a trailing newline may not appear until it is flushed.

stdout, stderr, and raw bytes

Console.write("no newline ")
Console.writeLine("then a line")
Console.writeLineErr("diagnostics go to stderr")

var b = Buffer.fromString("via buffer\n")
Console.writeBuffer(b)
Console.flush()

Colors & Styles

Every color setter accepts a color in two forms: by index, a number from 0–15 covering the standard 16 ANSI colors, or by name, a string from the table below. The legacy snake_case forms (bright_red, etc.) are also accepted for compatibility.

Name	Bright variant
`black`	`brightBlack` (alias `gray`)
`red`	`brightRed`
`green`	`brightGreen`
`yellow`	`brightYellow`
`blue`	`brightBlue`
`magenta`	`brightMagenta`
`cyan`	`brightCyan`
`white`	`brightWhite`

Console.setColor(c)

Sets the foreground color.

c (number or string) — color index (0–15) or a color name

Console.setBackgroundColor(c)

Sets the background color.

c (number or string) — color index (0–15) or a color name

Console.setColorRGB(r, g, b)

Sets the foreground to a 24-bit truecolor.

r, g, b (number) — color components, each 0–255

Console.setBackgroundColorRGB(r, g, b)

Sets the background to a 24-bit truecolor.

r, g, b (number) — color components, each 0–255

Console.reset()

Clears all color and style attributes, back to the terminal default.

Console.setBold(on)

Enables or disables bold.

Console.setDim(on)

Enables or disables dim.

Console.setItalic(on)

Enables or disables italic.

Console.setUnderline(on)

Enables or disables underline.

Console.setReverse(on)

Enables or disables reverse video.

Console.setStrikethrough(on)

Enables or disables strikethrough.

Truecolor and several styles depend on the terminal. On terminals that don't support them, the escape is still sent and is silently ignored or downgraded by the host. Output remains correct, just unstyled.

Non-TTY output: if stdout is redirected to a file or pipe, color and cursor escapes are still written. Pipe through a tool that strips ANSI, or guard styling with if (Console.isTTY()) { ... }.

truecolor and styles

Console.setColorRGB(255, 128, 0)
Console.write("orange ")
Console.setBold(true)
Console.writeLine("and bold")
Console.reset()

Console.setBackgroundColor("blue")
Console.write(" bg ")
Console.reset()
Console.writeLine("")

Cursor

Console.moveCursor(row, col)

Moves the cursor to an absolute position. Coordinates are 1-based; moveCursor(1, 1) is the top-left cell.

row (number) — target row, 1-based
col (number) — target column, 1-based

Console.moveCursorUp(n?)

Moves the cursor up n rows. n defaults to 1.

Console.moveCursorDown(n?)

Moves the cursor down n rows. n defaults to 1.

Console.moveCursorLeft(n?)

Moves the cursor left n columns. n defaults to 1.

Console.moveCursorRight(n?)

Moves the cursor right n columns. n defaults to 1.

Console.hideCursor()

Hides the cursor. Visibility is restored automatically at finalization.

Console.showCursor()

Shows the cursor.

Console.saveCursorPos()

Saves the current cursor position (DECSC).

Console.restoreCursorPos()

Restores a previously saved position (DECRC).

status line without losing your place

// Draw on the last row, then jump back
Console.saveCursorPos()
Console.moveCursor(Console.getHeight(), 1)
Console.clearLine()
Console.write("READY")
Console.restoreCursorPos()
Console.flush()

Clearing & Scrolling

Console.clear()

Clears the entire screen and homes the cursor.

Console.clearLine()

Clears the current line.

Console.clearToEndOfLine()

Clears from the cursor to the end of the line.

Console.clearToStartOfLine()

Clears from the start of the line to the cursor.

Console.scrollUp(n?)

Scrolls the screen up n lines. n defaults to 1.

Console.scrollDown(n?)

Scrolls the screen down n lines. n defaults to 1.

Screen Modes

Console.useAltScreen()

Switches to the alternate screen buffer, for full-screen TUIs. The previous screen contents are preserved by the terminal.

Console.useMainScreen()

Returns to the main screen. Also done automatically at finalization if the alternate screen was active.

Console.setTitle(s)

Sets the terminal window title.

s (string) — the new title

Console.beep()

Emits an audible/visual bell by writing \a. Many terminals visualize this as a flash; some do nothing.

Input

Console.readLine()

Reads one line from stdin with the trailing newline stripped.

Returns: the line as a string, or null on EOF.

Reading after writing: call Console.flush() before readLine() if a prompt was written without a trailing newline, otherwise the prompt may not appear before the read blocks.

Console.write("name? ")
Console.flush()  // Show the prompt before blocking
var name = Console.readLine()
if (name != null) {
    print("hello, %v", name)
}

Console.readChar()

Reads a single character. In line-buffered mode this still waits for Enter; combine with setRawMode(true) to read keystrokes immediately. Returns one byte. Multi-byte UTF-8 characters and escape sequences (arrow keys, function keys, mouse events) arrive as several bytes, so read repeatedly and parse at the script level when they matter.

Returns: the character as a string, or null on EOF.

Console.hasInput()

Returns true if at least one byte is available on stdin without blocking. It only checks stdin and says nothing about whether stdout is ready to write.

Console.setRawMode(on)

Enables or disables raw mode. In raw mode echo is off and input is delivered byte-by-byte. The mode is restored at finalization regardless.

on (boolean) — true to enter raw mode, false to leave it

Examples

TTY-Aware Styling

func status(label, color) {
    var styled = Console.isTTY()   // Only style real terminals
    if (styled) {
        Console.setColor(color)
        Console.setBold(true)
    }
    Console.write(label)
    if (styled) { Console.reset() }
    Console.writeLine("")
}

status("PASS", "green")
status("FAIL", "brightRed")
print("size = %nx%n", Console.getWidth(), Console.getHeight())

Full-Screen Key Loop

Console.useAltScreen()
Console.clear()
Console.hideCursor()
Console.setRawMode(true)

Console.moveCursor(1, 1)
Console.writeLine("press q to quit")
Console.flush()

while (true) {
    var key = Console.readChar()
    if (key == null or key == "q") { break }
    Console.moveCursor(2, 1)
    Console.clearLine()
    Console.write("key: ")
    Console.write(key)
    Console.flush()
}

// Finalization would restore all of this too; unwinding explicitly is optional
Console.setRawMode(false)
Console.showCursor()
Console.useMainScreen()