rstudioapi

https://rstudio.github.io/rstudioapi/
Admin
rstudioapi is an R package that makes it easy to conditionally access the RStudio API from CRAN...
Tokens:48,193
Snippets:522
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Find OAuth Integration by Exact GUID

Source: https://rstudio.github.io/rstudioapi/reference/findOAuthIntegration.html

This example shows how to find an OAuth integration using its exact globally unique identifier (GUID).

```R
integration <- findOAuthIntegration(guid = "4c1cfecb-1927-4f19-bc2f-d8ac261364e0")
```

--------------------------------

### Iterate and Display OAuth Integration Details

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthIntegrations.html

Demonstrates how to loop through the list of integrations returned by `getOAuthIntegrations()` and display their names, GUIDs, and authentication status. This example is part of a larger script and is intended for execution within a Posit Workbench session.

```r
if (FALSE) { # \dontrun{
# Get all OAuth integrations
integrations <- getOAuthIntegrations()

# Show all integrations
for (int in integrations) {
  cat(sprintf("%s (%s): %s\n",
              int$name,
              int$guid,
              if (int$authenticated) "authenticated" else "not authenticated"))
}

# Filter to authenticated integrations only
authenticated <- Filter(function(x) x$authenticated, integrations)

# Get credentials for the first authenticated integration
if (length(authenticated) > 0) {
  creds <- getOAuthCredentials(audience = authenticated[[1]]$guid)
}
} # }
```

--------------------------------

### Highlight Git Panel

Source: https://rstudio.github.io/rstudioapi/reference/highlightUi.html

Example of highlighting the Git panel. This is a basic usage example.

```r
rstudioapi::highlightUi("#rstudio_workbench_panel_git")
```

--------------------------------

### Run rstudioapi on Session Startup

Source: https://rstudio.github.io/rstudioapi/articles/r-session.html

Use the 'rstudio.sessionInit' hook to execute rstudioapi methods when RStudio starts. This example prints the RStudio version to the console upon session initialization.

```r
setHook("rstudio.sessionInit", function(newSession) {
  if (newSession)
    message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")
```

--------------------------------

### Check, Install, and Execute Build Tools

Source: https://rstudio.github.io/rstudioapi/reference/build-tools.html

Use these functions to manage build tools. First, check if they are available, then install if necessary, and finally execute code that requires them.

```r
buildToolsCheck()

buildToolsInstall(action)

buildToolsExec(expr)
```

```r
compile_model <- function(...) {

  if (rstudioapi::isAvailable()) {

    if (!rstudioapi::buildToolsCheck())
      rstudioapi::buildToolsInstall("Model compilation")

    rstudioapi::buildToolsExec({
      # code requiring build tools here
    })

  }
}
```

--------------------------------

### Run and Configure RStudio Viewer Examples

Source: https://rstudio.github.io/rstudioapi/reference/viewer.html

These examples demonstrate how to run applications within the RStudio IDE, specify viewer height, utilize the 'viewer' option, and display temporary HTML files.

```r
if (FALSE) { # \dontrun{

# run an application inside the IDE
rstudioapi::viewer("http://localhost:8100")

# run an application and request a height of 500 pixels
rstudioapi::viewer("http://localhost:8100", height = 500)

# use 'viewer' option if set, or `utils::browseURL()` if unset
viewer <- getOption("viewer", default = utils::browseURL)
viewer("http://localhost:8100")

# generate a temporary html file and display it
dir <- tempfile()
dir.create(dir)
htmlFile <- file.path(dir, "index.html")
# (code to write some content to the file)
rstudioapi::viewer(htmlFile)

} # }
```

--------------------------------

### Example: Find OAuth Integration by Exact Name

Source: https://rstudio.github.io/rstudioapi/reference/findOAuthIntegration.html

This example demonstrates how to find an OAuth integration by its exact name using a regular expression with anchors.

```R
integration <- findOAuthIntegration(name = "^my-github-integration$")
```

--------------------------------

### Example of Asking for Password

Source: https://rstudio.github.io/rstudioapi/reference/askForPassword.html

This is a non-runnable example demonstrating the usage of askForPassword. It is typically used within RStudio sessions.

```r
rstudioapi::askForPassword("Please enter your password")
```

--------------------------------

### buildToolsInstall

Source: https://rstudio.github.io/rstudioapi/reference/build-tools.html

Installs build tools if they are not already present. It can be used to prompt the user for installation.

```APIDOC
## buildToolsInstall(action)

### Description
Installs build tools if they are not already present. It can be used to prompt the user for installation.

### Method
`buildToolsInstall(action)`

### Parameters
#### Path Parameters
- **action** (string) - Required - The action (as a string) being taken that will require installation of build tools. Setting it to `NULL` or the empty string will suppress the prompt.
```

--------------------------------

### Install rstudioapi from GitHub

Source: https://rstudio.github.io/rstudioapi/index.html

Install the development version of the rstudioapi package from GitHub using the devtools package.

```R
# install.packages("devtools")
devtools::install_github("rstudio/rstudioapi")
```

--------------------------------

### Example: Find Authenticated Integration by Display Name Pattern

Source: https://rstudio.github.io/rstudioapi/reference/findOAuthIntegration.html

This example demonstrates finding an authenticated OAuth integration that matches a pattern in its display name.

```R
integration <- findOAuthIntegration(display_name = "GitHub.*", authenticated = TRUE)
```

--------------------------------

### Install rstudioapi from CRAN

Source: https://rstudio.github.io/rstudioapi/index.html

Install the released version of the rstudioapi package from CRAN.

```R
install.packages("rstudioapi")
```

--------------------------------

### Example: Find OAuth Integration by Name Pattern

Source: https://rstudio.github.io/rstudioapi/reference/findOAuthIntegration.html

This example shows how to find any OAuth integration that has 'github' in its name using a regular expression.

```R
integration <- findOAuthIntegration(name = "github")
```

--------------------------------

### Get RStudio Preference Example

Source: https://rstudio.github.io/rstudioapi/reference/readRStudioPreference.html

Use this snippet to retrieve RStudio IDE internal preferences, such as indentation settings. Provide the preference name and a default value.

```r
if (FALSE) { # \dontrun{
# Get indentation settings
spaces <- rstudioapi::readRStudioPreference("num_spaces_for_tab", FALSE)
message("Using ", spaces, " per tab.")
} # }
```

--------------------------------

### Create and Manage Interactive Terminal

Source: https://rstudio.github.io/rstudioapi/articles/terminal.html

Create an interactive terminal session. This example shows how to check if a terminal is running and reactivate it if necessary, then send a command.

```r
# start an interactive terminal using the shell selected in 
# RStudio global options
myTerm <- rstudioapi::terminalCreate()

# ....
# sometime later
# ....
if (!rstudioapi::terminalRunning(myTerm)) {
  # start the terminal shell back up, but don't bring to front
  rstudioapi::terminalActivate(myTerm, show = FALSE)
  
  # wait for it to start
  while (!rstudioapi::terminalRunning(myTerm)) {
    Sys.sleep(0.1)
  }
 
  # send a new command 
  rstudioapi::terminalSend(myTerm, "echo Hello\n") 
}
```

--------------------------------

### Check Workbench Launcher Availability

Source: https://rstudio.github.io/rstudioapi/reference/launcherAvailable.html

Use this function to determine if the Workbench launcher is configured and ready to support Workbench jobs. No setup or imports are required.

```r
launcherAvailable()
```

--------------------------------

### Get Workbench Launcher Information

Source: https://rstudio.github.io/rstudioapi/reference/launcherGetInfo.html

Call this function to retrieve details about the Workbench launcher and its configured clusters. No arguments are required.

```r
launcherGetInfo()
```

--------------------------------

### Wait for Terminal to Become Available

Source: https://rstudio.github.io/rstudioapi/reference/terminalBusy.html

This example demonstrates how to create a hidden terminal, send a command that takes time to execute (sleep 5), and then use a while loop with terminalBusy to wait until the terminal is no longer busy before proceeding.

```r
if (FALSE) { # \dontrun{
# create a hidden terminal and run a lengthy command
termId <- rstudioapi::terminalCreate(show = FALSE)
rstudioapi::terminalSend(termId, "sleep 5\n")

# wait until a busy terminal is finished
while (rstudioapi::terminalBusy(termId)) {
  Sys.sleep(0.1)
}
print("Terminal available")
} # }
```

--------------------------------

### systemUsername

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Get the current system username.

```APIDOC
## systemUsername

### Description
Get System Username.

### Method
APICALL

### Endpoint
systemUsername()
```

--------------------------------

### Retrieve All OAuth Integrations

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthIntegrations.html

Call this function to get a list of all configured OAuth integrations. It returns metadata such as authentication status, scopes, and client IDs. Requires Posit Workbench version 2026.01.0 or later.

```r
getOAuthIntegrations()
```

--------------------------------

### Call bugReport() to File a Bug

Source: https://rstudio.github.io/rstudioapi/reference/bugReport.html

Call this function to open a pre-populated bug report template. No setup or imports are required.

```r
bugReport()
```

--------------------------------

### selectionGet, selectionSet

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Get and set user selections in the RStudio IDE.

```APIDOC
## selectionGet, selectionSet

### Description
Manipulate User Selections in the RStudio IDE.

### Method
APICALL

### Endpoint
selectionGet()
selectionSet()
```

--------------------------------

### getMode()

Source: https://rstudio.github.io/rstudioapi/reference/getMode.html

Use `getMode()` if you need to differentiate between server and desktop installations of RStudio.

```APIDOC
## getMode()

### Description
Reports whether RStudio Desktop or RStudio Server is in use.

### Method
`getMode()`

### Parameters
This function does not take any parameters.

### Value
Returns "desktop" for RStudio Desktop installations, and "server" for RStudio Server / RStudio Workbench installations.
```

--------------------------------

### buildToolsCheck

Source: https://rstudio.github.io/rstudioapi/reference/build-tools.html

Checks if the necessary build tools are installed and available in the R environment.

```APIDOC
## buildToolsCheck()

### Description
Checks if the necessary build tools are installed and available in the R environment.

### Method
`buildToolsCheck()`

### Parameters
None
```

--------------------------------

### Get OAuth Integrations

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthIntegrations.html

Retrieves a list of all OAuth integrations configured in Posit Workbench. This returns metadata about each integration including its authentication status, scopes, and configuration details. Returns an empty list if no integrations are configured.

```APIDOC
## getOAuthIntegrations()

### Description
Retrieve a list of all OAuth integrations configured in Posit Workbench. This returns metadata about each integration including its authentication status, scopes, and configuration details.

### Returns
A list of OAuth integrations, where each element contains:
- **type** (string): The integration type (e.g., "custom").
- **name** (string): The integration name.
- **display_name** (string): The display name (may be NULL).
- **client_id** (string): The OAuth client ID.
- **auth_url** (string): The authorization URL.
- **token_url** (string): The token URL.
- **scopes** (character vector): A character vector of OAuth scopes.
- **issuer** (string): The OAuth issuer URL.
- **authenticated** (boolean): Boolean indicating if currently authenticated.
- **guid** (string): The globally unique identifier for this integration (useful for `getOAuthCredentials()`).

Returns an empty list if no integrations are configured.

### Note
This function requires Posit Workbench version 2026.01.0 or later. It works in any IDE running within a Posit Workbench session (not just RStudio).

### Example
```R
if (FALSE) { # \dontrun{
# Get all OAuth integrations
integrations <- getOAuthIntegrations()

# Show all integrations
for (int in integrations) {
  cat(sprintf("%s (%s): %s\n",
              int$name,
              int$guid,
              if (int$authenticated) "authenticated" else "not authenticated"))
}

# Filter to authenticated integrations only
authenticated <- Filter(function(x) x$authenticated, integrations)

# Get credentials for the first authenticated integration
if (length(authenticated) > 0) {
  creds <- getOAuthCredentials(audience = authenticated[[1]]$guid)
}
} # }
```
```

--------------------------------

### Get RStudio Dictionaries Path

Source: https://rstudio.github.io/rstudioapi/reference/dictionaries.html

Retrieves the path to dictionaries installed with RStudio. Introduced in RStudio 1.2.1202.

```r
dictionariesPath()
```

--------------------------------

### Get List of Editor Themes

Source: https://rstudio.github.io/rstudioapi/reference/getThemes.html

Retrieves a list of the names of all the editor themes installed for RStudio. This function was introduced in RStudio 1.2.879.

```APIDOC
## getThemes

### Description
Retrieves a list of the names of all the editor themes installed for RStudio.

### Details
The `getThemes` function was introduced in RStudio 1.2.879.

### Usage
```R
getThemes()
```
```

--------------------------------

### Get a Specific OAuth Integration

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthIntegration.html

Retrieves metadata for a specific OAuth integration using its GUID. Returns NULL if no integration is found.

```APIDOC
## getOAuthIntegration(guid)

### Description
Retrieve metadata for a specific OAuth integration by its globally unique identifier.

### Arguments
#### Path Parameters
- **guid** (string) - Required - The globally unique identifier (GUID) of the OAuth integration to retrieve.

### Returns
A list containing the integration metadata, or NULL if no integration with the specified GUID is found.

### Value
- **type** (string) - The integration type (e.g., "custom").
- **name** (string) - The integration name.
- **display_name** (string) - The display name (may be NULL).
- **client_id** (string) - The OAuth client ID.
- **auth_url** (string) - The authorization URL.
- **token_url** (string) - The token URL.
- **scopes** (character vector) - A character vector of OAuth scopes.
- **issuer** (string) - The OAuth issuer URL.
- **authenticated** (boolean) - Boolean indicating if currently authenticated.
- **guid** (string) - The globally unique identifier for this integration.

### Example
```R
if (FALSE) { # \dontrun{
# Get a specific integration by GUID
integration <- getOAuthIntegration("4c1cfecb-1927-4f19-bc2f-d8ac261364e0")

if (!is.null(integration)) {
  cat("Found integration:", integration$name, "\n")
  cat("Authenticated:", integration$authenticated, "\n")

  # Get credentials if authenticated
  if (integration$authenticated) {
    creds <- getOAuthCredentials(audience = integration$guid)
  }
}
} # }
```
```

--------------------------------

### Create New Document in RStudio

Source: https://rstudio.github.io/rstudioapi/reference/rstudio-documents.html

Create a new document with specified initial text, type, and starting position. The `execute` argument controls whether code is run upon creation. Introduced in RStudio 1.2.640.

```r
documentNew(
  text,
  type = "r",
  position = document_position(0, 0),
  execute = FALSE
)
```

--------------------------------

### Initialize Project

Source: https://rstudio.github.io/rstudioapi/reference/projects.html

Initializes and opens a new RStudio project in the specified directory.

```APIDOC
## initializeProject

### Description
Initializes and opens a new RStudio project in the specified directory.

### Arguments
* `path` (character) - The path to a directory in which a new project should be initialized and opened. Defaults to the current working directory.

### Note
Added in version 1.1.287 of RStudio.
```

--------------------------------

### Get Specific OAuth Integration by GUID

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthIntegration.html

Retrieve metadata for a specific OAuth integration by its globally unique identifier. This function requires Posit Workbench version 2026.01.0 or later and works in any IDE within a Posit Workbench session.

```r
if (FALSE) { # \dontrun{
# Get a specific integration by GUID
integration <- getOAuthIntegration("4c1cfecb-1927-4f19-bc2f-d8ac261364e0")

if (!is.null(integration)) {
  cat("Found integration:", integration$name, "\n")
  cat("Authenticated:", integration$authenticated, "\n")

  # Get credentials if authenticated
  if (integration$authenticated) {
    creds <- getOAuthCredentials(audience = integration$guid)
  }
}
} # }
```

--------------------------------

### Retrieve OAuth Credentials

Source: https://rstudio.github.io/rstudioapi/reference/getOAuthCredentials.html

Use this function to obtain OAuth credentials for an integration configured in Posit Workbench. Ensure you have Posit Workbench version 2026.01.0 or later installed. The function returns a list containing the access token, its expiry time, and the audience (integration GUID).

```R
if (FALSE) { # \dontrun{
# Retrieve OAuth credentials for an integration
creds <- getOAuthCredentials("4c1cfecb-1927-4f19-bc2f-d8ac261364e0")
if (!is.null(creds)) {
  cat("Access token:", creds$access_token, "\n")
  cat("Expires at:", format(creds$expiry), "\n")
}
} # } 
```

--------------------------------

### Opening and Initializing RStudio Projects

Source: https://rstudio.github.io/rstudioapi/articles/projects.html

Demonstrates how to use the `rstudioapi::openProject` and `rstudioapi::initializeProject` functions to manage RStudio projects.

```APIDOC
## Interacting with RStudio Projects

This section covers the direct user-invokable functions for managing RStudio projects.

### `rstudioapi::openProject`

#### Description
Opens an RStudio project. If no argument is provided, it re-opens the current project.

#### Usage
```r
# Open a project in a specific directory
rstudioapi::openProject("~/projects/t-sne-gene-expression-2017")

# Re-open the current project
rstudioapi::openProject()
```

### `rstudioapi::initializeProject`

#### Description
Initializes an RStudio project in a specified directory without opening it.

#### Usage
```r
# Initialize a project in a directory
rstudioapi::initializeProject("~/scratch/testbed")
```
```

--------------------------------

### Get RStudio Package Dependencies

Source: https://rstudio.github.io/rstudioapi/reference/getRStudioPackageDependencies.html

Gets a list of all the R packages that RStudio depends on in some way.

```APIDOC
## getRStudioPackageDependencies()

### Description
Gets a list of all the R packages that RStudio depends on in some way.

### Value
A data frame containing a row per R package.

### Details
The data frame of package dependencies contains the following columns:

*   **name** (string) - The name of the R package.
*   **version** (string) - The required minimum version of the R package.
*   **location** (string) - Where RStudio expects the package to be, `cran` for a CRAN-like repository or `embedded` for development packages embedded in RStudio itself.
*   **source** (string) - Whether the package should be installed from source.

### Note
The `getRStudioPackageDependencies` function was introduced in RStudio 1.3.525.
```

--------------------------------

### Select a File or Directory

Source: https://rstudio.github.io/rstudioapi/reference/file-dialogs.html

Use `selectFile` to prompt the user for a file path and `selectDirectory` to prompt for a directory path. Both functions utilize system dialogs. `selectFile` can filter by extension and specify if the file must exist.

```r
selectFile(
  caption = "Select File",
  label = "Select",
  path = getActiveProject(),
  filter = "All Files (*)",
  existing = TRUE
)

selectDirectory(
  caption = "Select Directory",
  label = "Select",
  path = getActiveProject()
)
```

--------------------------------

### Get Visible Terminal

Source: https://rstudio.github.io/rstudioapi/reference/terminalVisible.html

Call this function to get the identifier of the currently visible terminal. This function was added in RStudio version 1.1.350.

```r
terminalVisible()
```

--------------------------------

### File Selection Dialogs

Source: https://rstudio.github.io/rstudioapi/articles/dialogs.html

Use `selectFile()` to prompt the user to select an existing file or specify a path for a new file.

```APIDOC
## selectFile

### Description
Prompts the user to select a file path. Can be used to select an existing file or specify a path for a new file.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Function Signature
`selectFile(caption = "Select File", label = "Open", filter = NULL, existing = TRUE)`

### Parameters
- **caption** (string) - Optional - The text displayed in the dialog's title bar.
- **label** (string) - Optional - The text displayed on the dialog's confirmation button (e.g., "Open", "Save").
- **filter** (string) - Optional - A filter string to limit selectable file types (e.g., "CSV Files (*.csv)").
- **existing** (boolean) - Optional - If TRUE, only existing files can be selected. If FALSE, any path can be specified.

### Request Example
```r
# Request an existing CSV file
path <- rstudioapi::selectFile(caption = "Select CSV File",
                               filter = "CSV Files (*.csv)",
                               existing = TRUE)

# Request a path for a new file
target <- rstudioapi::selectFile(caption = "Save File",
                                 label = "Save",
                                 existing = FALSE)
```

### Response
Returns the selected file path as a string, or NULL if the dialog was cancelled.
```

--------------------------------

### launcherContainer

Source: https://rstudio.github.io/rstudioapi/reference/launcherContainer.html

Creates a launcher container configuration with the specified image and optional user/group IDs.

```APIDOC
## launcherContainer

### Description

Define a launcher container, suitable for use with the `container` argument to `launcherSubmitJob()`.

### Arguments

- **image** (string) - Required - The container image to use.
- **runAsUserId** (numeric) - Optional - The user id to run as within the container. Defaults to the container-specified user.
- **runAsGroupId** (numeric) - Optional - The group id to run as within the container. Defaults to the container-specified group.
```

--------------------------------

### launcherGetInfo

Source: https://rstudio.github.io/rstudioapi/reference/launcherGetInfo.html

Retrieves information about the Workbench launcher and its configured clusters.

```APIDOC
## launcherGetInfo

### Description
Retrieve information about the Workbench launcher, as well as the different clusters that the launcher has been configured to use.

### Method
This function does not have an explicit HTTP method or endpoint as it is an R function call.

### Endpoint
N/A

### Parameters
This function does not take any parameters.

### Request Example
```R
launcherGetInfo()
```

### Response
#### Success Response
Returns information about the Workbench launcher and its configured clusters. The exact structure of the response is not detailed in the source.

#### Response Example
```json
{
  "example": "Response structure not specified in source"
}
```
```

--------------------------------

### Get Delegated Azure Token

Source: https://rstudio.github.io/rstudioapi/reference/getDelegatedAzureToken.html

Call this function to get an OAuth2 token for a specified Azure resource. Ensure delegated permissions are configured in Azure.

```r
getDelegatedAzureToken(resource)
```

```r
getDelegatedAzureToken("https://storage.azure.com")
```

--------------------------------

### createProjectTemplate

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Create a new project using a specified template.

```APIDOC
## createProjectTemplate

### Description
Create a Project Template.

### Method
APICALL

### Endpoint
createProjectTemplate()
```

--------------------------------

### Get RStudio Package Dependencies

Source: https://rstudio.github.io/rstudioapi/reference/getRStudioPackageDependencies.html

Call this function to get a data frame of R packages RStudio depends on. The function was introduced in RStudio 1.3.525.

```r
getRStudioPackageDependencies()
```

--------------------------------

### Get Active Project Path

Source: https://rstudio.github.io/rstudioapi/reference/getActiveProject.html

Call this function to get the path of the active RStudio project. Returns NULL if no project is open. The path is UTF-8 encoded if it contains non-ASCII characters.

```r
getActiveProject()
```

--------------------------------

### selectDirectory

Source: https://rstudio.github.io/rstudioapi/reference/file-dialogs.html

Prompts the user to select a directory using the system's file dialog. It allows customization of the dialog's caption, button label, and initial path.

```APIDOC
## selectDirectory

### Description
Prompts the user for the path to a folder, using system file dialogs with RStudio Desktop, and RStudio's own dialogs with RStudio Server.

### Arguments

*   **caption** (string) - Optional - The window title. Defaults to "Select Directory".
*   **label** (string) - Optional - The label to use for the 'Accept' / 'OK' button. Defaults to "Select".
*   **path** (string) - Optional - The initial working directory, from which the file dialog should begin browsing. Defaults to the current RStudio project directory.

### Details
When the selected file resolves within the user's home directory, RStudio will return an aliased path – that is, prefixed with `~/`.

### Note
The `selectDirectory` function was added in version 1.1.287 of RStudio.
```

--------------------------------

### previewSql

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Preview a SQL statement.

```APIDOC
## previewSql

### Description
Preview SQL statement.

### Method
APICALL

### Endpoint
previewSql()
```

--------------------------------

### getRStudioPackageDependencies

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Get the package dependencies for RStudio.

```APIDOC
## getRStudioPackageDependencies

### Description
Get RStudio Package Dependencies.

### Method
APICALL

### Endpoint
getRStudioPackageDependencies()
```

--------------------------------

### Check Workbench Launcher Availability

Source: https://rstudio.github.io/rstudioapi/reference/launcherAvailable.html

Use the `launcherAvailable()` function to determine if the Workbench launcher is ready to support job creation through the RStudio IDE.

```APIDOC
## launcherAvailable()

### Description
Check if the Workbench launcher is available and configured to support Workbench jobs; that is, jobs normally launched by the user through the RStudio IDE's user interface.

### Method
launcherAvailable()

### Parameters
This function does not take any parameters.

### Returns
- A logical value indicating whether the launcher is available.
```

--------------------------------

### userIdentity

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Get the current user's identity in RStudio.

```APIDOC
## userIdentity

### Description
Get User Identity.

### Method
APICALL

### Endpoint
userIdentity()
```

--------------------------------

### launcherGetJob

Source: https://rstudio.github.io/rstudioapi/reference/launcherGetJob.html

Retrieves information about a specific Workbench job.

```APIDOC
## launcherGetJob

### Description
Retrieve information on a Workbench job with id `jobId`.

### Arguments

*   **jobId** (string) - The id of a Workbench job.

### See also
Other job-launcher functionality: `launcherAvailable()`, `launcherConfig()`, `launcherContainer()`, `launcherControlJob()`, `launcherGetInfo()`, `launcherGetJobs()`, `launcherHostMount()`, `launcherNfsMount()`, `launcherPlacementConstraint()`, `launcherResourceLimit()`, `launcherSubmitJob()`, `launcherSubmitR()`
```

--------------------------------

### setPersistentValue, getPersistentValue

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Set and get persistent key-value pairs.

```APIDOC
## setPersistentValue, getPersistentValue

### Description
Persistent keys and values.

### Method
APICALL

### Endpoint
setPersistentValue()
getPersistentValue()
```

--------------------------------

### dictionariesPath

Source: https://rstudio.github.io/rstudioapi/reference/dictionaries.html

Retrieves the path to the hunspell dictionaries installed and distributed with RStudio.

```APIDOC
## dictionariesPath()

### Description
Provides the path to the dictionaries that are installed and distributed with RStudio.

### Details
This function returns a file path string.

### Note
Introduced with RStudio version 1.2.1202.
```

--------------------------------

### Get User Identity

Source: https://rstudio.github.io/rstudioapi/reference/userIdentity.html

Retrieves the displayed name of the current user.

```APIDOC
## userIdentity

### Description
Returns the identity (displayed name) of the current user.

### Usage
```R
userIdentity()
```
```

--------------------------------

### Launcher Functions

Source: https://rstudio.github.io/rstudioapi/reference

Functions for interacting with the launcher pane in Workbench, including checking availability, configuring, controlling jobs, and submitting jobs.

```APIDOC
## Launcher Functions

### Description
Functions for interacting with the launcher pane in Workbench.

### Functions
- `launcherAvailable()`: Check if Workbench Launcher is Available
- `launcherConfig()`: Define a Workbench Launcher Configuration
- `launcherContainer()`: Define a Workbench Launcher Container
- `launcherControlJob()`: Interact with (Control) a Workbench Job
- `launcherGetInfo()`: Retrieve Workbench Launcher Information
- `launcherGetJob()`: Retrieve Workbench Job Information
- `launcherGetJobs()`: Retrieve Workbench Job Information
- `launcherHostMount()`: Define a Workbench Launcher Host Mount
- `launcherNfsMount()`: Define a Workbench Launcher NFS Mount
- `launcherPlacementConstraint()`: Define a Workbench Launcher Placement Constraint
- `launcherResourceLimit()`: Define a Workbench Launcher Resource Limit
- `launcherSubmitJob()`: Submit a Workbench Job
- `launcherSubmitR()`: Execute an R Script as a Workbench Job
```

--------------------------------

### Highlight Multiple UI Elements Sequentially

Source: https://rstudio.github.io/rstudioapi/reference/highlightUi.html

Highlight multiple UI elements, such as a menu button and a subsequent menu item, by providing a list of queries with parent references. The parent is specified by its index in the list (0-based).

```r
rstudioapi::highlightUi( list(
list(query = "#rstudio_mb_import_dataset", parent = 0L), list(query =
"#rstudio_label_from_text_readr_command", parent = 1L) )
)
```

--------------------------------

### Launcher Functions

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Functions for interacting with the launcher pane in Workbench, including configuration, job submission, and status retrieval.

```APIDOC
## Launcher Functions

### Description
Provides functions to interact with the launcher pane in Workbench.

### Functions
- `launcherAvailable()`: Check if Workbench Launcher is Available
- `launcherConfig()`: Define a Workbench Launcher Configuration
- `launcherContainer()`: Define a Workbench Launcher Container
- `launcherControlJob()`: Interact with (Control) a Workbench Job
- `launcherGetInfo()`: Retrieve Workbench Launcher Information
- `launcherGetJob()`: Retrieve Workbench Job Information
- `launcherGetJobs()`: Retrieve Workbench Job Information
- `launcherHostMount()`: Define a Workbench Launcher Host Mount
- `launcherNfsMount()`: Define a Workbench Launcher NFS Mount
- `launcherPlacementConstraint()`: Define a Workbench Launcher Placement Constraint
- `launcherResourceLimit()`: Define a Workbench Launcher Resource Limit
- `launcherSubmitJob()`: Submit a Workbench Job
- `launcherSubmitR()`: Execute an R Script as a Workbench Job
```

--------------------------------

### filesPaneNavigate

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Navigate to a specific directory in the Files pane.

```APIDOC
## filesPaneNavigate

### Description
Navigate to a Directory in the Files Pane.

### Method
APICALL

### Endpoint
filesPaneNavigate()
```

--------------------------------

### launcherConfig

Source: https://rstudio.github.io/rstudioapi/reference/launcherConfig.html

Defines a single configuration parameter for a Workbench job launcher.

```APIDOC
## launcherConfig

### Description

Define a Workbench launcher configuration, suitable for use with the `config` argument to `launcherSubmitJob()`.

### Function Signature

```R
launcherConfig(name, value = NULL)
```

### Arguments

*   **name** (string) - Required - The name of the launcher configuration.
*   **value** (integer, float, or string) - Optional - The configuration value. Must either be an integer, float, or string.
```

--------------------------------

### Create a Document Range

Source: https://rstudio.github.io/rstudioapi/reference/document_range.html

Constructs a document_range object from start and end positions.

```APIDOC
## document_range

### Description
Creates a document_range object.

### Arguments
- **start** (document_position) - Required - The starting position of the range.
- **end** (document_position) - Optional - The ending position of the range. If NULL, the range may be considered open-ended or invalid depending on context.

### Value
A list with class `document_range` containing `start` and `end` fields.
```

--------------------------------

### Get All Terminal Ids

Source: https://rstudio.github.io/rstudioapi/reference/terminalList.html

Returns a character vector containing all the current terminal identifiers.

```APIDOC
## terminalList()

### Description
Returns a character vector containing all the current terminal identifiers.

### Method
`terminalList()`

### Parameters
This function does not take any parameters.

### Value
The terminal identifiers as a character vector.

### Note
The `terminalList` function was added in version 1.1.350 of RStudio.
```

--------------------------------

### previewRd

Source: https://rstudio.github.io/rstudioapi/reference/previewRd.html

Preview an Rd topic in the Help pane.

```APIDOC
## previewRd

### Description
Preview an Rd topic in the Help pane.

### Arguments
* `rdFile` (string) - The path to an `.Rd` file.

### Note
The `previewRd` function was added in version 0.98.191 of RStudio.

### Example
```r
if (FALSE) { # \dontrun{
  rstudioapi::previewRd("~/MyPackage/man/foo.Rd")
} # }
```
```

--------------------------------

### previewRd

Source: https://rstudio.github.io/rstudioapi/reference/index.html

Preview an Rd topic in the Help pane.

```APIDOC
## previewRd

### Description
Preview an Rd topic in the Help pane.

### Method
APICALL

### Endpoint
previewRd()
```

--------------------------------

### Get System Username

Source: https://rstudio.github.io/rstudioapi/reference/systemUsername.html

Call this function to retrieve the system username of the current user. No arguments are required.

```r
systemUsername()
```

--------------------------------

### Get User Dictionaries Path

Source: https://rstudio.github.io/rstudioapi/reference/dictionaries.html

Retrieves the path for custom user hunspell dictionaries. Introduced in RStudio 1.2.1202.

```r
userDictionariesPath()
```

--------------------------------

### launcherSubmitJob

Source: https://rstudio.github.io/rstudioapi/reference/launcherSubmitJob.html

Submits a job to a Posit Workbench cluster. This function allows for detailed configuration of the job, including name, cluster, command, environment variables, resource limits, and more.

```APIDOC
## launcherSubmitJob

### Description
Submit a Workbench job. See https://docs.posit.co/job-launcher/latest/index.html for more information.

### Arguments

* **name** (string) - Required - A descriptive name to assign to the job.
* **cluster** (string) - Optional - The name of the cluster this job should be submitted to. Defaults to "Local".
* **tags** (list) - Optional - A set of user-defined tags, used for searching and querying jobs.
* **command** (string) - Optional - The command to run within the job. This is executed via the system shell. Only one of command or exe should be specified.
* **exe** (string) - Optional - The (fully pathed) executable to run within the job. Only one of `command` or `exe` should be specified.
* **args** (array) - Optional - An array of arguments to pass to the command / executable.
* **environment** (list) - Optional - A list of environment variables to be set for processes launched with this job.
* **stdin** (string) - Optional - Data to be written to stdin when the job process is launched.
* **stdoutFile** (string) - Optional - The file used for the job's generated standard output. Not all launcher plugins support this parameter.
* **stderrFile** (string) - Optional - The file used for the job's generated standard error. Not all launcher plugins support this parameter.
* **workingDirectory** (string) - Optional - The working directory to be used by the command / executable associated with this job.
* **host** (string) - Optional - The host that the job is running on, or the desired host during job submission.
* **container** (string) - Optional - The container to be used for launched jobs.
* **exposedPorts** (list) - Optional - The ports that are exposed by services running on a container. Only applicable to systems that support containers.
* **mounts** (list) - Optional - A list of mount points. See `launcherHostMount()` and `launcherNfsMount()` for more information.
* **placementConstraints** (list) - Optional - A list of placement constraints. See `launcherPlacementConstraint()` for more information.
* **resourceLimits** (list) - Optional - A list of resource limits. See `launcherResourceLimit()` for more information.
* **resourceProfile** (string) - Optional - A resource profile name to be used for the job. The resource profile must be defined in the cluster configuration.
* **queues** (list) - Optional - A list of available submission queues for the cluster. Only applicable to batch systems like LSF.
* **config** (list) - Optional - A list of cluster-specific configuration options. See `launcherConfig()` for more information.
* **user** (string) - Optional - The user-name of the job owner. Defaults to Sys.getenv("USER").
* **applyConfigSettings** (boolean) - Optional - Apply server-configured mounts, exposedPorts, and environment, in addition to any specified in this call. Defaults to TRUE.

### See also
Other job-launcher functionality: `launcherAvailable()`, `launcherConfig()`, `launcherContainer()`, `launcherControlJob()`, `launcherGetInfo()`, `launcherGetJob()`, `launcherGetJobs()`, `launcherHostMount()`, `launcherNfsMount()`, `launcherPlacementConstraint()`, `launcherResourceLimit()`, `launcherSubmitR()`
```

--------------------------------

### Get Current User Identity

Source: https://rstudio.github.io/rstudioapi/reference/userIdentity.html

Call this function to retrieve the displayed name of the currently logged-in user. No arguments are required.

```r
userIdentity()
```

--------------------------------

### launcherHostMount

Source: https://rstudio.github.io/rstudioapi/reference/launcherHostMount.html

Defines a host mount for the launcher. This function is used to mount a path from the host into the generated container, typically as part of the `mounts` argument in `launcherSubmitJob()`.

```APIDOC
## launcherHostMount(path, mountPath, readOnly = TRUE)

### Description

Define a launcher host mount, suitable for use with the `mounts` argument to `launcherSubmitJob()`. This can be used to mount a path from the host into the generated container.

### Arguments

* **path** (string) - Required - The host path to be mounted.
* **mountPath** (string) - Required - The destination path for the mount in the container.
* **readOnly** (boolean) - Optional - Boolean; should the path be mounted read-only? Defaults to TRUE.
```

--------------------------------

### Get Visible Terminal

Source: https://rstudio.github.io/rstudioapi/reference/terminalVisible.html

Returns the identifier of the terminal selected in the RStudio client, if any. This function was introduced in RStudio version 1.1.350.

```APIDOC
## terminalVisible

### Description
Get Visible Terminal

### Details
Terminal identifier selected in the client, if any.

### Value
Terminal identifier selected in the client, if any.

### Note
The `terminalVisible` function was added in version 1.1.350 of RStudio.
```

--------------------------------

### documentNew

Source: https://rstudio.github.io/rstudioapi/reference/rstudio-documents.html

Creates a new RStudio document with specified initial content and type.

```APIDOC
## documentNew

### Description
Creates a new RStudio document with specified initial content and type.

### Arguments
* `text` (character vector, required): The initial content for the new document.
* `type` (character, optional): The type of document to create. One of "r" (default), "rmarkdown", or "sql".
* `position` (document_position, optional): The initial cursor position. Defaults to (0, 0).
* `execute` (logical, optional): Whether to execute the code after the document is created. Defaults to FALSE.
```

--------------------------------

### Highlight Element with Click Callback

Source: https://rstudio.github.io/rstudioapi/reference/highlightUi.html

Highlight a UI element and optionally provide a callback function that executes when the element is clicked. The callback is specified as a string representing an R command.

```r
rstudioapi::highlightUi(
  list(
    list(
      query="#rstudio_workbench_panel_git", 
      callback="rstudioapi::highlightUi('')"
    )
  )
)
```

--------------------------------

### selectFile

Source: https://rstudio.github.io/rstudioapi/reference/file-dialogs.html

Prompts the user to select a file using the system's file dialog. It allows customization of the dialog's caption, button label, initial path, file filter, and whether to select existing files or allow new file paths.

```APIDOC
## selectFile

### Description
Prompts the user for the path to a file, using system file dialogs with RStudio Desktop, and RStudio's own dialogs with RStudio Server.

### Arguments

*   **caption** (string) - Optional - The window title. Defaults to "Select File".
*   **label** (string) - Optional - The label to use for the 'Accept' / 'OK' button. Defaults to "Select".
*   **path** (string) - Optional - The initial working directory, from which the file dialog should begin browsing. Defaults to the current RStudio project directory.
*   **filter** (string) - Optional - A glob filter, to be used when attempting to open a file with a particular extension. For example, to scope the dialog to R files, one could use `R Files (*.R)` here. Defaults to "All Files (*)".
*   **existing** (boolean) - Optional - Should the file dialog limit itself to existing files on the filesystem, or allow the user to select the path to a new file? Defaults to TRUE.

### Details
When the selected file resolves within the user's home directory, RStudio will return an aliased path – that is, prefixed with `~/`.

### Note
The `selectFile` function was added in version 1.1.287 of RStudio.
```

--------------------------------

### Insert Last Modified Comment

Source: https://rstudio.github.io/rstudioapi/articles/document-manipulation.html

Inserts a 'last modified' comment at the beginning of the active document. Ensure the rstudioapi package is installed and loaded.

```r
# construct the text to be inserted
fmt <- "# This document was last modified on %s.\n"
text <- sprintf(fmt, Sys.Date())

# specify a range where this text should be inserted; here,
# we use the first line; that is, the 'range' between the start
# of the first row, and the start of the second row
range <- rstudioapi::document_range(c(1, 0), c(2, 0))
rstudioapi::insertText(range, text)
```

--------------------------------

### Get Terminal Buffer Contents

Source: https://rstudio.github.io/rstudioapi/reference/terminalBuffer.html

Retrieves the contents of a specified terminal buffer. You can choose whether to strip ANSI escape sequences from the output.

```APIDOC
## terminalBuffer()

### Description
Returns contents of a terminal buffer.

### Arguments

*   **id** (character or numeric) - Required - The terminal id. The `id` is obtained from `terminalList()`, `terminalVisible()`, `terminalCreate()`, or `terminalExecute()`.
*   **stripAnsi** (logical) - Optional - If FALSE, don't strip out Ansi escape sequences before returning terminal buffer. Defaults to TRUE.

### Value
The terminal contents, one line per row.

### Note
The `terminalBuffer` function was added in version 1.1.350 of RStudio.
```

--------------------------------

### versionInfo()

Source: https://rstudio.github.io/rstudioapi/reference/versionInfo.html

Retrieves information about the current RStudio session.

```APIDOC
## versionInfo()

### Description
Query information about the currently running instance of RStudio.

### Method
```R
versionInfo()
```

### Value
An R list with the following elements:
- `version` (string): The version of RStudio.
- `mode` (string): `"desktop"` for RStudio Desktop, or `"server"` for RStudio Server.
- `citation` (string): Information on how RStudio can be cited in academic publications.

### Note
The `versionInfo` function was added in version 0.97.124 of RStudio.

### Examples
```R
if (FALSE) { # \dontrun{
info <- rstudioapi::versionInfo()

# check what version of RStudio is in use
if (info$version >= "1.4") {
  # code specific to versions of RStudio 1.4 and newer
}

# check whether RStudio Desktop or RStudio Server is being used
if (info$mode == "desktop") {
  # code specific to RStudio Desktop
}

# Get the citation
info$citation

} # } 
```
```

--------------------------------

### Get Identity Token

Source: https://rstudio.github.io/rstudioapi/reference/getIdentityToken.html

Retrieves the user's OpenID Connect identity token and its expiry time. Throws an error if the token cannot be retrieved.

```APIDOC
## getIdentityToken()

### Description
Retrieve the user's OpenID Connect identity token for the current Posit Workbench session, if any. This token can be used to authenticate with services that trust Workbench's identity provider.

### Function Signature
```R
getIdentityToken()
```

### Value
A list containing:

- **token** (string): The identity token string.
- **expiry** (POSIXct): The token expiry time as a POSIXct datetime object.

Throws an error if the token cannot be retrieved.

### Note
This function works for any IDE running within a Posit Workbench session, not just RStudio.
```

--------------------------------

### Password Prompt Dialog

Source: https://rstudio.github.io/rstudioapi/articles/dialogs.html

Use `askForPassword()` to securely prompt the user for sensitive information like passwords or tokens.

```APIDOC
## askForPassword

### Description
Prompts the user to enter a password or other sensitive credentials.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Function Signature
`askForPassword(prompt = "Password:")`

### Parameters
- **prompt** (string) - Required - The message displayed to the user asking for input.

### Request Example
```r
token <- rstudioapi::askForPassword(
  prompt = "Please provide your GitHub access token."
)
```

### Response
Returns the entered password/credentials as a string, or NULL if the dialog was cancelled.
```

--------------------------------

### Get All Terminal IDs

Source: https://rstudio.github.io/rstudioapi/reference/terminalList.html

Call this function to retrieve a character vector containing all current terminal identifiers. This function was added in RStudio version 1.1.350.

```r
terminalList()
```

--------------------------------

### launcherNfsMount

Source: https://rstudio.github.io/rstudioapi/reference/launcherNfsMount.html

Defines a launcher NFS mount, suitable for use with the `mounts` argument to `launcherSubmitJob()`. This can be used to mount a path from a networked filesystem into a newly generated container.

```APIDOC
## launcherNfsMount(host, path, mountPath, readOnly = TRUE)

### Description
Define a launcher NFS mount, suitable for use with the `mounts` argument to `launcherSubmitJob()`. This can be used to mount a path from a networked filesystem into a newly generated container.

### Arguments

* **host** (string) - The host name, or IP address, of the NFS server.
* **path** (string) - The NFS path to be mounted.
* **mountPath** (string) - The destination path for the mount in the container.
* **readOnly** (boolean) - Optional. Boolean; should the path be mounted read-only? Defaults to TRUE.
```

--------------------------------

### jobRunScript

Source: https://rstudio.github.io/rstudioapi/reference/jobRunScript.html

Starts an R script as a background job. You can specify the script path, job name, encoding, working directory, and environment import/export options.

```APIDOC
## Function: jobRunScript

### Description
Starts an R script as a background job.

### Signature
```R
jobRunScript(
  path,
  name = NULL,
  encoding = "unknown",
  workingDir = NULL,
  importEnv = FALSE,
  exportEnv = ""
)
```

### Arguments

*   **path** (string) - The path to the R script to be run.
*   **name** (string, optional) - A name for the background job. When `NULL` (the default), the filename of the script is used as the job name.
*   **encoding** (string, optional) - The text encoding of the script, if known. Defaults to "unknown".
*   **workingDir** (string, optional) - The working directory in which to run the job. When `NULL` (the default), the parent directory of the R script is used.
*   **importEnv** (boolean, optional) - Whether to import the global environment into the job. Defaults to `FALSE`.
*   **exportEnv** (string, optional) - The name of the environment in which to export the R objects created by the job. Use `""` (the default) to skip export, `"R_GlobalEnv"` to export to the global environment, or the name of an environment object to create an object with that name.
```
Tokens:
Raw