Creating a Pseudo-Terminal Session

Using fig.pty creates a headless terminal session. Unlike fig.execute or fig.stream, using fig.pty lets you maintain state across multiple commands. It is necessary for creating apps that work over ssh or sftp. It gives you much more fine-grained control over handling terminal output.

fig.pty.init() creates a new pseudo-terminal instance. This is an expensive operation. To ensure the pty has been created wait for at least 200ms. (I know this is ugly! There will be a callback in an upcoming version😅). Apps that don't need to use the pty API, should stick with the normal API.

fig.pty.execute and fig.pty.stream present an identical interface to fig.execute and fig.stream.

fig.pty.execute(command, (out) => {

})

fig.pty.stream(command, (out) => {

})

One limitation is of fig.pty.execute and fig.pty.stream is that they only work when running commands in the shell. For instance, when writing a wrapper around a command like sftp, you'll need to write custom code for coupling commands with their output. Check out the sftp app for an example of how this could work.

fig.write runs a command in the psuedo terminal without attempting to capture the response. This is useful for running commands that alter the state of the terminal session, eg. changing directories or updating enviroment variables.

fig.write('cd ~')

fig.write can also be used for quitting processes, using these constants.

^D maps to Control-D, which sends the EOF signal.

^C maps to Control-C, which sends the ETX signal.

fig.write('man whoami')
fig.write('^C')

fig.pty.exit() terminates the pseudo-terminal process associated with your app. This happens automatically when your app is closed, so only run this is you are planning on creating a new pty.

When should I use fig.pty?

You should create a pseudo-terminal for apps that need to operate over SSH or need more control. Also, although the startup time can be slow, if you need to run commands repeatedly, fig.pty can be more performant than the standard API.