Every time I review a Node.js CLI that “sometimes hangs” or “randomly misses input,” I find the same root cause: the code is treating terminal input like a simple prompt() call, but the terminal is a stream, and streams have timing, buffering, and lifecycle rules.\n\nWhen you need to ask a few questions, accept commands, or guide someone through a setup flow, the built-in readline module is the smallest tool that still gives you real control. It sits between process.stdin and process.stdout, turns raw bytes into lines, and gives you a clean interface for prompts, question/answer flows, and event-driven input.\n\nI’m going to show you how I structure readline code so it behaves well in real terminals: it exits when it should, handles Ctrl+C, supports timeouts, validates input, and doesn’t fight the event loop. Along the way, you’ll see complete runnable examples, common mistakes I still see in 2026, and a few patterns that make a plain CLI feel polished without pulling in a big prompt library.\n\n## The Mental Model: readline Is a Thin Layer Over Streams\nNode’s terminal input is a stream (process.stdin). Output is also a stream (process.stdout). readline doesn’t replace that; it wraps it.\n\nI like to picture it as a receptionist sitting between you and the terminal:\n\n- process.stdin is a constant flow of characters (sometimes buffered by the terminal).\n- readline waits for “end of line” boundaries (Enter/Return) and emits a line event.\n- You can also ask a question (rl.question) which temporarily behaves like a one-off prompt.\n\nTwo implications matter immediately:\n\n1) Lifecycle matters: If you create an interface and never close it, Node will usually keep running because stdin is still open.\n\n2) You’re in event land: readline events (line, close, etc.) fire asynchronously. If you mix callbacks, events, and promises without a plan, you’ll get race conditions.\n\nBasic setup looks like this:\n\njavascript\nconst readline = require(‘readline‘);\n\nconst rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n});\n\n\nThat’s the core: you give it an input stream and an output stream. After that, you choose your interaction style: question-based, event-based, or a hybrid.\n\n## Creating an Interface You Can Trust (and Reuse)\nMost quick examples create rl once and then call rl.question(...). That’s fine for toy scripts. For real tools, I recommend two small upgrades:\n\n- Make interface creation a function so you can centralize options.\n- Treat closing as non-optional: close on success, close on abort, close on error.\n\nHere’s a robust factory I use as a starting point:\n\njavascript\nconst readline = require(‘readline‘);\n\nfunction createRl() {\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n terminal: true, // set explicitly; helps when stdin/stdout get piped\n });\n\n // Make Ctrl+C behave predictably.\n rl.on(‘SIGINT‘, () => {\n rl.close();\n });\n\n return rl;\n}\n\nmodule.exports = { createRl };\n\n\nA few notes from experience:\n\n- terminal: true: When you run inside CI or pipe input from a file, readline can behave differently. Being explicit helps you notice those cases.\n- rl.on(‘SIGINT‘): This is the cleanest way to handle Ctrl+C for many CLIs. It triggers close, which gives you one cleanup path.\n\nIf you want richer cancellation (timeouts, external aborts), I’ll show a pattern for that soon.\n\n## Asking Questions: Callback Style vs Promise Style\n### The classic rl.question(query, callback)\nThis is the method most people learn first. It prints a query, waits for a line, then calls your callback with the answer.\n\njavascript\nconst { createRl } = require(‘./createRl‘);\n\nconst rl = createRl();\n\nrl.question(‘What is your age? ‘, (age) => {\n console.log(‘Your age is:‘, age);\n rl.close();\n});\n\n\nThe key detail is the last line: rl.close(). Without it, the process often stays alive.\n\n### A modern pattern: wrap questions in a Promise\nIn 2026, most production Node code is promise-first. I rarely keep callback-style question in the “main flow” of a CLI anymore. Instead, I wrap it once and then write the rest of the CLI with async/await.\n\njavascript\nconst readline = require(‘readline‘);\n\nfunction createRl() {\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n });\n rl.on(‘SIGINT‘, () => rl.close());\n return rl;\n}\n\nfunction ask(rl, query) {\n return new Promise((resolve) => {\n rl.question(query, (answer) => resolve(answer));\n });\n}\n\nasync function main() {\n const rl = createRl();\n\n try {\n const name = (await ask(rl, ‘Project name: ‘)).trim();\n const portRaw = (await ask(rl, ‘Port (3000): ‘)).trim();\n\n const port = portRaw === ‘‘ ? 3000 : Number(portRaw);\n if (!Number.isInteger(port) |
finally).\n- Validation is straightforward.\n\n### Traditional vs modern question flow\nApproach
Where it breaks down
\n
—
—
Nested rl.question callbacks
Gets messy with validation, re-asking, branching
\n
async/await Linear, readable
Default choice for setup-style CLIs
Event-based rl.on(‘line‘)
Harder to “ask question 2 only after question 1”
\n\n## Prompts and REPL-Style Input with rl.setPrompt, rl.prompt, and rl.on(‘line‘)\nIf your CLI behaves like a mini shell (“type commands, press Enter”), stop using rl.question and switch to the line event.\n\nHere’s a runnable example: a tiny task runner that supports add, list, and exit.\n\njavascript\nconst readline = require(‘readline‘);\n\nconst rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n});\n\nrl.setPrompt(‘tasks> ‘);\n\nconst tasks = [];\n\nfunction printHelp() {\n console.log(‘Commands:‘);\n console.log(‘ add Add a task‘);\n console.log(‘ list List tasks‘);\n console.log(‘ exit Quit‘);\n}\n\nrl.on(‘SIGINT‘, () => rl.close());\n\nrl.on(‘line‘, (line) => {\n const input = line.trim();\n if (input === ‘‘) {\n rl.prompt();\n return;\n }\n\n const [command, ...rest] = input.split(‘ ‘);\n const argText = rest.join(‘ ‘).trim();\n\n switch (command) {\n case ‘help‘:\n printHelp();\n break;\n case ‘add‘:\n if (!argText) {\n console.log(‘Please provide task text.‘);\n } else {\n tasks.push({ text: argText, createdAt: new Date().toISOString() });\n console.log(Added: ${argText});\n }\n break;\n case ‘list‘:\n if (tasks.length === 0) {\n console.log(‘No tasks yet.‘);\n } else {\n for (let i = 0; i < tasks.length; i++) {\n console.log(${i + 1}. ${tasks[i].text});\n }\n }\n break;\n case ‘exit‘:\n rl.close();\n return;\n default:\n console.log(Unknown command: ${command});\n printHelp();\n }\n\n rl.prompt();\n});\n\nrl.on(‘close‘, () => {\n console.log(‘\nBye.‘);\n});\n\nprintHelp();\nrl.prompt();\n\n\nTwo details make this feel “right”:\n\n- rl.setPrompt(...) sets the prompt text.\n- rl.prompt() prints it again after each command.\n\nWhen you build a REPL-like tool, rl.on(‘line‘) is the backbone. Then you layer parsing, validation, and output formatting on top.\n\n## Timeouts, Cancellation, and “Don’t Hang Forever” Behavior\nA setup wizard that waits forever is fine in your terminal. In CI, in scripted installs, or when someone forgets the tab open, it becomes annoying.\n\nI solve this by combining readline with AbortController. Even if you don’t cancel often, designing the API to allow cancel makes your code calmer.\n\nHere’s a Promise-based ask() that supports an abort signal and a timeout.\n\njavascript\nconst readline = require(‘readline‘);\n\nfunction createRl() {\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n });\n rl.on(‘SIGINT‘, () => rl.close());\n return rl;\n}\n\nfunction ask(rl, query, { signal } = {}) {\n return new Promise((resolve, reject) => {\n let done = false;\n\n const onAbort = () => {\n if (done) return;\n done = true;\n cleanup();\n reject(new Error(‘Aborted‘));\n };\n\n const cleanup = () => {\n if (signal) signal.removeEventListener(‘abort‘, onAbort);\n };\n\n if (signal) {\n if (signal.aborted) return onAbort();\n signal.addEventListener(‘abort‘, onAbort, { once: true });\n }\n\n rl.question(query, (answer) => {\n if (done) return;\n done = true;\n cleanup();\n resolve(answer);\n });\n });\n}\n\nasync function main() {\n const rl = createRl();\n\n const ac = new AbortController();\n const timeoutId = setTimeout(() => ac.abort(), 60_000);\n\n try {\n const email = (\n await ask(rl, ‘Email (60s timeout): ‘, { signal: ac.signal })\n ).trim();\n console.log(‘You entered:‘, email);\n } catch (err) {\n console.error(String(err.message
process.stdin.isTTY === false), you may want to skip prompting and read config from flags or env vars instead.\n\n### A practical non-interactive rule I actually use\nIf the tool can run in CI or inside scripts, I make a rule like this:\n\n- If process.stdin.isTTY is false:\n – Don’t prompt.\n – Require all needed values via flags/env/config file.\n – If a value is missing, print a clear error and exit with a non-zero code.\n\nThat avoids the worst failure mode: a pipeline that blocks forever because it’s waiting for a prompt nobody will ever see.\n\n## Terminal Polish: pause, resume, write, clearLine, clearScreenDown\nOnce you have the core interaction working, you can make the CLI feel less clunky. readline includes a few methods that help you behave like a “good terminal citizen.”\n\n### rl.pause() and rl.resume()\nThese control whether the input stream is flowing into your readline interface.\n\nI use them when:\n\n- I’m running an async task that should not accept input mid-flight.\n- I’m temporarily handing stdin to another consumer.\n\nExample pattern:\n\njavascript\nrl.pause();\ntry {\n await runLongTask();\n} finally {\n rl.resume();\n rl.prompt();\n}\nrl.write(data)\nrl.write() is useful for simulating input (handy in demos) or pushing text into the output in a way that plays nicely with the current prompt.\n\nOne common use: if you print logs while someone is typing, you can re-render the prompt afterward.\n\n### rl.clearLine(dir) and rl.clearScreenDown()\nThese help with progress updates and redrawing.\n\n- rl.clearLine(0) clears the current line.\n- rl.clearScreenDown() clears everything below the cursor.\n\nA tiny “progress ticker” demo:\n\njavascript\nconst readline = require(‘readline‘);\n\nconst rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n});\n\nlet i = 0;\nconst timer = setInterval(() => {\n i++;\n // Clear current line and write progress.\n rl.clearLine(0);\n rl.write(Working… ${i}s);\n\n if (i >= 5) {\n clearInterval(timer);\n rl.clearLine(0);\n rl.write(‘Done.\n‘);\n rl.close();\n }\n}, 1000);\nrl.close().\n\nI typically enforce this with one of these rules:\n\n- Put the entire interactive flow in a try/finally and close in finally.\n- If you’re building a command shell, close on exit command and on SIGINT.\n\n### 2) Mixing rl.question and rl.on(‘line‘) without a plan\nThese are different interaction styles. If you attach a line listener and also call question, it’s easy to double-handle input.\n\nFix: pick one primary mode.\n\n- Setup wizard: promise-wrapped question.\n- REPL/command shell: line event.\n\n### 3) Not handling Ctrl+C\nSymptom: Ctrl+C dumps you into a half-closed state or prints weird output.\n\nFix: handle SIGINT at the readline level and close.\n\njavascript\nrl.on(‘SIGINT‘, () => rl.close());\njavascript\nasync function askUntil(rl, query, validate, ask) {\n while (true) {\n const answer = (await ask(rl, query)).trim();\n const result = validate(answer);\n if (result.ok) return result.value;\n console.log(result.error);\n }\n}\necho ‘yes‘ node tool.js\n- in CI with no TTY\n\nYour prompt UX changes.\n\nFix: decide on a rule and code it:\n\n- If not TTY, require flags/env vars.\n- Or read stdin as a file-like stream.\n\nIn other words: if you want prompts, you want a TTY.\n\n## Performance and UX Notes for Real CLIs\nMost readline-driven tools are “human speed,” so performance isn’t the main bottleneck. Still, I pay attention to a few hotspots.\n\n### Startup cost and event loop behavior\nCreating a readline interface is cheap; typically it’s not your slow part. The bigger issue is keeping the process alive accidentally.\n\n- If you forget to close, the event loop stays open.\n- If you keep timers or file watchers running, readline isn’t the reason you can’t exit.\n\n### Handling large lines\nBy default, readline reads line-by-line. If you paste a huge blob (like a JSON config), you can spike memory.\n\nPractical guidance:\n\n- For “paste JSON” workflows, set expectations in the prompt and validate size.\n- For truly large inputs, don’t use line-based input; read from a file path or accept stdin as a stream and parse incrementally.\n\n### Progress rendering overhead\nIf you redraw the line too often (like every 10ms), the terminal becomes the bottleneck.\n\nA good range for human-visible progress is usually 100–250ms updates, and sometimes even slower (500ms) is fine.\n\n### AI-assisted workflows (2026 reality)\nI do use AI tools while building CLIs, but I keep them in a narrow lane:\n\n- Generate a draft command parser and validation schema.\n- Draft help text and examples.\n- Create a few test cases for edge inputs.\n\nThen I manually verify the terminal behavior: Ctrl+C, blank lines, piping, and cleanup. Those are exactly the spots assistants tend to miss because they’re not “pure code logic.”\n\n## When I Use readline (and When I Don’t)\nHere’s a direct rule I follow.\n\n### I use readline when:\n- I need minimal dependencies and a small surface area.\n- I’m building a tool with simple prompts (setup wizards, one-time configuration, “confirm before delete”).\n- I want a REPL-like loop with a prompt and commands.\n- I need fine-grained control over lifecycle (close cleanly, handle Ctrl+C, avoid hangs).\n\n### I avoid readline when:\n- I need a rich, multi-select UI, checkboxes, search-as-you-type, or complex layouts. That’s when I reach for a dedicated prompt/TUI library.\n- I need full-screen interfaces (a real terminal UI). readline can fake some of it, but it’s not designed for that.\n- I’m reading bulk input. If the user is going to paste or pipe large content, I prefer reading from files or streaming stdin directly.\n\n### A quick decision table\n
Best default
\n
—
\n
rl.question + async/await
\n
tool> ...) rl.on(‘line‘)
\n
No prompts (flags/env/stdin stream)
\n
readline + muted output
\n\n## The Underused Parts of Readline (That Make CLIs Feel “Pro”)\nMost people only touch createInterface() and question(). There are a few other capabilities that I reach for constantly.\n\n### Autocomplete with completer\nIf you’re building a command shell, autocompletion is the single highest ROI feature you can add. With a completer function, Tab can suggest commands or options.\n\nHere’s a small example that autocompletes command names and a couple of subcommands:\n\njavascript\nconst readline = require(‘readline‘);\n\nconst commands = [‘help‘, ‘add‘, ‘list‘, ‘remove‘, ‘exit‘];\n\nfunction completer(line) {\n const trimmed = line.trimStart();\n\n // Only autocomplete the first word in this simple example.\n const hits = commands.filter((c) => c.startsWith(trimmed));\n return [hits.length ? hits : commands, line];\n}\n\nconst rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n completer,\n});\n\nrl.setPrompt(‘tasks> ‘);\nrl.on(‘SIGINT‘, () => rl.close());\nrl.on(‘line‘, (line) => {\n const cmd = line.trim();\n if (cmd === ‘exit‘) rl.close();\n else console.log(You typed: ${cmd});\n rl.prompt();\n});\n\nrl.prompt();\n\n\nA few real-world tips:\n\n- Keep completion fast. If it needs I/O (reading the filesystem, hitting an API), cache results.\n- Make completion forgiving. Users hit Tab with half-typed inputs all the time.\n- Don’t overbuild it. Even just completing command names makes a CLI feel dramatically better.\n\n### Command history behavior (historySize, duplicates)\nIn interactive shells, command history is both UX and a subtle performance knob. If your CLI is long-running, storing massive history is pointless.\n\nA sensible approach:\n\n- Keep a modest historySize (hundreds or a couple thousand lines, depending on your tool).\n- Optionally remove duplicates if repeated commands clutter history.\n\nEven if you don’t tune it, it’s good to know it exists so you can adjust when a tool is used heavily.\n\n### Recognizing EOF (Ctrl+D) and closing cleanly\nIn many terminals, Ctrl+D indicates “end of input” (EOF). That’s different from Ctrl+C. Users expect both to exit cleanly.\n\nFor a REPL-style tool, the simplest rule is: if input closes, your interface closes.\n\njavascript\nrl.on(‘close‘, () => {\n console.log(‘\nBye.‘);\n process.exitCode = 0;\n});\n\n\nIf your CLI is a setup wizard and stdin closes unexpectedly (for example, the user pipes an empty file), treat it as an error and explain what happened.\n\n## readline/promises: The Cleanest Way to Do Q/A (When Available)\nIf you’re on a Node version that supports it, the readline/promises API gives you an interface where question() returns a Promise directly. Conceptually, it’s what we’ve been hand-rolling with an ask() wrapper.\n\nI still like my own ask() sometimes (because I want abort support, validation loops, and consistent behavior), but the native promise interface can reduce boilerplate.\n\nThe overall shape is similar:\n\n- Create a readline interface\n- await rl.question(...)\n- rl.close() in finally\n\nEven if you don’t use readline/promises, I recommend keeping your code structured as if you could swap it in: one interface factory, one question abstraction, and one cleanup path.\n\n## A Reusable “Wizard” Toolkit (Validation, Defaults, Confirm, Select)\nThe moment your CLI grows beyond a couple prompts, you’ll want small primitives instead of repeating logic. Here’s the set I usually build first:\n\n- askText() for free-form strings (with trimming and default)\n- askNumber() for integers/floats with range checks\n- askConfirm() for yes/no\n- askChoice() for a small list of options\n\nBelow is a complete, runnable example that uses those helpers to build a mini setup wizard. The goal is not to be fancy; it’s to be predictable.\n\njavascript\nconst readline = require(‘readline‘);\n\nfunction createRl() {\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n terminal: true,\n });\n rl.on(‘SIGINT‘, () => rl.close());\n return rl;\n}\n\nfunction ask(rl, query, { signal } = {}) {\n return new Promise((resolve, reject) => {\n let done = false;\n\n const onAbort = () => {\n if (done) return;\n done = true;\n cleanup();\n reject(new Error(‘Aborted‘));\n };\n\n const cleanup = () => {\n if (signal) signal.removeEventListener(‘abort‘, onAbort);\n };\n\n if (signal) {\n if (signal.aborted) return onAbort();\n signal.addEventListener(‘abort‘, onAbort, { once: true });\n }\n\n rl.question(query, (answer) => {\n if (done) return;\n done = true;\n cleanup();\n resolve(answer);\n });\n });\n}\n\nasync function askText(rl, label, { defaultValue, required = false } = {}) {\n const suffix = defaultValue !== undefined ? (${defaultValue}) : ‘‘;\n\n while (true) {\n const raw = await ask(rl, ${label}${suffix}: );\n const value = raw.trim();\n\n if (value === ‘‘ && defaultValue !== undefined) return String(defaultValue);\n if (value === ‘‘ && required) {\n console.log(‘This value is required.‘);\n continue;\n }\n return value;\n }\n}\n\nasync function askNumber(rl, label, { defaultValue, min, max, integer = true } = {}) {\n const suffix = defaultValue !== undefined ? (${defaultValue}) : ‘‘;\n\n while (true) {\n const raw = (await ask(rl, ${label}${suffix}: )).trim();\n if (raw === ‘‘ && defaultValue !== undefined) return Number(defaultValue);\n\n const n = Number(raw);\n const okType = Number.isFinite(n) && (!integer| Number.isInteger(n));\n if (!okType) {\n console.log(integer ? ‘Please enter an integer.‘ : ‘Please enter a number.‘);\n continue;\n }\n if (min !== undefined && n < min) {\n console.log(Must be >= ${min}.);\n continue;\n }\n if (max !== undefined && n > max) {\n console.log(Must be <= ${max}.);\n continue;\n }\n return n;\n }\n}\n\nasync function askConfirm(rl, label, { defaultValue = true } = {}) {\n const hint = defaultValue ? ‘[Y/n]‘ : ‘[y/N]‘;\n\n while (true) {\n const raw = (await ask(rl, ${label} ${hint}: )).trim().toLowerCase();\n if (raw === ‘‘) return defaultValue;\n if ([‘y‘, ‘yes‘].includes(raw)) return true;\n if ([‘n‘, ‘no‘].includes(raw)) return false;\n console.log(‘Please answer yes or no.‘);\n }\n}\n\nasync function askChoice(rl, label, choices) {\n // choices: [{ key: ‘a‘, label: ‘Alpha‘ }, ...]\n console.log(label);\n for (const c of choices) console.log( ${c.key}) ${c.label});\n\n const keys = new Set(choices.map((c) => String(c.key)));\n\n while (true) {\n const raw = (await ask(rl, ‘Select an option: ‘)).trim();\n if (keys.has(raw)) return raw;\n console.log(Valid options: ${[…keys].join(‘, ‘)});\n }\n}\n\nasync function main() {\n if (!process.stdin.isTTY) {\n console.error(‘This setup wizard requires an interactive terminal (TTY).‘);\n process.exitCode = 2;\n return;\n }\n\n const rl = createRl();\n\n try {\n console.log(‘Setup wizard (Ctrl+C to cancel)‘);\n\n const project = await askText(rl, ‘Project name‘, { required: true });\n const port = await askNumber(rl, ‘Port‘, { defaultValue: 3000, min: 1, max: 65535 });\n const useDocker = await askConfirm(rl, ‘Enable Docker support?‘, { defaultValue: true });\n const runtime = await askChoice(rl, ‘Choose runtime mode:‘, [\n { key: ‘1‘, label: ‘Development‘ },\n { key: ‘2‘, label: ‘Production‘ },\n ]);\n\n console.log(‘\nSummary‘);\n console.log(‘- project:‘, project);\n console.log(‘- port:‘, port);\n console.log(‘- docker:‘, useDocker);\n console.log(‘- mode:‘, runtime === ‘1‘ ? ‘Development‘ : ‘Production‘);\n\n const ok = await askConfirm(rl, ‘Write config?‘, { defaultValue: true });\n if (!ok) {\n console.log(‘Canceled.‘);\n process.exitCode = 1;\n return;\n }\n\n console.log(‘Pretending to write config...‘);\n } finally {\n rl.close();\n }\n}\n\nmain().catch((err) => {\n console.error(err);\n process.exitCode = 1;\n});\n\n\nWhat this buys you:\n\n- Default values don’t require duplicate logic.\n- Validation and re-asking are centralized.\n- The “cancel path” is consistent (Ctrl+C closes the interface; finally closes it again safely).\n\n## Handling Secrets: Password/Token Input Without Echo\nA classic readline problem: you want the user to type a password or API token, but you don’t want it echoed back to the terminal.\n\nThere are a few ways to do this. Here’s a simple pattern that’s good enough for many internal tools: override the output behavior while a secret is being typed.\n\njavascript\nconst readline = require(‘readline‘);\n\nfunction createSecretInterface() {\n // We create a writable output wrapper that can mute output.\n const mutableOut = new (require(‘stream‘).Writable)({\n write(chunk, encoding, callback) {\n if (!mutableOut.muted) process.stdout.write(chunk, encoding);\n callback();\n },\n });\n\n mutableOut.muted = false;\n\n const rl = readline.createInterface({\n input: process.stdin,\n output: mutableOut,\n terminal: true,\n });\n\n rl.on(‘SIGINT‘, () => rl.close());\n return { rl, mutableOut };\n}\n\nfunction ask(rl, query) {\n return new Promise((resolve) => rl.question(query, resolve));\n}\n\nasync function main() {\n const { rl, mutableOut } = createSecretInterface();\n\n try {\n const email = (await ask(rl, ‘Email: ‘)).trim();\n\n mutableOut.muted = true;\n const token = (await ask(rl, ‘API token (hidden): ‘)).trim();\n mutableOut.muted = false;\n\n console.log(‘\nReceived:‘);\n console.log(‘- email:‘, email);\n console.log(‘- token length:‘, token.length);\n } finally {\n rl.close();\n }\n}\n\nmain().catch((err) => {\n console.error(err);\n process.exitCode = 1;\n});\n\n\nPractical notes:\n\n- This hides the characters, but it doesn’t draw placeholders. If you want , you can implement that by writing your own masking output logic.\n- Don’t log secrets. Not even in debug mode. If you need troubleshooting, log length or a hash prefix.\n- Decide how you want to handle paste. Some tools treat paste as input like anything else; others warn about it.\n\n## Keypress Mode: When You Need More Than Lines\nMost of the time, line-based input is enough. But sometimes you want keystrokes (arrow keys, single-key shortcuts, ‘press any key to continue’). That’s where readline can still help, but the mental model changes: you’re no longer waiting for a newline; you’re reacting to keypress events.\n\nA lightweight pattern is:\n\n- Enable keypress events on stdin\n- Put stdin into raw mode (TTY only)\n- Listen for keypresses and decide when to exit\n\njavascript\nconst readline = require(‘readline‘);\n\nreadline.emitKeypressEvents(process.stdin);\n\nif (process.stdin.isTTY) process.stdin.setRawMode(true);\n\nconsole.log(‘Press q to quit, or Ctrl+C.‘);\n\nprocess.stdin.on(‘keypress‘, (str, key) => {\n if (key && key.ctrl && key.name === ‘c‘) {\n process.exitCode = 130;\n process.exit();\n }\n\n if (str === ‘q‘) {\n process.exitCode = 0;\n process.exit();\n }\n\n // Example: show what was pressed\n process.stdout.write(You pressed: ${JSON.stringify({ str, key })}\n);\n});\n\n\nThis is not “readline the interface” anymore; it’s more like “readline the helper utilities.” Still, it’s part of the same module, and it’s worth knowing when line-based prompting isn’t enough.\n\n## Edge Cases That Actually Bite in Production\nIf your CLI is used by more than just you, these are the cases I test deliberately.\n\n### 1) Piped stdin (isTTY === false)\nIf you don’t explicitly handle this, you’ll get confusing behavior:\n\n- The tool prints a prompt but nobody sees it (because stdout might be redirected)\n- The tool waits for input that won’t come\n\nMy rule: if you’re prompting, require TTY. If you’re not prompting, design for pipes (read stdin fully or line-by-line as data).\n\n### 2) Ctrl+C during a prompt vs during work\nUsers don’t care what you’re doing; they want Ctrl+C to stop it.\n\n- During prompts: close the interface cleanly and exit with a code that indicates interruption (many tools use 130).\n- During work: either abort the task (if possible) or stop accepting input and exit quickly after cleanup.\n\nThis is where an AbortController shines: you can route both “timeout” and “Ctrl+C” into the same cancellation channel.\n\n### 3) Double-close and “already closed” behavior\nIt’s common to call rl.close() in multiple places (a SIGINT handler and a finally, for example). That’s fine as long as you avoid logic that assumes close happens only once.\n\nI treat close as idempotent at the call site: calling it twice should not break anything. If a cleanup step must happen once, put it behind a flag.\n\n### 4) Printing while the user is typing\nThis is a subtle one. If your tool logs progress while a user is in the middle of typing, your output can “cut through” their prompt line.\n\nThe cheap fix is: don’t spam logs during prompts.\n\nThe nicer fix: clear the line, print your message, then redraw prompt. You can do this manually (clear line + write message + prompt), but be consistent.\n\n### 5) Windows-style newlines and crlfDelay\nWhen reading from files or pasted content, you can see \r\n behavior. There’s a crlfDelay option that influences how carriage returns are treated. If your tool reads from non-terminal streams (files/pipes), be intentional about newline handling.\n\n## Alternatives to readline (and Why I Still Start Here)\nI’m not anti-library. I just don’t reach for a heavy prompt framework by default.\n\nHere’s how I think about alternatives:\n\n- Flags only (process.argv): Great for automation; terrible for onboarding if there are many required values.\n- Environment variables: Great for CI and secrets injection; weak discoverability.\n- Config files: Great for repeatability; adds filesystem complexity (where is it stored? how do you update it?).\n- Prompt libraries: Great UX; more dependencies; sometimes more work to control cancellation/TTY edge cases.\n\nMy typical “mature CLI” path looks like this:\n\n1) Start with flags for all important options (so the tool is scriptable).\n2) Add readline prompts as a convenience layer when values are missing and* stdin is a TTY.\n3) Optionally add a --yes/--non-interactive mode that never prompts.\n4) Only then consider a prompt library if UX requirements justify it.\n\nThat keeps your tool usable both by humans and by automation, without painting yourself into a corner.\n\n## Testing Readline Logic Without a Real Terminal\nTerminal behavior is hard to test end-to-end, but you can test most of your logic by injecting streams. This is one of the reasons I like “create interface” factories: they let me swap process.stdin for a PassThrough stream in tests.\n\nHere’s a small example that “feeds” lines into a wizard-like function:\n\njavascript\nconst readline = require(‘readline‘);\nconst { PassThrough } = require(‘stream‘);\n\nfunction createRlFromStreams(input, output) {\n const rl = readline.createInterface({ input, output, terminal: false });\n return rl;\n}\n\nfunction ask(rl, query) {\n return new Promise((resolve) => rl.question(query, resolve));\n}\n\nasync function runFlow(rl) {\n const name = (await ask(rl, ‘Name: ‘)).trim();\n const age = Number((await ask(rl, ‘Age: ‘)).trim());\n return { name, age };\n}\n\nasync function demo() {\n const input = new PassThrough();\n const output = new PassThrough();\n\n const rl = createRlFromStreams(input, output);\n\n const p = runFlow(rl).finally(() => rl.close());\n\n // Simulate user typing two lines\n input.write(‘Ada Lovelace\n‘);\n input.write(‘36\n‘);\n\n const result = await p;\n console.log(result);\n}\n\ndemo();\n\n\nThis doesn’t prove your cursor movement works, but it does prove your control flow, validation, and cleanup. For many CLIs, that’s 80% of the reliability story.\n\n## A “Never Hang” Checklist I Use Before Shipping\nWhen I’m about to ship a readline-based CLI, I run through this list:\n\n- Does it close the interface on every path (success, validation failure, exception, Ctrl+C)?\n- Does it behave sensibly when process.stdin.isTTY is false?\n- Does it handle Ctrl+D (EOF) cleanly?\n- Do prompts include defaults and constraints so users don’t guess?\n- Are secrets masked and never logged?\n- If it draws progress, does it update at a human rate (100–500ms) and not destroy the prompt line?\n- If it supports long-running tasks, can they be aborted (timeout and/or Ctrl+C)?\n\nMost “readline bugs” aren’t actually complex. They come from treating the terminal like a blocking input box instead of a live stream with a lifecycle. When you design around lifecycle and cancellation first, the rest becomes straightforward—and you can ship a CLI that feels polished without dragging in half the ecosystem.\n\n## Expansion Strategy\nAdd new sections or deepen existing ones with:\n- Deeper code examples: More complete, real-world implementations\n- Edge cases: What breaks and how to handle it\n- Practical scenarios: When to use vs when NOT to use\n- Performance considerations: Before/after comparisons (use ranges, not exact numbers)\n- Common pitfalls: Mistakes developers make and how to avoid them\n- Alternative approaches: Different ways to solve the same problem\n\n## If Relevant to Topic\n- Modern tooling and AI-assisted workflows (for infrastructure/framework topics)\n- Comparison tables for Traditional vs Modern approaches\n- Production considerations: deployment, monitoring, scaling\n
