Node.js Reference ยท Streams and readline
The readline/promises module
Reference for node:readline/promises: await rl.question(), abort a prompt with an AbortSignal, build a Readline for batched cursor actions, and avoid common pitfalls.
node:readline/promises is the promise flavor of readline. Its createInterface() returns an interface whose rl.question() returns a promise, so a sequence of prompts reads like ordinary top-level code: const name = await rl.question("Name? "). No nested callbacks are needed.
The module also exports Readline, a helper that queues cursor and screen actions (cursorTo, clearLine, and so on) and sends them to a stream in one commit(). Everything else, including events and async iteration, behaves as in the callback-based module.
import readline from "node:readline/promises"; import { stdin as input, stdout as output } from "node:process"; const rl = readline.createInterface({ input, output }); const answer = await rl.question("Your name? "); console.log(`Hello, ${answer}`); rl.close();
Try it
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.
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
import readline from "node:readline/promises"; readline.createInterface(options): readline.Interface rl.question(query: string, options?: { signal?: AbortSignal }): Promise<string> new readline.Readline(stream: Writable, options?: { autoCommit?: boolean })
| Name | Description |
|---|---|
options.input |
The readable stream to read from (required). Often process.stdin. |
options.output |
The writable stream the prompt is written to. Optional. |
options.terminal |
Treat the output as a TTY and enable line editing. Defaults to output.isTTY. |
options.crlfDelay |
Milliseconds to wait for \n after \r. Use Infinity for CRLF input. |
options.signal |
An AbortSignal that closes the interface when aborted. |
query |
Text written before waiting for the answer. |
Returns: question() resolves with the entered line, without the line break.
Errors and edge cases:
- Aborting the signal passed to
question()rejects with anAbortErrorwhosecodeisABORT_ERR. The interface stays usable. - Calling
question()afterrl.close()rejects withERR_USE_AFTER_CLOSE.
Usage notes
- The promise API and the callback API are separate modules. Do not mix
readline/promisesquestion()with the callback style on the same interface. - A single interface can ask many questions in sequence. Create one per input stream and close it when done, otherwise the process stays alive waiting for input.
- Input that arrives before a question is asked is not kept for that question. For fully scripted input, prefer async iteration of lines.
Readlineis a batching tool: queuerl.cursorTo(0).clearLine(0), then callcommit()once. It is handy for progress displays; see readline.cursorTo() and clearLine().- The promise module is stable since Node.js 17.