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.

See Admin Setup for Remote Use for steps on creating API tokens as an admin.
See Remote User Setup for Remote Use for steps on using the Package Manager CLI remotely as a user.

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:

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.
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:

Download the standalone Package Manager CLI, ensuring that the CLI version matches the server version.
Set an environment variable named PACKAGEMANAGER_TOKEN with the value of the token.
Set an environment variable named PACKAGEMANAGER_ADDRESS with the address of the Package Manager server.
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#

Advanced

API tokens are used to authenticate with the server when using the Package Manager CLI remotely.

API Token Security#

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

Grant access only to the minimum necessary scope to run the required commands. For sources tokens, grant access only to the required sources using the --sources flag.
Provide a token expiration with the --expires flag when creating a token. Tokens never expire by default.
Rotate tokens regularly.

Creating API Tokens#

You can create a token using the rspm create token command. API tokens have several properties. The token scope, description, expiry, and sources can only be set when the token is created; they cannot be changed. Tokens can be revoked at any time.

Scope - The type of access granted by the token, such as sources:write or global:admin. See API Token Scopes for a list of available scopes. Required.
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.

Note

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.

API Token Scopes#

Name	Description
`global:admin`	Grants full access to manage the Package Manager server.
`sources:write`	Grants read and write access to sources, such as uploading packages, removing packages, creating Git builders, and importing Git credentials. Access can be limited to specific sources.
`blocklist:admin`	Grants full access to manage the blocklist.
`blocklist:read`	Grants read access to the blocklist.

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 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.