deploy-to-connect

Deploying to Posit Connect

This guide covers Python, R, and static content on a Connect server. A registered Connect Model Context Protocol (MCP) server can also provide publishing tools.

Choose the deployment route that matches the content and available tools:

• Python — posit-cli, which provides the posit CLI and is published on PyPI. Its posit connect commands wrap rsconnect-python.
• R — the R rsconnect package, pointed at a Connect server.
• A registered Connect MCP server — use its publishing tools when they support the content.

If the user asks a question ("how do I…", "what is the command…") rather than asking for a deploy, answer from this guide and stop.

At the end, report which server you deployed to, which content type you picked, any tool you installed, and any assumption you made.

---

Stage 1 — Detect the content

Infer the language and framework from the files in the project directory. Common signals:

Signal in project dir	Likely content
app.py	Python web app — Shiny for Python, Streamlit, Dash, Gradio, Panel, or Bokeh
app.R, or ui.R + server.R	Shiny for R
plumber.R / entrypoint.R containing plumb()	Plumber API (R)
*.qmd	Quarto document
*.Rmd	R Markdown
*.ipynb	Jupyter notebook / Voila
index.html, or a directory containing HTML, CSS, JavaScript, or image files	Static HTML site
manifest.json	Prebuilt bundle — deploy it directly, no framework guess needed
A bare .py or .R — no framework import, no ui.R/server.R/plumber.R/entrypoint.R alongside	Script — a batch/ETL job that Quarto renders and Connect can schedule

Confirm the guess

The imports in app.py name the framework:

grep -Eo 'import (shiny|streamlit|dash|gradio|panel|bokeh)|from (shiny|streamlit|dash|gradio|panel|bokeh)' app.py

A bare ASGI or WSGI object means fastapi or flask.

Dependency files confirm the language: requirements.txt and pyproject.toml for Python, DESCRIPTION and renv.lock for R.

Quarto renders a script only if it opens with a front-matter comment: # %% [markdown] around a --- block in Python, #' --- in R. Most scripts lack one — add it before the deploy (Stage 5).

If the content is ambiguous (both Python and R files, or an app.py with no recognizable import), use your discretion, and report the assumption you made.

---

Stage 2 — Inventory your tools

Probe the environment and build a capability set:

command -v posit                                     # posit-cli on PATH
command -v rsconnect                                 # rsconnect-python on PATH
command -v uv                                        # uv (installs and runs Python tools)
uv tool list 2>/dev/null | grep posit-cli            # posit-cli installed via uv
command -v Rscript                                   # R present
Rscript -e 'cat(requireNamespace("rsconnect", quietly=TRUE))' 2>/dev/null   # R rsconnect package
command -v quarto                                     # quarto CLI
command -v git                                        # git

With uv present, Python content needs no install step. uv tool run --from posit-cli posit ... fetches and runs the CLI on demand. If an authenticated Connect MCP server is registered, include its publishing tools in the capability set.

---

Stage 3 — Pick a route

Cross the detected content (Stage 1) with your capabilities (Stage 2).

Registered Connect MCP server

If a registered Connect MCP server offers publishing tools for this content, follow the guidance provided by that server. Otherwise, use a publishing client below.

Python content

Use posit-cli. With posit on PATH:

posit connect deploy <framework> ./my-app

Off PATH but with uv present:

uv tool run --from posit-cli posit connect deploy <framework> ./my-app

Both forms take identical arguments. The rest of this guide writes the bare posit connect ... form. Prefix it with uv tool run --from posit-cli when you use the second route.

posit connect mounts the full rsconnect command set, so posit connect <command> and rsconnect <command> take the same arguments and share the same saved servers. If rsconnect is on PATH and you cannot get posit, run rsconnect <command> in place of posit connect <command>.

<framework> is one of api, bokeh, bundle, dash, fastapi, flask, git, gradio, html, manifest, nodejs, notebook, panel, pyproject, quarto, shiny, streamlit, tensorflow, voila. For anything outside that list, posit connect deploy other-content prints guidance.

The frameworks and flags depend on the installed version, so confirm against posit connect deploy --help rather than this list. If uv tool run resolves a stale cached version, add --refresh: uv tool run --refresh --from posit-cli posit ....

R content

Use the R rsconnect package, through Rscript -e '...' or an R session:

• Shiny for R, Plumber API, or any app directory → deployApp()
• A single R Markdown or Quarto document → deployDoc()
• A full R Markdown or Quarto site → deploySite()

If Rscript is absent, deploy the R content through posit-cli with a manifest.json:

• A manifest.json already exists — deploy it directly:

  posit connect deploy manifest ./manifest.json
  

• No manifest, but R is available elsewhere — generate one first with rsconnect::writeManifest() (see Stage 5).
• Neither R nor a manifest — a valid R bundle is not possible. Surface this as a blocker: ask the user or report it clearly.

Quarto content

posit connect deploy quarto ./report

R-flavored Quarto (a .qmd with R code chunks) needs R to render. If R is absent, treat the document as R content and use the manifest route, or surface the gap.

Script content

Use the quarto framework. Add the front matter first (Stage 5).

posit connect deploy quarto script.py    # Python

rsconnect::deployApp()               # R, rsconnect 1.2.2 or later, from the directory of the script

Both commands include every file in the directory. Push-button publishing does not cover R scripts, so deployApp() is the only R route.

A script deploys like a Quarto document but is a different content type: a .qmd is a page to read, a script is a job that writes output.

---

Stage 4 — Find the target and check its credentials

Now that the tool is known, find out which server to deploy to and whether the tool can already reach it. This is a check, not a login.

If using publishing MCP tools, the authenticated MCP connection identifies the target. Confirm that it matches the server the user named. If the user named no server, ask which target to use. Do not inspect CLI accounts or register a server for the MCP route. Follow that server's publishing guidance when the target is clear.

Do not search the environment for API keys. Do not read CONNECT_API_KEY, CONNECT_SERVER, a .env file, a keychain entry, or any other stored secret to pick a target or to register a server. Do this only when the user explicitly asks for it. An environment variable is not a request to use it.

For CLI routes, list the accounts the tool already has. This is the only CLI credential check you need.

posit connect list                               # Python: saved servers, stored tokens, and the default server
Rscript -e 'print(rsconnect::accounts())'        # R: registered accounts

If the tool is not installed yet, close that gap in Stage 5 first. Then run the check.

Compare the result with the target the user named. Three outcomes:

• An account matches the named target. The credential path is live. Run no login and no posit connect add. Continue to Stage 6 once the other gaps are closed.
• The user named no target. Ask them. List the servers the check found, and ask which one to deploy to, or whether they want a new target instead. Do not pick one for them, and do not deploy to the only saved server because it is the only one.
• The target is new, or no account matches it. This is a gap for Stage 5. Register it with a browser login.

A browser login is the way to register a new target:

posit connect login https://connect.example.com  # Python

rsconnect::addServer(url = "https://connect.example.com", name = "myserver")   # R
rsconnect::connectUser(server = "myserver")

Both forms open a browser flow, so the user approves the login and no key passes through the conversation. The credentials reference has the details and the pitfalls.

---

Stage 5 — Resolve gaps

When Stages 3 and 4 find a gap, close it, then include the action in your report.

posit not on PATH. With uv present, no install is needed:

uv tool run --from posit-cli posit connect deploy <framework> ./my-app

If the user wants it installed persistently, or uv tool run is not viable:

uv tool install posit-cli     # or: pip install posit-cli

The package name and the command name differ: the PyPI package is posit-cli, and the command it provides is posit. That is why uv tool run needs --from posit-cli. To update later, run uv tool upgrade posit-cli.

R rsconnect package missing, Rscript present. Install it from Posit Package Manager (P3M), which serves precompiled Linux binaries. A binary install is much faster than a source build and needs no -dev system libraries. Binaries need two things: the __linux__/<codename> repo URL and a platform-identifying HTTPUserAgent. Without the user agent, P3M serves source.

export P3M="https://packagemanager.posit.co/cran/__linux__/$(. /etc/os-release && echo "$VERSION_CODENAME")/latest"
Rscript -e '
  options(HTTPUserAgent = sprintf("R/%s R (%s)", getRversion(),
    paste(getRversion(), R.version["platform"], R.version["arch"], R.version["os"])))
  install.packages("rsconnect", repos = Sys.getenv("P3M"))
'

P3M binaries exist for x86_64 on common distros. On arm64 or an unsupported distro, P3M falls back to source. That result is still correct, only slower, and it needs the usual -dev libraries and a compiler. Use https://cloud.r-project.org (CRAN source) only when P3M is unreachable.

manifest.json missing for R content, R present. Generate it:

Rscript -e 'rsconnect::writeManifest()'

posit-cli writes one for Python content:

posit connect write-manifest <framework> ./my-app

Then deploy the manifest with posit-cli if R cannot deploy directly.

Script front matter missing. Add the minimal block at the top of the file. Connect takes the content title from title, so write a descriptive one.

Python:

# %% [markdown]
# ---
# title: "Data processing script"
# ---

R:

#' ---
#' title: "Data processing script"
#' ---

No CLI account for the target. Register it now with a browser login: posit connect login for Python, or rsconnect::addServer() and rsconnect::connectUser() for R. The credentials reference has the details and the pitfalls. Do not fall back to an API key from the environment. If the browser flow is not available, report that and stop.

Dependencies. rsconnect and posit-cli scan the code and snapshot the required package versions for you, so hand-listing them is rarely necessary. Python content needs a requirements.txt. For R, the content's own packages must be installed locally for rsconnect to detect them — plumber for a Plumber API, shiny for a Shiny app. Install any that are missing from the same P3M repo shown above.

---

Stage 6 — Deploy and handle failure

Discover the live command surface (Python)

The frameworks and flags change between releases, and the help text is the source of truth:

posit --version                          # which posit-cli version you are actually running
posit connect deploy --help              # every framework you can deploy
posit connect deploy <framework> --help  # flags for one framework

posit connect version reports the version of the Connect server, not the version of the CLI.

Deploy

For Python, run posit connect deploy <framework> <dir> with the framework Stage 3 picked. The manifest framework takes the manifest file rather than a directory.

Non-obvious flags: -t/--title, -N/--new (force a new deployment instead of updating the recorded one), -a/--app-id <id> (target an existing item explicitly, mutually exclusive with --new), -E NAME=VALUE (set an environment variable, repeatable), --draft (keep serving the previous bundle until published).

For R, call the function Stage 3 selected. Pass appTitle so the content is not named after the directory.

A script deploy sweeps the whole directory. If the directory holds files the script does not need, narrow the selection: name the files in Python (posit connect deploy quarto script.py helper.py data.csv) or pass appFiles in R (rsconnect::deployApp(appFiles = c("_quarto.yml", "script.R"))). A directory with a _quarto.yml is a Quarto project — deploy it whole with posit connect deploy quarto ..

If posit is not found at deploy time

It can be installed but off PATH in this shell. IDE-spawned terminals and active virtualenvs both cause this. Fall back to uv tool run as described in Stage 5, with --from posit-cli.

Pre-flight check (optional)

To confirm that the target is reachable and the credentials work before you deploy:

posit connect details -n myserver

When a deploy fails

Python:

• Auth errors — confirm the target with posit connect list, then re-run posit connect login. Pass -s/-k only when the user told you to use an existing key.
• -n/--name ... cannot be specified in conjunction with ... -s/--server (from ENVIRONMENT) — CONNECT_SERVER is set and you also passed -n. Run unset CONNECT_SERVER and keep -n. The credentials reference explains why that direction. CONNECT_API_KEY can stay.
• The requirements file 'requirements.txt' does not exist — Python content needs one. Create it, point at another file with --requirements-file, or generate it with --force-generate. The last option runs a pip freeze, so it can over-pin.
• Self-signed TLS — use -i/--insecure or -c/--cacert <file>. Set CONNECT_INSECURE or CONNECT_CA_CERTIFICATE to apply it everywhere.
• Rejected flag or unknown framework — re-check posit --version and re-read posit connect deploy <framework> --help. The installed version is usually older than the flag you used.
• A deployed script renders empty or broken — the server lacks Quarto 1.4+, Jupyter (Python scripts), or rmarkdown (R scripts). The deploy itself succeeded, so do not retry it. Report the missing server dependency.

R:

• "No account" or auth errors — run rsconnect::accounts(). If it is empty, re-run rsconnect::addServer(), then connectUser() or connectApiUser(). Make sure that you used a server function and not connectCloudUser().
• Found multiple accounts. Please disambiguate by setting server and/or account — more than one account is linked. Pass account = and server = explicitly to the deploy call. An interactive R session shows a menu instead, which hangs a headless run.
• Wrong deploy function — deployApp() for directories and apps, deployDoc() for a single document, deploySite() for a site.
• Self-signed TLS — pass the CA bundle through the curl options, or add the server with the certificate. For a quick test, set options(rsconnect.check.certificate = FALSE).
• Absolute-path warnings — files with hard-coded absolute paths do not block the deploy, but they are better made relative to the project directory.

---

Credentials reference

How to register a target that Stage 4 found no account for. If an account already matches the target, none of this is needed.

A browser login is the route. The API-key routes below it are there for one case only: the user explicitly tells you to use a key that already exists, in an environment variable or a credential store. Do not go looking for a key on your own, and never ask the user to give you one. An API key does not belong in the conversation.

Python (posit-cli)

1. OAuth login (interactive). The default route. One browser flow per server. Tokens land in the OS keyring, or a local credential store, and refresh automatically.

   posit connect login https://connect.example.com
   posit connect login https://connect.example.com --use-device-code   # headless
   

2. Saved API-key nickname. Only when the user asked for a key route. Save once, select later with -n/--name.

   posit connect add -n myserver -s https://connect.example.com -k <api-key>
   posit connect list                # confirm what is saved
   

   A server can be the default, used when a command passes neither -n nor -s. add sets the default only with --set-default. login sets it unless you pass --no-set-default. posit connect server set-default -n <name> changes it later. CONNECT_SERVER still takes precedence over the default.
3. Environment variables. Only when the user asked you to use them. posit-cli reads them directly, which suits a headless or automated run with no state to manage.

   export CONNECT_SERVER=https://connect.example.com
   export CONNECT_API_KEY=...        # honored across the whole `posit connect` surface
   

4. Ad hoc flags on the deploy command: -s <url> -k <api-key>. Same condition, and read the key from the variable the user named rather than writing it out.

Shared credential flags: -n/--name (saved server), -s/--server (env CONNECT_SERVER), -k/--api-key (env CONNECT_API_KEY), -i/--insecure (env CONNECT_INSECURE, for self-signed TLS), -c/--cacert <file> (env CONNECT_CA_CERTIFICATE).

-n and CONNECT_SERVER cannot both be in play. posit-cli rejects a command that combines a saved-server name (-n/--name) with a server URL, including a URL that came from the environment: -n/--name (from COMMANDLINE) cannot be specified in conjunction with options -s/--server (from ENVIRONMENT).

Only the server conflicts. CONNECT_API_KEY, CONNECT_INSECURE, and CONNECT_CA_CERTIFICATE sit alongside -n without complaint, because the key is not part of the exclusion. -n dogfood with CONNECT_API_KEY exported is a valid command. It is CONNECT_SERVER that has to go.

Choose by what the request names, not by what happens to be exported:

• The request names a saved server ("deploy to dogfood") — use -n dogfood and unset CONNECT_SERVER for that command. Resolving the conflict the other way is worse: CONNECT_SERVER can point somewhere else entirely, so dropping -n to keep it would deploy to a server the user did not ask for.
• The request names no server, the typical headless run — let CONNECT_SERVER and CONNECT_API_KEY supply the target, and deploy with posit connect deploy <framework> <dir>.

CONNECT_SERVER is not secret. Print it if you are unsure which server it points at, and name the server you deployed to in your report.

R (rsconnect)

Register the server under a local nickname, then register your user against it:

library(rsconnect)

# 1. The server (once per server; the name is a local nickname)
rsconnect::addServer(url = "https://connect.example.com", name = "myserver")

# 2a. Interactive — approve in a browser, no key to handle
rsconnect::connectUser(server = "myserver")

# 2b. Or non-interactively (CI), only when the user asked for a key route
rsconnect::connectApiUser(
  server  = "myserver",
  account = "your-username",
  apiKey  = Sys.getenv("CONNECT_API_KEY")
)

connectCloudUser() authenticates against Connect Cloud, a different service, so it does not work for a Connect server. Use connectUser() or connectApiUser() here.

If the login route is not available

Report it and stop. Name the server you tried to register and say which login command failed. Do not search the environment, a .env file, or a credential store for a key to fill the gap, and do not ask the user for a key. The next step is theirs to choose.