# "Terminal I/O" _Path: en/lua/system/io_ > "Read from stdin and write to stdout/stderr for CLI applications." ## Table of Contents - Terminal I/O ## Content # Terminal I/O The `io` module reads from standard input and writes to standard output and standard error in terminal applications. This is an API reference. Its snippets are isolated calls; a terminal process should propagate returned structured Lua errors when the result affects control flow. This module is available only to processes running on a Terminal Host, not to regular functions. ## Loading ```lua local io = require("io") ``` ## Writing to Stdout Write values to standard output without a trailing newline: ```lua local ok, err = io.write("text", "more") ``` | Parameter | Type | Description | |-----------|------|-------------| | `...` | any | Variable number of values to write (coerced to string) | **Returns:** `boolean, error` ## Print with Newline Write values to standard output, separated by tabs and followed by a newline: ```lua io.print("value1", "value2", 123) ``` | Parameter | Type | Description | |-----------|------|-------------| | `...` | any | Variable number of values to print | **Returns:** `boolean, error` After terminal context lookup succeeds, output write errors are ignored and the function returns `true`. A missing terminal context returns `nil, "no terminal context"`. ## Writing to Stderr Write values to standard error, separated by tabs and followed by a newline: ```lua io.eprint("Error:", message) ``` | Parameter | Type | Description | |-----------|------|-------------| | `...` | any | Variable number of values to print | **Returns:** `boolean, error` After terminal context lookup succeeds, output write errors are ignored and the function returns `true`. A missing terminal context returns `nil, "no terminal context"`. ## Reading Bytes Read up to `n` bytes from standard input: ```lua local data, err = io.read(1024) ``` | Parameter | Type | Description | |-----------|------|-------------| | `n` | integer | Number of bytes to read (default: 1024, values <= 0 become 1024) | **Returns:** `string, error`. A successful read may return fewer than `n` bytes or an empty string. ## Reading a Line Read one line from standard input: ```lua local line, err = io.readline() ``` **Returns:** `string, error`. The trailing `\n` and `\r` are removed. EOF after partial input returns that partial line; EOF without input returns `nil` and a structured error. ## Raw Mode Enable or disable raw terminal mode, which disables line buffering and echo: ```lua local ok, err = io.raw(true) -- enable local ok, err = io.raw(false) -- disable ``` | Parameter | Type | Description | |-----------|------|-------------| | `enable` | boolean | `true` to enable, `false` to disable (default: `true`) | **Returns:** `boolean, error` Raw mode is reference-counted: each `io.raw(true)` call must be matched by an `io.raw(false)` call. The terminal returns to normal mode automatically when the process exits. ## Flushing Output Flush the standard-output buffer: ```lua local ok, err = io.flush() ``` **Returns:** `boolean, error`. The call is a successful no-op when standard output does not implement `Sync()`. ## Command Line Arguments Retrieve the command-line arguments: ```lua local args = io.args() ``` **Returns:** `string[]` `io.args()` never fails. It returns an empty table when no terminal context is available. ## Errors This module returns structured Lua errors. A missing terminal context uses `errors.UNAVAILABLE`; direct write/flush and invalid yield-response failures use `errors.INTERNAL`. Dispatcher-backed read, readline, and raw-mode failures preserve underlying error metadata when available. `io.args()` has no error return. ## Navigation Previous: "Logging" (lua/system/logger) Next: "Metrics & Telemetry" (lua/system/metrics)