Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js readline.createInterface() method

Reference for readline.createInterface() in Node.js: read input line by line from stdin or any stream, options like crlfDelay, the Interface object and cleanup.

readline.createInterface(options) wraps a readable stream and gives you its content one line at a time. The classic use is reading process.stdin for an interactive prompt, but it works equally well on a file stream, a socket or any other Readable, which makes it the standard way to process large text files without loading them whole.

The returned readline.Interface is an event emitter and an async iterable. It emits a 'line' event per line, a 'close' event at the end, and offers question() for prompts. Lines are split on \n, \r\n or a lone \r, and the line ending is not included in the text you receive.

NODE
import readline from 'node:readline';

const rl = readline.createInterface({ input: process.stdin });
rl.on('line', (line) => console.log('got:', line));

Try it

Node.js Reading lines from a stream

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Processing a file with for await

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
readline.createInterface(options): readline.Interface
readline.createInterface(input[, output[, completer[, terminal]]]): readline.Interface
Name Description
options.input The readable stream to read from (required).
options.output A writable stream for prompts and echoed input, such as process.stdout. Optional for plain line reading.
options.crlfDelay Milliseconds to wait for \n after a \r before treating \r alone as a line end. Use Infinity so \r\n is always one break. Default 100.
options.terminal Treat output as a TTY (enables escape sequences and key handling). Detected automatically by default.
options.prompt The prompt string for rl.prompt(). Default '> '.
options.history, options.historySize Initial history lines and maximum count (default 30), only in terminal mode.
options.completer A function (line) => [matches, prefix] for Tab completion.
options.signal An AbortSignal that closes the interface.
options.tabSize Spaces per tab, at least 1. Default 8.
options.escapeCodeTimeout Wait time for the rest of an escape sequence. Default 500 ms.

Returns: an Interface. Its main members are close(), pause(), resume(), prompt(), setPrompt(), write(), question(), line, cursor, plus [Symbol.asyncIterator].

Errors: a missing or non-stream input throws ERR_INVALID_ARG_TYPE. Errors on the input stream are not forwarded as readline events in all versions, so also watch the input itself.

Usage notes

  • Always set crlfDelay: Infinity for files. Otherwise a \r\n pair split across two chunks can be seen as two line breaks and produce a phantom empty line.
  • The last line needs no newline. A final unterminated line is still delivered.
  • Closing. The interface closes when the input ends, or when you call rl.close(). Closing does not close process.stdin itself; the process exits once nothing else keeps it alive.
  • Prefer iteration over events. for await (const line of rl) gives natural backpressure and straightforward try/catch. Attach the iterator right away: lines emitted before it starts can be lost.
  • No output means no echo. Without output, nothing is printed for the user; this is what you want for batch processing.
  • Large files. Memory use stays flat because only one chunk and one partial line are held at a time.
  • Promise prompts. node:readline/promises offers the same interface with a promise-based question().