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 can authenticate with Package Manager for remote CLI use in multiple ways:

  • SSO Authentication: Use rspm login sso to authenticate through your organization’s OpenID Connect provider (requires OpenID Connect configuration).
  • Identity Federation: Use external OpenID Connect tokens with automatic token exchange (requires identity federation configuration).
  • API Token Authentication: Use rspm login or environment variables with long-lived API tokens.

For detailed setup instructions:

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. For SSO Authentication: Ensure Package Manager is configured with an OpenID Connect provider. See OpenID Connect Authentication for configuration details.
  2. For Identity Federation: Ensure Package Manager is configured with appropriate IdentityFederation providers that match your external systems’ token issuers. See OpenID Connect Identity Federation for configuration details.
  3. For API Token Authentication: 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.
  4. Provide remote users with either:
    • The server address for SSO authentication: https://packagemanager.example.com
    • The server address for identity federation (external systems will provide their own tokens)
    • The API token and server address for token authentication
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

Method 2: Using Identity Federation (For CI/CD with External OIDC Tokens)

For CI/CD systems and automation environments that already have access to OpenID Connect tokens from external providers, you can use the PACKAGEMANAGER_IDENTITY_TOKEN_FILE environment variable:

  1. Download the standalone Package Manager CLI, ensuring that the CLI version matches the server version:
Terminal
RSPM_SERVER_VERSION=2025.09.0-7
curl -o rspm -f https://cdn.posit.co/package-manager/linux/amd64/rspm-cli-linux-${RSPM_SERVER_VERSION}
chmod +x rspm
Terminal
RSPM_SERVER_VERSION=2025.09.0-7
curl -o rspm -f https://cdn.posit.co/package-manager/darwin/amd64/rspm-cli-darwin-${RSPM_SERVER_VERSION}
chmod +x rspm

Ensure compatibility by setting the RSPM_SERVER_VERSION environment variable to the server version. The server version can be found by running the following command on a running Package Manager server:

Terminal
$ rspm --version
...
Posit Package Manager Server Version: 2025.09.0-7; ...

  1. Set environment variables:

    Terminal
    export PACKAGEMANAGER_ADDRESS=https://packagemanager.example.com
export PACKAGEMANAGER_IDENTITY_TOKEN_FILE=/path/to/external-oidc-token-file

  2. Run CLI commands directly (token exchange happens automatically):

    Terminal
    rspm verify

When PACKAGEMANAGER_IDENTITY_TOKEN_FILE is set and Package Manager is configured with matching identity federation providers, the CLI will automatically:

  • Read the external OpenID Connect token from the specified file
  • Perform RFC 8693 token exchange to obtain a Package Manager token
  • Use the exchanged token for authentication
  • Execute the requested command

This method is ideal for:

  • GitHub Actions workflows with OIDC tokens
  • GitLab CI pipelines with CI_JOB_JWT_V2 tokens
  • Azure DevOps with federated credentials
  • Other CI/CD systems that provide OpenID Connect tokens
Note

This method requires that Package Manager is configured with appropriate IdentityFederation providers that match your external token’s issuer, audience, and subject claims. For detailed configuration examples, see the OpenID Connect Identity Federation guide.

Method 3: Using Environment Variables (For CI/CD and Automation)

For automated systems and CI/CD pipelines, you can use environment variables:

  1. Download the standalone Package Manager CLI, ensuring that the CLI version matches the server version:
Terminal
RSPM_SERVER_VERSION=2025.09.0-7
curl -o rspm -f https://cdn.posit.co/package-manager/linux/amd64/rspm-cli-linux-${RSPM_SERVER_VERSION}
chmod +x rspm
Terminal
RSPM_SERVER_VERSION=2025.09.0-7
curl -o rspm -f https://cdn.posit.co/package-manager/darwin/amd64/rspm-cli-darwin-${RSPM_SERVER_VERSION}
chmod +x rspm

Ensure compatibility by setting the RSPM_SERVER_VERSION environment variable to the server version. The server version can be found by running the following command on a running Package Manager server:

Terminal
$ rspm --version
...
Posit Package Manager Server Version: 2025.09.0-7; ...

  1. Set environment variables:

    Terminal
    export PACKAGEMANAGER_TOKEN=your-api-token-here
export PACKAGEMANAGER_ADDRESS=https://packagemanager.example.com

  2. Test that CLI commands work remotely:

    Terminal
    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