> For the complete documentation index, see [llms.txt](https://fig.gitbook.io/fig/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fig.gitbook.io/fig/apps/advanced/creating-a-pseudo-terminal-session.md).

# 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) => {

})
```

{% hint style="info" %}
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.
{% endhint %}

`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.