read

For reading user input from stdin.

Similar to the readline builtin's question() method, but with a few more features.

Usage

const { read } = require('read')
// or with ESM: import { read } from 'read'
try {
  const result = await read(options)
} catch (er) {
  console.error(er)
}

Options

Every option is optional.

• prompt What to write to stdout before reading input.
• silent Don't echo the output as the user types it.
• replace Replace silenced characters with the supplied character value.
• timeout Number of ms to wait for user input before giving up.
• default The default value if the user enters nothing.
• edit Allow the user to edit the default value.
• terminal Treat the output as a TTY, whether it is or not.
• input Readable stream to get input data from. (default process.stdin)
• output Writable stream to write prompts to. (default: process.stdout)
• completer Autocomplete callback (see official api for details
• history History array, which will be appended to.

If silent is true, and the input is a TTY, then read will set raw mode, and read character by character.

Contributing

Patches welcome.

Changelog

5.0.1 (2025-10-22)

Dependencies

• fa485f3 #139 bump mute-stream from 2.0.0 to 3.0.0 (#139) (@dependabot[bot])

5.0.0 (2025-10-22)

⚠️ BREAKING CHANGES

• read now supports node ^20.17.0 || >=22.9.0

  Bug Fixes

• daa8671 #136 align to npm 11 node engine range (#136) (@owlstronaut)

  Chores

• 2e118b7 #130 bump eslint-import-resolver-typescript from 3.10.0 to 4.3.2 (#130) (@dependabot[bot])
• 47193b3 #137 bump @npmcli/template-oss from 4.27.0 to 4.27.1 (#137) (@dependabot[bot], @npm-cli-bot)

4.1.0 (2025-01-30)

Features

• 980e75c #127 add history parameter (#127) (@JupiterPi)

4.0.0 (2024-09-25)

⚠️ BREAKING CHANGES

• read now supports node ^18.17.0 || >=20.5.0

  Bug Fixes

• eddeb02 #124 align to npm 10 node engine range (@hashtagchris)

  Dependencies

• 0641d3a #124 `mute-stream@2.0.0`

  Chores

• 1b07665 #109 bump c8 from 8.0.1 to 10.1.2 (#109) (@dependabot[bot])
• cdf4cd8 #122 bump @npmcli/eslint-config from 4.0.5 to 5.0.0 (#122) (@dependabot[bot])
• 104dc92 #116 bump tshy from 1.18.0 to 3.0.2 (#116) (@dependabot[bot])
• 8f24ce4 #124 run template-oss-apply (@hashtagchris)
• 8a7ba09 #120 bump @typescript-eslint/parser from 7.18.0 to 8.0.1 (#120) (@dependabot[bot])
• d6beca8 #103 bump @npmcli/template-oss to 4.22.0 (@lukekarrys)
• ff55321 #100 bump @typescript-eslint/parser from 6.21.0 to 7.2.0 (#100) (@dependabot[bot])
• d30350d #123 postinstall for dependabot template-oss PR (@hashtagchris)
• 8558668 #123 bump @npmcli/template-oss from 4.23.1 to 4.23.3 (@dependabot[bot])

3.0.1 (2023-11-20)

Bug Fixes

• 22cb8dc #84 only ship dist files (@lukekarrys)

3.0.0 (2023-11-16)

⚠️ BREAKING CHANGES

• read is now written in TypeScript and types are now shipped as part of this package.

Features

• 18cb7bd #77 convert to typescript and esm (#77) (@lukekarrys)

Documentation

• ada826d #59 remove unnecessary callback param (#59) (@igrep)

2.1.0 (2023-04-13)

Features

• c149cf9 #51 add completer option to forward to readline (#51) (@wraithgar, @131)

Bug Fixes

• c5932e8 #35 Support rare \r line break (#35) (@NikxDa, @wraithgar, @wraithgar)
• f30fe66 #52 extra newline on muted, replaced input (#52) (@wraithgar, @deed02392)

2.0.0 (2022-12-13)

⚠️ BREAKING CHANGES

• this module has been refactored to use promises
  • the API is now promise only and no longer accepts a callback
  • the Promise is resolved to a string and no longer returns isDefault
• this package is now compatible with the following semver range for node: ^14.17.0 || ^16.13.0 || >=18.0.0

Features

• c5b56f6 use async/await (@lukekarrys)
• 5a7563b add template-oss (@lukekarrys)

Documentation

• 711d7cd #30 Fix typo "Writeable" => "Writable" in README.MD (#30) (@vitalymak, @vitalymak)

Dependencies

• 6102578 #42 bump mute-stream from 0.0.8 to 1.0.0 (#42)