1# TTY 2 3<!--introduced_in=v0.10.0--> 4 5> Stability: 2 - Stable 6 7<!-- source_link=lib/tty.js --> 8 9The `node:tty` module provides the `tty.ReadStream` and `tty.WriteStream` 10classes. In most cases, it will not be necessary or possible to use this module 11directly. However, it can be accessed using: 12 13```js 14const tty = require('node:tty'); 15``` 16 17When Node.js detects that it is being run with a text terminal ("TTY") 18attached, [`process.stdin`][] will, by default, be initialized as an instance of 19`tty.ReadStream` and both [`process.stdout`][] and [`process.stderr`][] will, by 20default, be instances of `tty.WriteStream`. The preferred method of determining 21whether Node.js is being run within a TTY context is to check that the value of 22the `process.stdout.isTTY` property is `true`: 23 24```console 25$ node -p -e "Boolean(process.stdout.isTTY)" 26true 27$ node -p -e "Boolean(process.stdout.isTTY)" | cat 28false 29``` 30 31In most cases, there should be little to no reason for an application to 32manually create instances of the `tty.ReadStream` and `tty.WriteStream` 33classes. 34 35## Class: `tty.ReadStream` 36 37<!-- YAML 38added: v0.5.8 39--> 40 41* Extends: {net.Socket} 42 43Represents the readable side of a TTY. In normal circumstances 44[`process.stdin`][] will be the only `tty.ReadStream` instance in a Node.js 45process and there should be no reason to create additional instances. 46 47### `readStream.isRaw` 48 49<!-- YAML 50added: v0.7.7 51--> 52 53A `boolean` that is `true` if the TTY is currently configured to operate as a 54raw device. 55 56This flag is always `false` when a process starts, even if the terminal is 57operating in raw mode. Its value will change with subsequent calls to 58`setRawMode`. 59 60### `readStream.isTTY` 61 62<!-- YAML 63added: v0.5.8 64--> 65 66A `boolean` that is always `true` for `tty.ReadStream` instances. 67 68### `readStream.setRawMode(mode)` 69 70<!-- YAML 71added: v0.7.7 72--> 73 74* `mode` {boolean} If `true`, configures the `tty.ReadStream` to operate as a 75 raw device. If `false`, configures the `tty.ReadStream` to operate in its 76 default mode. The `readStream.isRaw` property will be set to the resulting 77 mode. 78* Returns: {this} The read stream instance. 79 80Allows configuration of `tty.ReadStream` so that it operates as a raw device. 81 82When in raw mode, input is always available character-by-character, not 83including modifiers. Additionally, all special processing of characters by the 84terminal is disabled, including echoing input 85characters. <kbd>Ctrl</kbd>+<kbd>C</kbd> will no longer cause a `SIGINT` when 86in this mode. 87 88## Class: `tty.WriteStream` 89 90<!-- YAML 91added: v0.5.8 92--> 93 94* Extends: {net.Socket} 95 96Represents the writable side of a TTY. In normal circumstances, 97[`process.stdout`][] and [`process.stderr`][] will be the only 98`tty.WriteStream` instances created for a Node.js process and there 99should be no reason to create additional instances. 100 101### Event: `'resize'` 102 103<!-- YAML 104added: v0.7.7 105--> 106 107The `'resize'` event is emitted whenever either of the `writeStream.columns` 108or `writeStream.rows` properties have changed. No arguments are passed to the 109listener callback when called. 110 111```js 112process.stdout.on('resize', () => { 113 console.log('screen size has changed!'); 114 console.log(`${process.stdout.columns}x${process.stdout.rows}`); 115}); 116``` 117 118### `writeStream.clearLine(dir[, callback])` 119 120<!-- YAML 121added: v0.7.7 122changes: 123 - version: v12.7.0 124 pr-url: https://github.com/nodejs/node/pull/28721 125 description: The stream's write() callback and return value are exposed. 126--> 127 128* `dir` {number} 129 * `-1`: to the left from cursor 130 * `1`: to the right from cursor 131 * `0`: the entire line 132* `callback` {Function} Invoked once the operation completes. 133* Returns: {boolean} `false` if the stream wishes for the calling code to wait 134 for the `'drain'` event to be emitted before continuing to write additional 135 data; otherwise `true`. 136 137`writeStream.clearLine()` clears the current line of this `WriteStream` in a 138direction identified by `dir`. 139 140### `writeStream.clearScreenDown([callback])` 141 142<!-- YAML 143added: v0.7.7 144changes: 145 - version: v12.7.0 146 pr-url: https://github.com/nodejs/node/pull/28721 147 description: The stream's write() callback and return value are exposed. 148--> 149 150* `callback` {Function} Invoked once the operation completes. 151* Returns: {boolean} `false` if the stream wishes for the calling code to wait 152 for the `'drain'` event to be emitted before continuing to write additional 153 data; otherwise `true`. 154 155`writeStream.clearScreenDown()` clears this `WriteStream` from the current 156cursor down. 157 158### `writeStream.columns` 159 160<!-- YAML 161added: v0.7.7 162--> 163 164A `number` specifying the number of columns the TTY currently has. This property 165is updated whenever the `'resize'` event is emitted. 166 167### `writeStream.cursorTo(x[, y][, callback])` 168 169<!-- YAML 170added: v0.7.7 171changes: 172 - version: v12.7.0 173 pr-url: https://github.com/nodejs/node/pull/28721 174 description: The stream's write() callback and return value are exposed. 175--> 176 177* `x` {number} 178* `y` {number} 179* `callback` {Function} Invoked once the operation completes. 180* Returns: {boolean} `false` if the stream wishes for the calling code to wait 181 for the `'drain'` event to be emitted before continuing to write additional 182 data; otherwise `true`. 183 184`writeStream.cursorTo()` moves this `WriteStream`'s cursor to the specified 185position. 186 187### `writeStream.getColorDepth([env])` 188 189<!-- YAML 190added: v9.9.0 191--> 192 193* `env` {Object} An object containing the environment variables to check. This 194 enables simulating the usage of a specific terminal. **Default:** 195 `process.env`. 196* Returns: {number} 197 198Returns: 199 200* `1` for 2, 201* `4` for 16, 202* `8` for 256, 203* `24` for 16,777,216 colors supported. 204 205Use this to determine what colors the terminal supports. Due to the nature of 206colors in terminals it is possible to either have false positives or false 207negatives. It depends on process information and the environment variables that 208may lie about what terminal is used. 209It is possible to pass in an `env` object to simulate the usage of a specific 210terminal. This can be useful to check how specific environment settings behave. 211 212To enforce a specific color support, use one of the below environment settings. 213 214* 2 colors: `FORCE_COLOR = 0` (Disables colors) 215* 16 colors: `FORCE_COLOR = 1` 216* 256 colors: `FORCE_COLOR = 2` 217* 16,777,216 colors: `FORCE_COLOR = 3` 218 219Disabling color support is also possible by using the `NO_COLOR` and 220`NODE_DISABLE_COLORS` environment variables. 221 222### `writeStream.getWindowSize()` 223 224<!-- YAML 225added: v0.7.7 226--> 227 228* Returns: {number\[]} 229 230`writeStream.getWindowSize()` returns the size of the TTY 231corresponding to this `WriteStream`. The array is of the type 232`[numColumns, numRows]` where `numColumns` and `numRows` represent the number 233of columns and rows in the corresponding TTY. 234 235### `writeStream.hasColors([count][, env])` 236 237<!-- YAML 238added: 239 - v11.13.0 240 - v10.16.0 241--> 242 243* `count` {integer} The number of colors that are requested (minimum 2). 244 **Default:** 16. 245* `env` {Object} An object containing the environment variables to check. This 246 enables simulating the usage of a specific terminal. **Default:** 247 `process.env`. 248* Returns: {boolean} 249 250Returns `true` if the `writeStream` supports at least as many colors as provided 251in `count`. Minimum support is 2 (black and white). 252 253This has the same false positives and negatives as described in 254[`writeStream.getColorDepth()`][]. 255 256```js 257process.stdout.hasColors(); 258// Returns true or false depending on if `stdout` supports at least 16 colors. 259process.stdout.hasColors(256); 260// Returns true or false depending on if `stdout` supports at least 256 colors. 261process.stdout.hasColors({ TMUX: '1' }); 262// Returns true. 263process.stdout.hasColors(2 ** 24, { TMUX: '1' }); 264// Returns false (the environment setting pretends to support 2 ** 8 colors). 265``` 266 267### `writeStream.isTTY` 268 269<!-- YAML 270added: v0.5.8 271--> 272 273A `boolean` that is always `true`. 274 275### `writeStream.moveCursor(dx, dy[, callback])` 276 277<!-- YAML 278added: v0.7.7 279changes: 280 - version: v12.7.0 281 pr-url: https://github.com/nodejs/node/pull/28721 282 description: The stream's write() callback and return value are exposed. 283--> 284 285* `dx` {number} 286* `dy` {number} 287* `callback` {Function} Invoked once the operation completes. 288* Returns: {boolean} `false` if the stream wishes for the calling code to wait 289 for the `'drain'` event to be emitted before continuing to write additional 290 data; otherwise `true`. 291 292`writeStream.moveCursor()` moves this `WriteStream`'s cursor _relative_ to its 293current position. 294 295### `writeStream.rows` 296 297<!-- YAML 298added: v0.7.7 299--> 300 301A `number` specifying the number of rows the TTY currently has. This property 302is updated whenever the `'resize'` event is emitted. 303 304## `tty.isatty(fd)` 305 306<!-- YAML 307added: v0.5.8 308--> 309 310* `fd` {number} A numeric file descriptor 311* Returns: {boolean} 312 313The `tty.isatty()` method returns `true` if the given `fd` is associated with 314a TTY and `false` if it is not, including whenever `fd` is not a non-negative 315integer. 316 317[`process.stderr`]: process.md#processstderr 318[`process.stdin`]: process.md#processstdin 319[`process.stdout`]: process.md#processstdout 320[`writeStream.getColorDepth()`]: #writestreamgetcolordepthenv 321