# Running Shell Commands

The Fig runtime offers 5 different ways of running shell commands.

1. `fig.run` — will run the specified command directly in the user's terminal.\

2. `fig.insert` — will input the specified command into the user's terminal but requires the user to press `enter` for it to run.\

3. `fig.execute` — runs the command _synchronously_ in a background process at the same path and with the same environment variables as the user's terminal session\
   .
4. `fig.stream` —  runs the command _asynchronously_ in the background in the same working directory and with the same environment variables as the user's terminal session.\

5. `fig.pty` — creates a psuedo-terminal session. See [Creating a Pseudo-Terminal Session](../advanced/creating-a-pseudo-terminal-session).

#### Run Command in User's Terminal

Use `fig.run` when you need to **update the user's interactive terminal session**. For example, if you were building a finder app and wanted the user's terminal to reflect the same state when the user changes directory, you'd use `fig.run`.

To run shell command directly in the user's current terminal session.

```jsx
fig.run('ls')
```

#### Insert Command into User's Terminal

Use `fig.insert` for sensitive or **potentially destructive commands**. For example, if the user indicated they wanted to delete a file, you could call `fig.insert('rm file.txt')`. The user could then press enter to run the command.

Insert a shell command into the user's current terminal session _but don't run it._

```jsx
fig.insert('rm test.txt')
```

#### Run a Shell Command Asynchronously

`fig.stream` is used for asynchronously executing continuous and otherwise long running processes. Running commands like `tail` on log files, handling output from `psql` or `git` deployments should use `fig.stream`.

Run a shell command and receive output as stream. The handler will be called multiple times. The handler will receive a `null` value when the stream has ended. Keep in mind that background process are killed when your app is closed.

```jsx
var output = ""
fig.stream('heroku logs --tail', (out, err) => {
    if (!out) {
    console.log("The process has ended")
    console.log("The full output is: ", output)
  }
  console.log("Handle a single line of output")
  output += out + '\n'
})
```

#### Run a Shell Command Synchronously

`fig.execute` is used for **running commands synchronously** in the background. This should be used for shell commands that run for a discrete (and short) period of time. Anything that doesn't block your terminal session is a good candidate for `fig.execute`.

Run shell commands and receive output in callback. This will block your app's main thread, so make sure to only run commands that execute relatively quickly.

It should _not_ be used for commands that require networking or take a long period of time because your app will become unresponsive until the process terminates.

```jsx
fig.execute('ls', (out, err) => {

})
```

### Pseudo-Terminal Session

See [Creating a Pseudo-Terminal Session](../advanced/creating-a-pseudo-terminal-session) for more information.&#x20;
