Admin CLI

Posit Package Manager is administered through a command-line interface (CLI). Administrators can use the CLI to create and configure repositories, sources, and packages.

The CLI is installed at /opt/rstudio-pm/bin/rspm. The CLI uses the configuration defined in /etc/rstudio-pm/rstudio-pm.gcfg unless you specify an alternate configuration file with the --config flag.

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:

Terminal
alias rspm='/opt/rstudio-pm/bin/rspm'

Run rspm --help to display the top-level help for the Package Manager CLI. For help with a specific command, you can run rspm help <command>. For a complete list of commands, reference the Command-Line Interface documentation.

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.

Local Use

Users must be a member of the rstudio-pm group in order to use the Package Manager CLI locally. Refer to 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 the Server.SockFileDir setting.

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.

Remote Use

Advanced

Users must have an API token to use the Package Manager CLI remotely.

All commands are available for remote use except the rspm online, rspm offline, and rspm cluster commands.

Admin Setup for Remote Use

Follow these steps to prepare Package Manager for remote use:

  1. Create an API token using the rspm create token command. Grant the minimum scope necessary to run the required commands. See API Tokens for details on creating tokens and best practices for security.
  2. Provide the remote user with the API token and the full address of the server, such as https://my-rspm-server.org:4443. Include the port if not using a default port like 80/443.
Warning

It is strongly recommended to use HTTPS when using the remote CLI with Package Manager. Sending sensitive information over HTTP is insecure and exposes exchanged data to the risk of a MitM attack and theft.

Remote User Setup for Remote Use

Follow these steps to use Package Manager remotely:

  1. Download the standalone Package Manager CLI, ensuring that the CLI version matches the server version.
  2. Set an environment variable named PACKAGEMANAGER_TOKEN with the value of the token.
  3. Set an environment variable named PACKAGEMANAGER_ADDRESS with the address of the Package Manager server.
  4. Test that CLI commands work remotely by running the command, rspm verify.
Note

Instead of setting the PACKAGEMANAGER_ADDRESS environment variable, you can alternatively use the --address flag in each CLI command.

By default, the PACKAGEMANAGER_TOKEN environment variable sets the token used in the Authorization HTTP header. If Package Manager is behind a proxy that also requires an Authorization header, you can set both PACKAGEMANAGER_TOKEN and PACKAGEMANAGER_PROXY_TOKEN. In this case, PACKAGEMANAGER_PROXY_TOKEN will be used in the Authorization header for the proxy, and PACKAGEMANAGER_TOKEN will be sent in the X-PPM-Authorization header.

Examples

For examples of using the CLI remotely, please refer to:

API Tokens

API tokens are used to authentication users for repositories that require authentication, and to authenticate with the server when using the Package Manager CLI remotely.

See API Tokens for details on creating API tokens.

Autocompletion

The CLI can generate an autocompletion script for Bash and Fish. Completions 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 autocompletion, run rspm completion --help.

Push ++tab+tab++ to see suggested commands. Example output from the autocompletion script:

Bash

Terminal
$ 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

Fish

$ rspm (push tab key twice)
add                   (Command to add packages to sources. Supports remote use with API tokens when enabled.)
archive                                                            (Command to archive a package in a source)
cluster                                                                  (Commands for HA/cluster operations)
completion                                                             (Generate shell autocompletion script)
config                                                               (Commands to alter server configuration)
create                                                                          (Commands to create entities)
…and 23 more rows

$ rspm create (push tab key twice)
blocklist-rule         (Command to create blocklist rules. Supports remote use with API tokens when enabled.)
bulk-blocklist-rules   (Command to create blocklist rules. Supports remote use with API tokens when enabled.)
git-builder               (Command to create git-builders. Supports remote use with API tokens when enabled.)
repo                                                                                (Command to create repos)
source                                                                            (Command to create sources)
token  (Command to create tokens. The token will be written to stdout. Informational messages are written t…)

$ rspm create --(push tab key twice)
--config                                                                                (Path to config file)
--help                                                                                      (help for create)
--output-format  (Specify the output format 'human' for human-readable output or 'json' for JSON-encoded ou…)
--verbose                                                                         (Provide additional output)

Examples

For examples using the CLI, please refer to the Configuration guide.

Back to top