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.

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.

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.

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.

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.

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

})

Pseudo-Terminal Session

See Creating a Pseudo-Terminal Session for more information.