rig run

Run R, an R script or an R project, using the selected R version.

All of these examples allow an --r-version argument, to use a specific R version.

rig run                    # start R
rig run -f <script-file>   # run an R script
rig run -e <expression>    # evaluate an R expression
rig run <pkg>::<script>    # run a script from a package's exec directory
rig run <name>             # run a script the project declares
rig run --list             # list the scripts the project declares
rig run <path-to-app>      # run an R app
rig run --cmd <command>    # run `R CMD <command>`

Projects

If the current directory is inside a project (i.e. rig finds an rproj.toml, an rproj.lock, an .rvenv directory or an .rvenvlib directory at or above it), then rig run uses the project’s own environment instead of the default R version: it runs .rvenv/bin/R, which sets the project’s package library and repositories, and it uses the R version the project’s lock file names.

Before running R, rig syncs the environment if it is out of date, i.e. it runs the equivalent of rig proj lock and rig proj sync for you, which may also install the R version the project needs. There is nothing to source and no shell state to keep, so this also works in a Makefile or in CI.

Two things turn this off, and run the default R version instead:

• --r-version, because a project environment is tied to the R version its lock file names, and
• --no-project.

If the project has not been initialized at all, i.e. it has no .rvenvlib directory, then rig run fails and asks you to run rig proj init, instead of quietly running an R that is not the project’s.

Project scripts

A project can give its own scripts a name, in the [[bin]] tables of its rproj.toml:

[[bin]]
name = "report"
path = "scripts/report.R"
description = "Build the report"

rig run report --format pdf then runs scripts/report.R in the project’s environment, and passes --format pdf on to the script, where commandArgs(TRUE) picks it up. path is relative to the project directory, so a declared script works the same from anywhere within the project. rig run --list lists the declared scripts, and --json prints them as JSON.

A declared name wins over a directory of the same name. Arguments that look like a path rather than a name are never script names: anything containing a slash or ::, anything ending in .R, .r, .Rmd or .qmd, and . and ... Use ./name to run an app in a directory whose name a script has taken.

Supported apps

Currently supported apps are:

• Plumber APIs,
• Shiny apps,
• Quarto documents embedding Shiny apps,
• Quarto documents,
• Rmd documents,
• Rmd documents embedding Shiny apps,
• Static web sites.

Usage

rig run [OPTIONS] [command]...

Arguments

[command]...

R script, project script name, project or R CMD command to run, with parameters

Options

--admin

Run in admin mode (overrides RIG_MODE and config)

-t, --app-type <app-type>

Explicitly specify app type to run [possible values: api, shiny, quarto-shiny, rmd-shiny, quarto-static, rmd-static, static]

--cmd

Run R CMD <command> with the trailing arguments

--dry-run

Show the command, but do not run it

--echo

Print input to R

-e, --eval <eval>

R expression to evaluate

-h, --help

Print help (see a summary with ‘-h’)

--json

JSON output

--list

List the scripts the project declares

--no-cache

Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)

--no-echo

Do not print input to R

--no-project

Ignore the project environment, use the default R version

--no-startup

Do not print R startup message

-r, --r-version <r-version>

R version to use

-f, --script <script>

R script file to run

--startup

Print R startup message

--user

Run in user mode (overrides RIG_MODE and config)