Callback API

class readline.Interface extends readline.InterfaceConstructor

Instances of the readline.Interface class are constructed using the readline.createInterface() method. Every instance is associated with a single input Readable stream and a single output Writable stream. The output stream is used to print prompts for user input that arrives on, and is read from, the input stream.

rl.question(query, options?, callback): void

The rl.question() method displays the query by writing it to the output, waits for user input to be provided on input, then invokes the callback function passing the provided input as the first argument.

When called, rl.question() will resume the input stream if it has been paused.

If the readline.Interface was created with output set to null or undefined the query is not written.

The callback function passed to rl.question() does not follow the typical pattern of accepting an Error object or null as the first argument. The callback is called with the provided answer as the only argument.

An error will be thrown if calling rl.question() after rl.close().

Example usage:

rl.question('What is your favorite food? ', (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

Using an AbortController to cancel a question.

const ac = new AbortController();
const signal = ac.signal;

rl.question('What is your favorite food? ', { signal }, (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

setTimeout(() => ac.abort(), 10000);

readline.clearLine(stream, dir, callback?): boolean

The readline.clearLine() method clears current line of given TTY stream in a specified direction identified by dir.

readline.clearScreenDown(stream, callback?): boolean

The readline.clearScreenDown() method clears the given TTY stream from the current position of the cursor down.

readline.createInterface(options): readline.Interface

The readline.createInterface() method creates a new readline.Interface instance.

import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});

const { createInterface } = require('node:readline');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});

Once the readline.Interface instance is created, the most common case is to listen for the 'line' event:

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
});

If terminal is true for this instance then the output stream will get the best compatibility if it defines an output.columns property and emits a 'resize' event on the output if or when the columns ever change (process.stdout does this automatically when it is a TTY).

When creating a readline.Interface using stdin as input, the program will not terminate until it receives an EOF character. To exit without waiting for user input, call process.stdin.unref().

The completer function takes the current line entered by the user as an argument, and returns an Array with 2 entries:

• An Array with matching entries for the completion.
• The substring that was used for the matching.

For instance: [[substr1, substr2, ...], originalsubstring].

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
}

The completer function can be called asynchronously if it accepts two arguments:

function completer(linePartial, callback) {
  callback(null, [['123'], linePartial]);
}

readline.cursorTo(stream, x, y?, callback?): boolean

The readline.cursorTo() method moves cursor to the specified position in a given TTY stream.

readline.moveCursor(stream, dx, dy, callback?): boolean

The readline.moveCursor() method moves the cursor relative to its current position in a given TTY stream.