Publishing from the Command Line
Use the Posit CLI to publish content to Posit Connect from the command line.
If you previously used rsconnect-python to publish to Connect, you do not need to change anything right away. The standalone rsconnect-python CLI still works, so your existing rsconnect commands and scripts continue to run. The Posit CLI includes rsconnect-python for publishing and adds commands such as posit connect api that are not available in the standalone CLI.
When you are ready to switch, replace rsconnect <command> with posit connect <command>. All flags and arguments stay the same. Both CLIs share the same saved servers, so you do not need to add them again.
Installing
Install the Posit CLI using uv:
Terminal
uv tool install posit-cliThe Posit CLI runs in its own Python environment and inspects your project’s Python environment when it deploys content. It uses the activated virtual environment, or a .venv directory in the content directory or one of its parents. To use a different Python, specify its path with the --python option.
Setting up your project
These instructions use uv to manage your project’s Python environment. If your project directory does not have a pyproject.toml file, create one:
Terminal
uv init --bare --python 3.12 --pin-pythonReplace 3.12 with the Python version that your project uses. The --pin-python option writes that version to a .python-version file, which the Posit CLI uses to match a Python version on Connect.
Add your project’s packages with uv add, which also creates the project’s .venv directory. If your project has a requirements.txt file, add its packages with uv add -r requirements.txt.
Adding a Connect server
Using OAuth (recommended)
Use OAuth to sign in to your Connect server without creating an API key:
Terminal
posit connect login https://connect.example.comFollow the prompts in your browser to authorize the CLI. The CLI saves tokens for reuse during deployment, using your operating system keyring when available.
From Posit Workbench or another session without a local browser, use device-code sign-in:
Terminal
posit connect login https://connect.example.com --use-device-codeOpen the displayed URL in a browser and enter the code to authorize the CLI.
posit connect login saves the server under its hostname, such as connect.example.com, and makes it the default server. Deployment commands use the default server when you omit --name. Use --name to choose a different nickname, or --no-set-default to keep your current default server.
Both sign-in methods require the Server.OAuthClientsEnabled setting, which is enabled by default. If your administrator has disabled it, use an API key instead.
Using an API key
For continuous integration (CI) or servers where OAuth clients are disabled, use an API key. Save the server with its URL, API key, and a nickname:
Terminal
posit connect add \
--server https://connect.example.com \
--api-key "$CONNECT_API_KEY" \
--name myServerSet CONNECT_API_KEY to your API key before running this command. Deployment commands can reference the saved server with --name myServer or -n myServer.
Alternatively, set CONNECT_SERVER and CONNECT_API_KEY in your environment without saving a server:
Terminal
export CONNECT_SERVER=https://connect.example.com
export CONNECT_API_KEY="<your-api-key>"
posit connect deploy streamlit .In CI, supply the API key through your CI secret store.
Using the Posit CLI
Use the posit connect deploy command to deploy content to Connect. See the content-specific guides for deployment commands and options:
- Python apps and APIs
- Static HTML
- Jupyter Notebook
- R or other content with a prepared
manifest.json - Quarto content
Package dependencies
The deploy and write-manifest commands read your package dependencies from a requirements.txt file in the source directory. If the content runs Python code and the file does not exist, they stop with an error. Static notebook snapshots and Quarto content without Python code do not need the file. The Posit CLI includes the file in the deployment bundle, and Connect reconstructs the Python environment using the specified package list. Using the same requirements.txt file across multiple deployments also allows Connect to reuse the corresponding Python virtual environments, making deployments faster.
To create the file, export your project’s locked dependencies:
Terminal
uv export --no-dev --no-emit-project --no-hashes -o requirements.txtThe --no-dev option leaves out development dependencies. The --no-emit-project option leaves out the -e . line that uv adds for packaged projects. Run the command again after you add, remove, or upgrade packages.
To read dependencies from a different file, specify it with the --requirements-file option. The option accepts any file in requirements.txt format, or a pyproject.toml file. With pyproject.toml, the Posit CLI uses the unpinned package list in its [project] table, so Connect might install different package versions than you use locally.
Python version matching
Connect attempts to find a Python installation that is appropriate for published content based on the version constraint specified in the manifest.json file.
Example manifest.json file segment:
manifest.json
"environment": {
"python": {
"requires": ">=3.8,<4.0"
}
}By default, the Posit CLI generates this section from Python version information in .python-version, pyproject.toml, or setup.cfg files, in that order. The uv init --pin-python command creates a .python-version file for your project.
The version constraint respects the PEP 440 Specification.
If the Posit CLI cannot find a Python version specification in these files, it omits the version constraint and includes the version of your project’s Python. In this case, Connect falls back to matching <MAJOR.MINOR> versions of Python. For example, a server with only Python 3.10 installed will fail to deploy content created with Python 3.8. Your administrator can also enable exact Python version matching which is stricter and requires matching major, minor, and patch versions. For more information see the Python Version Matching section of the Admin Guide.
Deployment options
These options apply to any type of content deployment.
Title
The title of the deployed content is, by default, derived from the filename. For example, if you deploy my-notebook.ipynb, the title will be my-notebook. To change this, use the --title option:
Terminal
posit connect deploy notebook --title "My Notebook" my-notebook.ipynbWhen deploying an API or application, the title is derived from the directory containing the API or application.
When using posit connect deploy manifest, the title is derived from the primary filename referenced in the manifest.
Environment variables
You can set environment variables during deployment. Their names and values are passed to Connect during deployment so you can use them in your code.
For example, if notebook.ipynb contains
print(os.environ["MYVAR"])You can set the value of MYVAR that is set when your code runs in Connect using the -E/--environment option:
Terminal
posit connect deploy notebook \
--environment MYVAR='hello world' \
notebook.ipynbTo avoid exposing sensitive values on the command line, you can specify a variable without a value. In this case, it uses the value from the environment in which the Posit CLI is running:
Terminal
export SECRET_KEY=12345
posit connect deploy notebook --environment SECRET_KEY notebook.ipynbIf you specify environment variables when updating an existing deployment, new values will be set for the variables you provided. Other variables remain unchanged. If you don’t specify any variables, all of the existing variables remain unchanged.
Environment variables are set on the content item before the content bundle is uploaded and deployed. If the deployment fails, the new environment variables still take effect.
Target image
If your Connect installation uses off-host content execution with Kubernetes, Connect automatically selects an appropriate image to use when building or running your content. However, you can also specify a different image by providing the image argument when writing a manifest or deploying:
Terminal
posit connect deploy api \
--image "ghcr.io/posit-dev/connect-content:R4.6.0-python3.14.5-ubuntu-24.04-base" \
...
posit connect write-manifest api \
--image "ghcr.io/posit-dev/connect-content:R4.6.0-python3.14.5-ubuntu-24.04-base" \
...You can only use an image that has been configured by your administrator. To see a list of available images, log in to Connect, click System in the top menu bar, then click Environments under Manage.
If the image you select does not contain an appropriate Python version for the content you are deploying, the deployment will fail.
At any time, you can redeploy content without specifying an image (or write a manifest without specifying an image, and deploy the manifest) to go back to allowing Connect to choose an image automatically.
The following subcommands do not support the --image argument:
Terminal
posit connect deploy html
posit connect deploy manifest
posit connect deploy other-contentSpecifying an environment management strategy
Note that the environment management features used in this guide are also applicable for Connect in local execution mode. Off-host execution is not required to use the environment management features.
Sometimes it is preferable to self-manage Python package installation for your system, rather than allowing Connect to install packages for you. This can be useful in situations where many pieces of content share the same set of packages, or if off-host execution is enabled and the packages are already installed in the execution environment image.
Terminal
posit connect deploy api --disable-env-management-py ...
posit connect write-manifest api --disable-env-management-py ...When environment management is disabled, Connect uses only the packages that are already installed in the system library. No new packages are installed during the deployment. It is up to your administrator to install the required packages in the system library so that they are available for your content at runtime.
At any time, you can redeploy content without specifying an environment management strategy (or write a manifest without specifying, and deploy the manifest) to go back to allowing Connect to choose an environment management strategy based on the application-level and server-level defaults specified by your server administrator.
The following subcommands do not support the --disable-env-management flags:
Terminal
posit connect deploy html
posit connect deploy manifest
posit connect deploy other-contentUpdating a deployment
If you deploy a file again to the same server, posit connect will update the previous deployment. This means that you can keep running posit connect deploy notebook my-notebook.ipynb as you develop new versions of your notebook. The same applies to other Python content types.
Forcing a new deployment
To bypass this behavior and force a new deployment, use the --new option:
Terminal
posit connect deploy dash --new my-app/Updating a different deployment
If you want to update an existing deployment but don’t have the saved deployment data, you can provide the app’s numeric ID or GUID on the command line:
Terminal
posit connect deploy notebook --app-id 123456 my-notebook.ipynbYou must be the owner of the target deployment or a collaborator with permission to change the content. The type of content (static notebook, notebook with source code, API, or application) must match the existing deployment.
No confirmation is required to update a deployment. If you do so accidentally, use the Bundles dialog in the Connect dashboard to activate the previous version and remove the erroneous one.