Package Manager is administered through a command-line interface (CLI). Administrators can use the CLI to create repositories and sources, add local packages to sources, and setup sync schedules for CRAN, PyPI, and Bioconductor sources.
The CLI is installed at
/opt/rstudio-pm/bin/rspm. The CLI uses the configuration defined
/etc/rstudio-pm/rstudio-pm.gcfg unless you specify an alternate configuration file with
The CLI can be used locally or remotely. Locally, this CLI authenticates through a domain socket. Remotely, the CLI authenticates through an API token and HTTP(S) requests. Some commands may be unavailable remotely.
Users must be a member of the
rstudio-pm group in order to use the Package
Manager CLI. See the Changing RunAs User section for instructions on changing the required group.
The Package Manager CLI uses a Unix domain socket for communicating with the
Package Manager server. By default, the domain socket file is located at
/var/run/rstudio-pm/rstudio-pm.sock. You can customize the location by configuring
Any user invoking the Package Manager CLI must have read/write access to the Unix domain socket in order to communicate with the Package Manager server.
The major and minor server and CLI versions must match for compatibility
purposes. If you attempt to use an incompatible CLI version with a server
and CLI version greater than
v2022.04, the operation will fail
harmlessly. If you attempt to use an incompatible CLI with a server or
v2022.04 or earlier, the results may be unexpected.
Commands Available for Remote Use#
Remote use is disabled by default. You can use the following Package Manager CLI commands remotely when API tokens are enabled:
For information on enabling and using API tokens, please see API Tokens. Complete the Admin Setup for Remote Use section below to enable remote use.
Admin Setup for Remote Use#
Follow these steps to prepare Package Manager for remote use:
- Enable the
Authentication.APITokenAuthconfiguration setting and restart the Package Manager service.
- Create a token using the
rspm create tokencommand. See
rspm create token.
- Give the token and the full address of the server (including the port if not using a default port like 80/443) to the remote user.
Remote User Setup for Remote Use#
Follow these steps to use Package Manager remotely:
- Download the Package Manager CLI, ensuring that the CLI version matches the server version.
- Set an environment variable named
PACKAGEMANAGER_TOKENwith the value of the token.
- Set an environment variable named
PACKAGEMANAGER_ADDRESSwith the address of the Package Manager server.
- Use the CLI commands that support remote use.
Instead of setting the
PACKAGEMANAGER_ADDRESS environment variable, you
can alternatively use the
--address flag with CLI commands that support
For examples using the CLI remotely, please refer to the Quick Start guide.
The CLI is located at
/opt/rstudio-pm/bin/rspm. We recommend that users make
an alias, add this location to their PATH, or navigate to this directory if they
will be running multiple commands in one session, for example:
$ alias rspm='/opt/rstudio-pm/bin/rspm'
rspm without any arguments to display the top-level help for the
Package Manager CLI. For help with a specific command, you can use the
For example, to display help about the
create command, you can use
create. For a complete list of commands, see the Command-Line Interface documentation.
You can use certain Package Manager CLI commands remotely when API tokens
are enabled. To enable API tokens, please use the
Currently, only a subset of the available CLI commands support remote use.
API Token Security#
For the best security, please consider the following when creating API tokens:
- Provide a token expiration with the
--expiresflag when creating a token.
- Rotate tokens regularly.
- Grant access only to the required sources using the
Creating API Tokens#
You can create a token using the
rspm create token command.
API tokens have several properties. The token description, expiry, and sources
can only be set when the token is created; they cannot be changed. Tokens can
be revoked at any time.
- Description - A description of the token; provided when token is created. Required.
- Sources - The sources to which the token is granted access. When set to
*, the token is valid for all current and future sources. Required.
- Expires - An expiration time for the token. The token cannot be used after this time.
An expiry of
nevermeans that the token never expires. You can specify a duration like
30d(30 days) or
5m(5 minutes). Defaults to
- Revoked - A revoked token cannot be used; revoked tokens cannot be reinstated.
When an API token is created for a specific local or git source, the token is valid only for the source you specified. If you delete the source and re-create a new source with the same name, you will need to create a new API token for the new source.
Listing API Tokens#
You can list API tokens with the
rspm list tokens
command. Use the
--revoked flags to filter the results.
Revoking API Tokens#
You can revoke API tokens at any time with the
rspm revoke token command. Revoked tokens
cannot be reinstated, and are no longer valid for use. To revoke a token, you
can provide the token or the GUID associated with the token. You can
List API Tokens to find the GUID associated with each
The CLI can generate an autocompletion script for Bash. This can help you work with the CLI more
efficiently, using your autocomplete key (often TAB) to both complete commands and bring up options. Once installed, the
autocompletion works for
rspm subcommands and for flags to each command. To show instructions for how to install the
rspm completion --help.
Example output from the autocompletion script:
$ rspm url (push tab key twice) create explain $ rspm (push tab key twice) add cluster create encrypt hup list online rerun sync url archive completion delete evict import logs remove run unsubscribe clear config edit help info offline reorder subscribe update $ rspm create (push tab key twice) git-builder repo source $ rspm create source --(push tab key twice) --config --name --output-format --snapshot --type --verbose --version= --config= --name= --output-format= --snapshot= --type= --version
For examples using the CLI, please refer to the Configuration guide.