rig auth

rig can use HTTP basic authentication when downloading packages, metadata or when using Posit Package Manager’s API.

These are the rules for when rig sends an Authorization header and how it looks up credentials:

A password in the URL. This is only allowed for URLs given on the command line, with --with-repos, and rig does not store it.
The RIG_REPO_<NAME>_USERNAME and RIG_REPO_<NAME>_PASSWORD environment variables, for the repository called <NAME>: the name you gave to rig repos add, in --with-repos <name>=<url>, or in [[repository]] in rproj.toml. rig auth status shows it in the name column. <NAME> is in upper case, with every character that is not a letter or a digit replaced by _.
A PPM single sign-on (SSO) token from rig auth login, or from pak.
A netrc file.
The system credential store (macOS Keychain, Windows Credential Manager, Secret Service on Linux), only for URLs that include a username. Passwords saved with rig auth login --username go here.

rig uses the same netrc file, the same credential store keys and the same PPM token file as pak, so credentials that work with pak also work with rig, and the other way around.

These credentials are only used by rig itself. R’s own install.packages() does not use them.

rig never stores passwords in its configuration file, in rproj.toml or in rproj.lock.

See the authentication guide for details and examples.

Subcommands

login: Save credentials for a repository or Package Manager instance
logout: Remove saved credentials
status: Show which repositories have credentials
token: Print the password or token rig uses for a URL

`rig auth login`

The argument is a URL, or the name of a repository of the default R installation or one added with rig repos add. For a name, rig uses the URL of that repository, including the username in it, if there is one.

Without --username, log in to a Posit Package Manager (PPM) instance with single sign-on (SSO). rig prints a URL and a code, and opens the URL in your browser. After you log in there, rig saves the PPM token in ~/.ppm/tokens.toml (or the file PACKAGEMANAGER_SSO_TOKEN_FILE names), the same file pak uses. The URL is the base URL of the PPM instance, by default the value of the PACKAGEMANAGER_ADDRESS environment variable.

If PACKAGEMANAGER_IDENTITY_TOKEN_FILE is set, e.g. on a CI system, rig exchanges the identity token in that file for a PPM token, instead of using the browser.

With --username, save a password for a repository in the system credential store: macOS Keychain, Windows Credential Manager, or a Secret Service (e.g. GNOME Keyring) on Linux. rig asks for the password, or reads it from the standard input with --password -. rig does not check the password.

rig only looks in the credential store for repository URLs that include the username, so add the repository with the username in its URL, e.g. https://alice@cran.example.com/cran. The URL you log in to can be a repository URL, or the URL of the host, e.g. https://cran.example.com, to use the same password for every repository there. It does not have to be a configured repository; if none uses the credentials yet, rig tells you.

See the authentication guide for details.

Usage

rig auth login [OPTIONS] [url]

Arguments

[url]: URL or name of a repository, or URL of a Package Manager instance (default: PACKAGEMANAGER_ADDRESS)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--cache-dir <CACHE_DIR>: Path to the cache directory (overrides RIG_CACHE_DIR and config)
-h, --help: Print help (see a summary with ‘-h’)
--no-browser: do not open the browser for SSO, only print the URL
--no-cache: Do not read or write rig’s cache (overrides RIG_NO_CACHE and config)
--password <password>: password, - reads it from the standard input (default: ask)
--user: Run in user mode (overrides RIG_MODE and config)
-u, --username <username>: username, for the system credential store

Examples

# Log in to your PPM instance with SSO
export PACKAGEMANAGER_ADDRESS=https://ppm.example.com
rig auth login

# Save a password for a repository
rig auth login https://cran.example.com/cran --username alice

# The same, for the repository you added as `acme`, with
# `rig repos add acme https://alice@cran.example.com/cran`
rig auth login acme

# Read the password from the standard input
echo "$PASSWORD" | rig auth login https://cran.example.com/cran --username alice --password -

`rig auth logout`

The argument is a URL, or the name of a configured repository, as for rig auth login.

Without --username, remove the PPM SSO token of a Posit Package Manager instance from the token file. The URL is the base URL of the instance, by default the value of PACKAGEMANAGER_ADDRESS.

With --username, remove the password of that user for the URL from the system credential store.

This only removes credentials that rig (or pak) saved on this computer. It does not end your session on the server.

Usage

rig auth logout [OPTIONS] [url]

Arguments

[url]: URL or name of a repository, or URL of a Package Manager instance (default: PACKAGEMANAGER_ADDRESS)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--cache-dir <CACHE_DIR>: Path to the cache directory (overrides RIG_CACHE_DIR 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)
-u, --username <username>: username, for the system credential store

Examples

rig auth logout
rig auth logout https://cran.example.com/cran --username alice

`rig auth status`

Show, for every repository of the default R installation, and for the repositories added with rig repos add, whether rig found credentials for it, and where. With a URL or a repository name, show only that.

The source column tells where the credentials come from:

url: a password in the URL.
env:RIG_REPO_<NAME>_PASSWORD: an environment variable.
ppm-sso:<file>: a PPM SSO token.
netrc:<file>: a netrc file.
keyring:<backend>:<key>: the system credential store.

If rig found no credentials, this column says why, if it knows.

rig then lists the PPM SSO tokens, with their expiry times. With --connect, rig also asks each PPM instance whether it accepts the token.

This command never prints passwords or tokens.

Usage

rig auth status [OPTIONS] [url]

Arguments

[url]: only show this URL

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--cache-dir <CACHE_DIR>: Path to the cache directory (overrides RIG_CACHE_DIR and config)
--connect: check PPM SSO tokens with the server
-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)

Examples

rig auth status
rig auth status https://alice@cran.example.com/cran
rig auth status --connect

`rig auth token`

The argument is a URL, or the name of a configured repository, as for rig auth login.

Print the password or token that rig sends to a URL, e.g. to use it in a script. Include the username in the URL, or use --username, if the credentials are in the system credential store.

rig prints only the secret, so be careful where the output goes.

Usage

rig auth token [OPTIONS] [url]

Arguments

[url]: URL or name of a repository, or URL of a Package Manager instance (default: PACKAGEMANAGER_ADDRESS)

Options

--admin: Run in admin mode (overrides RIG_MODE and config)
--cache-dir <CACHE_DIR>: Path to the cache directory (overrides RIG_CACHE_DIR 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)
-u, --username <username>: username, for the system credential store

Examples

curl -u "__token__:$(rig auth token https://ppm.example.com)" \
  https://ppm.example.com/__api__/status