README.md

   1 # node-pty
   2
   3 [![Build Status](https://dev.azure.com/vscode/node-pty/_apis/build/status/Microsoft.node-pty)](https://dev.azure.com/vscode/node-pty/_build/latest?definitionId=11)
   4
   5 `forkpty(3)` bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.
   6
   7 This is useful for:
   8
   9 - Writing a terminal emulator (eg. via [xterm.js](https://github.com/sourcelair/xterm.js)).
  10 - Getting certain programs to *think* you're a terminal, such as when you need a program to send you control sequences.
  11
  12 `node-pty` supports Linux, macOS and Windows. Windows support is possible by utilizing the [Windows conpty API](https://blogs.msdn.microsoft.com/commandline/2018/08/02/windows-command-line-introducing-the-windows-pseudo-console-conpty/) on Windows 1809+ and the [winpty](https://github.com/rprichard/winpty) library in older version.
  13
  14 ## Real-world Uses
  15
  16 `node-pty` powers many different terminal emulators, including:
  17
  18 - [Microsoft Visual Studio Code](https://code.visualstudio.com)
  19 - [Hyper](https://hyper.is/)
  20 - [Upterm](https://github.com/railsware/upterm)
  21 - [Script Runner](https://github.com/ioquatix/script-runner) for Atom.
  22 - [Theia](https://github.com/theia-ide/theia)
  23 - [FreeMAN](https://github.com/matthew-matvei/freeman) file manager
  24 - [atom-xterm](https://atom.io/packages/atom-xterm) - Atom plugin for providing terminals inside your Atom workspace.
  25 - [Termination](https://atom.io/packages/termination) - Another Atom plugin that provides terminals inside your Atom workspace.
  26 - [electerm](https://github.com/electerm/electerm) Terminal/ssh/sftp client(linux, mac, win).
  27 - [Extraterm](http://extraterm.org/)
  28 - [Wetty](https://github.com/krishnasrinivas/wetty) Browser based Terminal over HTTP and HTTPS
  29
  30 Do you use node-pty in your application as well? Please open a [Pull Request](https://github.com/Tyriar/node-pty/pulls) to include it here. We would love to have it in our list.
  31
  32 ## Example Usage
  33
  34 ```js
  35 var os = require('os');
  36 var pty = require('node-pty');
  37
  38 var shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
  39
  40 var ptyProcess = pty.spawn(shell, [], {
  41   name: 'xterm-color',
  42   cols: 80,
  43   rows: 30,
  44   cwd: process.env.HOME,
  45   env: process.env
  46 });
  47
  48 ptyProcess.on('data', function(data) {
  49   process.stdout.write(data);
  50 });
  51
  52 ptyProcess.write('ls\r');
  53 ptyProcess.resize(100, 40);
  54 ptyProcess.write('ls\r');
  55 ```
  56
  57 ## Building
  58
  59 ```bash
  60 # Install dependencies and build C++
  61 npm install
  62 # Compile TypeScript -> JavaScript
  63 npm run tsc
  64 ```
  65
  66 ## Dependencies
  67
  68 ### Linux/Ubuntu
  69
  70 ```
  71 sudo apt install -y make python build-essential
  72 ```
  73
  74 The following are also needed:
  75
  76 - Node.JS 10+
  77
  78 ### Windows
  79
  80 `npm install` requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:
  81
  82 ```sh
  83 npm install --global --production windows-build-tools
  84 ```
  85
  86 The following are also needed:
  87
  88 - [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) - only the "Desktop C++ Apps" components are needed to be installed
  89 - Node.JS 10+
  90
  91 ## Debugging
  92
  93 [The wiki](https://github.com/Microsoft/node-pty/wiki/Debugging) contains instructions for debugging node-pty.
  94
  95 ## Security
  96
  97 All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.
  98
  99 ## Thread Safety
 100
 101 Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.
 102
 103 ## Flow Control
 104
 105 Automatic flow control can be enabled by either providing `handleFlowControl = true` in the constructor options or setting it later on:
 106
 107 ```js
 108 const PAUSE = '\x13';   // XOFF
 109 const RESUME = '\x11';  // XON
 110
 111 const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});
 112
 113 // flow control in action
 114 ptyProcess.write(PAUSE);  // pty will block and pause the slave program
 115 ...
 116 ptyProcess.write(RESUME); // pty will enter flow mode and resume the slave program
 117
 118 // temporarily disable/re-enable flow control
 119 ptyProcess.handleFlowControl = false;
 120 ...
 121 ptyProcess.handleFlowControl = true;
 122 ```
 123
 124 By default `PAUSE` and `RESUME` are XON/XOFF control codes (as shown above). To avoid conflicts in environments that use these control codes for different purposes the messages can be customized as `flowControlPause: string` and `flowControlResume: string` in the constructor options. `PAUSE` and `RESUME` are not passed to the underlying pseudoterminal if flow control is enabled.
 125
 126 ## Troubleshooting
 127
 128 ### Powershell gives error 8009001d
 129
 130 > Internal Windows PowerShell error.  Loading managed Windows PowerShell failed with error 8009001d.
 131
 132 This happens when PowerShell is launched with no `SystemRoot` environment variable present.
 133
 134 ### ConnectNamedPipe failed: Windows error 232
 135
 136 This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning `node-pty\build\Release\winpty-agent.exe`
 137
 138 ## pty.js
 139
 140 This project is forked from [chjj/pty.js](https://github.com/chjj/pty.js) with the primary goals being to provide better support for later Node.JS versions and Windows.
 141
 142 ## License
 143
 144 Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).<br>
 145 Copyright (c) 2016, Daniel Imms (MIT License).<br>
 146 Copyright (c) 2018, Microsoft Corporation (MIT License).