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.

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.

Privileges#

Local Use#

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

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:

• rspm add
• rspm add binary
• rspm create blocklist-rule
• rspm create git-builder
• rspm delete blocklist-rule
• rspm edit blocklist-rule
• rspm list blocklist-rules
• rspm test blocklist-rules

For information on enabling and using API tokens, please reference the API Tokens section. 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:

1. Enable the Authentication.APITokenAuth configuration setting and restart the Package Manager service.
2. Create a token using the rspm create token command.
3. 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:

1. Download the 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. Use the CLI commands that support remote use.

Examples#

For examples using the CLI remotely, please refer to the Quick Start guide.

Location#

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'

Getting Help#

Simply run 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 help command. For example, to display help about the create command, you can use rspm help create. For a complete list of commands, reference the Command-Line Interface documentation.

API Tokens#

Advanced

You can use certain Package Manager CLI commands remotely when API tokens are enabled. To enable API tokens, please use the Authentication.APITokenAuth configuration setting.

API Token Security#

For the best security, please consider the following when creating API tokens:

• Provide a token expiration with the --expires flag when creating a token.
• Rotate tokens regularly.
• Grant access only to the required sources using the --sources flag.

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 never means that the token never expires. You can specify a duration like 30d (30 days) or 5m (5 minutes). Defaults to never.
• Revoked - A revoked token cannot be used; revoked tokens cannot be reinstated.

Listing API Tokens#

You can list API tokens with the rspm list tokens command. Use the --expired and --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 token.

Autocompletion#

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 autocompletion, run rspm completion --help.

Push Tab+Tab to see suggested commands. 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

Examples#

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