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 | ## API
|
15 |
|
16 | The full API for node-pty is contained within the [TypeScript declaration file](https://github.com/microsoft/node-pty/blob/master/typings/node-pty.d.ts), use the branch/tag picker in GitHub (`w`) to navigate to the correct version of the API.
|
17 |
|
18 | ## Example Usage
|
19 |
|
20 | ```js
|
21 | var os = require('os');
|
22 | var pty = require('node-pty');
|
23 |
|
24 | var shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
|
25 |
|
26 | var ptyProcess = pty.spawn(shell, [], {
|
27 | name: 'xterm-color',
|
28 | cols: 80,
|
29 | rows: 30,
|
30 | cwd: process.env.HOME,
|
31 | env: process.env
|
32 | });
|
33 |
|
34 | ptyProcess.on('data', function(data) {
|
35 | process.stdout.write(data);
|
36 | });
|
37 |
|
38 | ptyProcess.write('ls\r');
|
39 | ptyProcess.resize(100, 40);
|
40 | ptyProcess.write('ls\r');
|
41 | ```
|
42 |
|
43 | ## Real-world Uses
|
44 |
|
45 | `node-pty` powers many different terminal emulators, including:
|
46 |
|
47 | - [Microsoft Visual Studio Code](https://code.visualstudio.com)
|
48 | - [Hyper](https://hyper.is/)
|
49 | - [Upterm](https://github.com/railsware/upterm)
|
50 | - [Script Runner](https://github.com/ioquatix/script-runner) for Atom.
|
51 | - [Theia](https://github.com/theia-ide/theia)
|
52 | - [FreeMAN](https://github.com/matthew-matvei/freeman) file manager
|
53 | - [terminus](https://atom.io/packages/terminus) - An Atom plugin for providing terminals inside your Atom workspace.
|
54 | - [x-terminal](https://atom.io/packages/x-terminal) - Also an Atom plugin that provides terminals inside your Atom workspace.
|
55 | - [Termination](https://atom.io/packages/termination) - Also an Atom plugin that provides terminals inside your Atom workspace.
|
56 | - [atom-xterm](https://atom.io/packages/atom-xterm) - Also an Atom plugin that provides terminals inside your Atom workspace.
|
57 | - [electerm](https://github.com/electerm/electerm) Terminal/SSH/SFTP client(Linux, macOS, Windows).
|
58 | - [Extraterm](http://extraterm.org/)
|
59 | - [Wetty](https://github.com/krishnasrinivas/wetty) Browser based Terminal over HTTP and HTTPS
|
60 | - [nomad](https://github.com/lukebarnard1/nomad-term)
|
61 | - [DockerStacks](https://github.com/sfx101/docker-stacks) Local LAMP/LEMP stack using Docker
|
62 | - [TeleType](https://github.com/akshaykmr/TeleType): cli tool that allows you to share your terminal online conveniently. Show off mad cli-fu, help a colleague, teach, or troubleshoot.
|
63 | - [mesos-term](https://github.com/criteo/mesos-term): A web terminal for Apache Mesos. It allows to execute commands within containers.
|
64 | - [Commas](https://github.com/CyanSalt/commas): A hackable terminal and command runner.
|
65 | - [ENiGMA½ BBS Software](https://github.com/NuSkooler/enigma-bbs): A modern BBS software with a nostalgic flair!
|
66 |
|
67 | 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.
|
68 |
|
69 | ## Building
|
70 |
|
71 | ```bash
|
72 | # Install dependencies and build C++
|
73 | npm install
|
74 | # Compile TypeScript -> JavaScript
|
75 | npm run build
|
76 | ```
|
77 |
|
78 | ## Dependencies
|
79 |
|
80 | ### Linux/Ubuntu
|
81 |
|
82 | ```
|
83 | sudo apt install -y make python build-essential
|
84 | ```
|
85 |
|
86 | The following are also needed:
|
87 |
|
88 | - Node.JS 10+
|
89 |
|
90 | ### macOS
|
91 |
|
92 | Xcode is needed to compile the sources, this can be installed from the App Store.
|
93 |
|
94 | ### Windows
|
95 |
|
96 | `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:
|
97 |
|
98 | ```sh
|
99 | npm install --global --production windows-build-tools
|
100 | ```
|
101 |
|
102 | The following are also needed:
|
103 |
|
104 | - [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk) - only the "Desktop C++ Apps" components are needed to be installed
|
105 | - Node.JS 10+
|
106 |
|
107 | ## Debugging
|
108 |
|
109 | [The wiki](https://github.com/Microsoft/node-pty/wiki/Debugging) contains instructions for debugging node-pty.
|
110 |
|
111 | ## Security
|
112 |
|
113 | 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.
|
114 |
|
115 | ## Thread Safety
|
116 |
|
117 | Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.
|
118 |
|
119 | ## Flow Control
|
120 |
|
121 | Automatic flow control can be enabled by either providing `handleFlowControl = true` in the constructor options or setting it later on:
|
122 |
|
123 | ```js
|
124 | const PAUSE = '\x13'; // XOFF
|
125 | const RESUME = '\x11'; // XON
|
126 |
|
127 | const ptyProcess = pty.spawn(shell, [], {handleFlowControl: true});
|
128 |
|
129 | // flow control in action
|
130 | ptyProcess.write(PAUSE); // pty will block and pause the child program
|
131 | ...
|
132 | ptyProcess.write(RESUME); // pty will enter flow mode and resume the child program
|
133 |
|
134 | // temporarily disable/re-enable flow control
|
135 | ptyProcess.handleFlowControl = false;
|
136 | ...
|
137 | ptyProcess.handleFlowControl = true;
|
138 | ```
|
139 |
|
140 | 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.
|
141 |
|
142 | ## Troubleshooting
|
143 |
|
144 | ### Powershell gives error 8009001d
|
145 |
|
146 | > Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.
|
147 |
|
148 | This happens when PowerShell is launched with no `SystemRoot` environment variable present.
|
149 |
|
150 | ### ConnectNamedPipe failed: Windows error 232
|
151 |
|
152 | 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`
|
153 |
|
154 | ## pty.js
|
155 |
|
156 | 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.
|
157 |
|
158 | ## License
|
159 |
|
160 | Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).<br>
|
161 | Copyright (c) 2016, Daniel Imms (MIT License).<br>
|
162 | Copyright (c) 2018, Microsoft Corporation (MIT License).
|