Introduction

The Terminal feature introduced in RStudio 1.1 has an API accessible through version 0.7 or newer of the rstudioapi package. That package is the definitive reference for these APIs.

The Terminal APIs can also be accessed without installing rstudioapi by prepending them with .Options$terminal.manager. For example, these calls are equivalent:

The latter does not require installation of the rstudioapi package.

API Summary

Concepts

Terminal Instances

The terminal tab hosts zero or more terminal instances. Each instance is represented by an entry in the terminal drop-down. Here are two terminal sessions:

Terminal Identifiers

A terminal instance is identified in the API via its caption. The default captions of new terminals are “Terminal 1”“,”Terminal 2“, and so on, but can be renamed by the user or specified via the createTerminal API. Captions must be unique within an RStudio session.

Terminal identifiers should be obtained in code via createTerminal, getAllTerminals, or getVisibleTerminal.

Running State

When an RStudio session terminates, all processes started by the terminal instances are killed (including the shell itself, e.g. bash), but the list of terminal identifiers, the most recent 1000 lines of their output buffers, and the current-working-directory are persisted. When RStudio reloads that session, it will repopulate the Terminal drop down.

When a session is reloaded in RStudio, the Terminal drop down entries are placeholders. It is not until the user selects an instance in the drop down that a new shell is started, connection is established, and the buffer is reloaded into the terminal emulator.

isTerminalRunning can be used to determine if a terminal instance is currently running or is in the placeholder state.

When not running, the sendToTerminal call will fail. Use activateTerminal to start the terminal; this is safe to call if the terminal is already running. If you don’t want the terminal instance brought to the front in RStudio, specify show = FALSE.

Busy State

A terminal instance is considered busy if the shell program has one or more sub-processes. The IDE generally warns before terminating a busy terminal instance and shows (Busy) next to the terminal caption. The busy-state can be queried via isTerminalBusy. This could be used to programmatically determine if a long-running command has completed.

Buffer

The terminal keeps approximately 1000 lines of output, visible both in RStudio’s terminal emulator, and available via getTerminalBuffer. To obtain longer results, redirection to a file would be necessary. The API strips out Ansi escape sequences before returning the buffer; if these are needed specify stripAnsi = FALSE.

Alternate-Buffer

If an ncurses-style program is running (such as vim, tmux, and so on) the terminal output is sent to an alternate buffer which is not persisted or returned by getTerminalBuffer. However, text can still be sent to the terminal via sentToTerminal when the alternate buffer is in use.

Examples

Task Example
Count terminals
Create a terminal with default name
Create a terminal with custom name
List the terminal identifiers
Send text to a terminal
Count lines in buffer
Get process-id of shell
Get a line from buffer
Stop the terminal