rig config

Manage the rig configuration file.

rig reads a number of settings from a configuration file. The configuration file is a JSON file, rig config config-file-path prints its path, and rig system dirs shows it together with the other directories rig uses.

Most settings can also be overridden with an environment variable. The environment variable takes precedence over the configuration file, and the configuration file takes precedence over rig’s built-in default.

Configuration entries

  • mode (RIG_MODE): the installation mode, either user or admin, see user and admin mode . Defaults to admin.

  • binary-dir (RIG_BINARY_DIR): the directory rig puts the quick links (R-4.5.1, R-release, etc.) into. Defaults to /usr/local/bin in admin mode and ~/.local/bin in user mode. On Windows the defaults are C:\Program Files\R\bin and %USERPROFILE%\.local\bin.

  • r-install-dir (RIG_R_INSTALL_DIR): the root directory of the R installations, i.e. the directory that holds the directories of the individual R versions. Defaults to the platform’s system-wide location in admin mode (/opt/R on Linux, /Library/Frameworks/R.framework on macOS, C:\Program Files\R on Windows), and to ~/.local/share/rig/r (%APPDATA%\rig\data\r on Windows) in user mode. On Windows this entry only applies in user mode; the admin-mode root is fixed, because it also depends on the architecture.

  • rtools-install-dir (RIG_RTOOLS_INSTALL_DIR): Windows only, the directory that holds the Rtools installations. Defaults to C:\ in admin mode (so Rtools 4.5 goes into C:\rtools45) and to %APPDATA%\rig\data\rtools in user mode.

  • download-dir (RIG_DOWNLOAD_DIR): the directory rig downloads the R (and on Windows the Rtools) installers into, before installing them. Defaults to rig-<uid> in the system temporary directory, e.g. /tmp/rig-1000, and to rig under %TEMP% on Windows. The user id is part of the default name on purpose: in admin mode rig downloads as root, in user mode as you, and a directory shared between them would only be writable by whoever created it first. For the same reason rig refuses to use the default directory if it is a symbolic link, or if it is owned by another user, or if other users can write into it. A directory you configure here is created but not checked.

  • no-cache (RIG_NO_CACHE): set it to true to stop rig from using its cache, the same as passing --no-cache. rig then neither reads nor writes the cache directory: it downloads the repository metadata, the binary package indices and the package files again, compiles a source package instead of unpacking a build it made earlier, and downloads an R or Rtools installer again instead of reusing the one in the download directory. What it downloads and builds goes into a temporary directory that is removed when rig exits, so the cache is left exactly as it was. Defaults to false. This is meant for debugging and for the occasional run that must not trust anything cached; it makes rig considerably slower, so it is a poor thing to turn on permanently.

  • concurrent-downloads (RIG_CONCURRENT_DOWNLOADS): the maximum number of downloads rig performs at the same time, e.g. when downloading package files for a project. Defaults to 50.

  • concurrent-installs (RIG_CONCURRENT_INSTALLS): the maximum number of packages rig proj sync installs at the same time, unless overridden with its own --max-concurrent flag. Defaults to the number of CPU cores.

  • sysreqs (RIG_SYSREQS): Linux only. What rig pkg install and rig proj sync do with the OS packages that the R packages need, see their help:

    • auto, the default: install them on the Linux distributions that the system requirements rules know, and quietly skip them on others.
    • true: the same, but also warn on other distributions.
    • print: show the missing OS packages and the commands that install them, but do not run the commands.
    • false: do nothing.

    If neither this entry nor RIG_SYSREQS is set, rig also respects pak’s PKG_SYSREQS=false environment variable.

  • sysreqs-sudo (RIG_SYSREQS_SUDO): how rig installs OS packages when it does not run as root. auto, the default, uses sudo if it works without a password, and otherwise prints the commands for you to run; true always uses sudo, even if it asks for a password; false never uses it.

  • sysreqs-update (RIG_SYSREQS_UPDATE): whether to update the package index (apt-get update, zypper refresh, apk update) before installing OS packages. Defaults to true.

  • sysreqs-rules-url (RIG_SYSREQS_RULES_URL): where rig downloads the system requirements rules from, a gzipped tarball of the repository. rig downloads them at most once a day, and uses the copy built into rig if it cannot download them.

  • positron-setup: user mode only. Set it to false to stop rig from updating Positron’s settings: adding its R installation root to positron.r.customRootFolders, and pointing positron.r.interpreters.default at the default R version. Any other value, and the default, keep the Positron setup on.

  • userlibrary: a JSON object that maps R versions to user library paths. rig maintains this entry itself, as a cache for the rig library commands; you don’t normally need to edit or set it.

rig config list lists the entries that are currently in the configuration file, which is typically fewer than the entries above, because rig only writes an entry once you set it.

Subcommands

config-file-path
Print the path to the rig config file
get
Get a config entry
list
List the names of all config entries
set
Set a config entry

rig config config-file-path

Print the full path to the rig configuration file.

The file might not exist yet; rig creates it when you first set an entry with rig config set.

Usage

rig config config-file-path [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig config get

Print the value of a rig configuration entry.

Configuration keys are listed by rig config list.

Usage

rig config get [OPTIONS] <key>

Arguments

<key>
config key to get

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--json
JSON output
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig config list

List the names of all rig configuration entries.

Use rig config get <key> to see the value of an entry, and rig config set <key>=<value> to change it.

Usage

rig config list [OPTIONS]

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--json
JSON output
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)

rig config set

Set a rig configuration entry.

The argument is a key=value pair, e.g. rig config set mode=user. The configuration file is created if it does not exist yet. See rig config --help for the known keys, and rig config list for the entries that are already in the configuration file.

Usage

rig config set [OPTIONS] <keyvalue>

Arguments

<keyvalue>
key=value pair to set

Options

--admin
Run in admin mode (overrides RIG_MODE and config)
-h, --help
Print help (see a summary with ‘-h’)
--no-cache
Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--user
Run in user mode (overrides RIG_MODE and config)