Repository navigation
Description
Summary
Read deployment config from a [tool.posit.connect] table in pyproject.toml, and keep [tool.rsconnect] working as a legacy name.
deploy pyproject, write-manifest pyproject, and quickstart use [tool.rsconnect] today. Users increasingly deploy through posit-cli (posit connect ...), so a table named after the old CLI doesn't match the tool they run. [tool.posit.connect] names the product being deployed to rather than a particular CLI, and leaves [tool.posit] open for other Posit tools. posit-dev/connect#48550 will recommend this table in the Connect docs, so the name should be settled first.
Where this lives
posit-cli doesn't parse pyproject.toml. Its posit connect group re-registers rsconnect's Click commands unchanged (posit_cli/connect/__init__.py), so posit connect deploy pyproject runs rsconnect/pyproject.py. The change belongs here. As a result, rsconnect deploy pyproject will read [tool.posit.connect] too, so a project works the same with either CLI.
Behavior
- Accept
[tool.posit.connect]with the same fields as[tool.rsconnect]:app_mode,entrypoint,title,requirements_file. [tool.posit.connect]is a nested table. Other keys or sub-tables under[tool.posit]are ignored, and[tool.posit]without aconnectsub-table counts as absent. Iftool.positortool.posit.connectexists but isn't a table, fail with the same not-a-table error used for[tool.rsconnect].- Keep reading
[tool.rsconnect]when[tool.posit.connect]is absent, and log a deprecation warning (logger.warning, like the--override-python-versiondeprecation) telling the user to rename the table to[tool.posit.connect]. - If both tables are present, fail with an
RSConnectExceptionnaming both tables and telling the user to keep one. Merging the two would hide which values apply. Check this before validating either table's fields. - The
-rflag still overridesrequirements_filein either table. quickstarttemplates write[tool.posit.connect].- Error messages and the minimum-config snippet in
rsconnect/pyproject.pyname[tool.posit.connect]. When neither table exists, the missing-section error also says[tool.rsconnect]is still accepted. - Errors about a table's contents (missing or invalid
app_mode/entrypoint, unsupportedapp_mode) name the table that was actually read.PyprojectDeployTargetrecords which table that was, so theUnsupported app_mode '…' in [tool.…]messages inmain.pydon't hardcode[tool.rsconnect].
Files
rsconnect/pyproject.py:read_tool_rsconnect,resolve_pyproject_deploy_target, and the error types and snippet.rsconnect/main.py: help text fordeploy pyproject,write-manifest pyproject, andquickstart, plus theUnsupported app_modeerrors indeploy pyprojectandwrite-manifest pyproject.rsconnect/quickstart/templates/*/pyproject.toml.tmpl, and the template-registry comment inrsconnect/quickstart/quickstart.pydocs/deploying.md,docs/CHANGELOG.md- Tests:
tests/test_deploy_pyproject.py,tests/test_write_manifest_pyproject.py,tests/test_quickstart.py,tests/test_connect_cloud.py
Acceptance criteria
-
deploy pyprojectandwrite-manifest pyprojectproduce the same result from[tool.posit.connect]as from the same fields in[tool.rsconnect]. - Projects that only have
[tool.rsconnect]keep working, and log a deprecation warning that names[tool.posit.connect]as the replacement. - Having both tables fails with a clear error, even when one of them is incomplete.
- Errors about a table's contents name the table that was read.
- With neither table, the error shows a
[tool.posit.connect]snippet and mentions that[tool.rsconnect]is still accepted. -
quickstartwrites[tool.posit.connect], and the generated project deploys. - Docs and the changelog describe the new name and the legacy one.
Follow-up
After this is released, posit-cli should raise its rsconnect-python>=1.33 minimum to the release that includes it, and update its docs to show [tool.posit.connect].
Out of scope
- The
rsconnect quickstart --helphint appended to config errors is wrong for posit-cli users. Track that separately.
Decided
- The table is
[tool.posit.connect]. We considered[tool.posit-cli], which ties the config to one CLI, and a bare[tool.posit], which would claim the whole Posit namespace for Connect deploy settings. [tool.rsconnect]logs a deprecation warning starting with this change. When to remove it can follow the rsconnect-python CLI deprecation (posit-dev/connect#46116).
Activity
[-]feat: read deploy config from [tool.posit-connect] in pyproject.toml[/-][+]feat: read deploy config from [tool.posit-cli] in pyproject.toml[/+]tdstein commentedon Nov 12, 2026
Agent Brief
Category: enhancement
Summary: Read pyproject deployment config from
[tool.posit.connect], keeping[tool.rsconnect]as a legacy name.Current behavior:
deploy pyprojectandwrite-manifest pyprojectread deployment config only from[tool.rsconnect]. Both commands go through one reader (read_tool_rsconnect, called byresolve_pyproject_deploy_target). A project with only[tool.posit.connect]fails with "The [tool.rsconnect] section is missing" (reproduced withrsconnect write-manifest pyproject).quickstarttemplates write[tool.rsconnect]. TheUnsupported app_mode '…' in [tool.rsconnect]message is hardcoded in the resolver and again in both CLI commands.Desired behavior:
[tool.posit.connect]accepts the same fields as[tool.rsconnect]:app_mode,entrypoint,title,requirements_file. Both tables resolve to identical deploy targets.[tool.posit.connect]is a nested table: ignore other keys or sub-tables under[tool.posit], and treat[tool.posit]without aconnectsub-table as absent. Iftool.positortool.posit.connectexists but isn't a TOML table, raiseInvalidPyprojectConfigErrornaming the offending key.[tool.rsconnect]is used only when[tool.posit.connect]is absent. When it is used, log a deprecation warning withlogger.warning(the same mechanism as the existing--override-python-versiondeprecation, not Python'swarnings.warn) telling the user to rename[tool.rsconnect]to[tool.posit.connect]. Log it once per command run, and only after the table has been read successfully, so an invalid config shows only the error.-rflag still overridesrequirements_filefrom whichever table was read.app_mode/entrypoint, unsupportedapp_mode) name the table that was actually read.[tool.posit.connect]and says[tool.rsconnect]is still accepted.quickstarttemplates write[tool.posit.connect], and the help text fordeploy pyproject,write-manifest pyproject, andquickstartnames[tool.posit.connect].docs/deploying.mdand the changelog describe[tool.posit.connect], with[tool.rsconnect]as the legacy name.Key interfaces:
PyprojectDeployTargetrecords which table it was read from (e.g. the table name), so callers can quote it in errors instead of hardcoding[tool.rsconnect].read_tool_rsconnectis fine; update its tests to match.InvalidPyprojectConfigErrorandUnsupportedAppModeErrorstay separate types. The CLI appends the quickstart hint only for the former.Acceptance criteria:
deploy pyprojectandwrite-manifest pyprojectproduce the same result from[tool.posit.connect]as from the same fields in[tool.rsconnect](parametrize the existing tests over both table names).[tool.rsconnect]keep working and produce the same result, plus a single deprecation warning that names[tool.posit.connect]as the replacement.[tool.posit.connect]log no deprecation warning.[tool.posit]with other keys but noconnectsub-table falls back to[tool.rsconnect](or the missing-section error);tool.posit = "x"andtool.posit.connect = "x"raise the not-a-table error.[tool.posit.connect]and[tool.rsconnect], including when one of them is incomplete.[tool.posit.connect]snippet and mentions that[tool.rsconnect]is still accepted.-roverridesrequirements_filein either table.quickstartoutput has[tool.posit.connect]and no[tool.rsconnect], and the generated project passeswrite-manifest pyproject.just lintandjust testpass.Out of scope:
[tool.rsconnect]support (may follow the rsconnect-python CLI deprecation, posit-dev/connect#46116).rsconnect quickstart --helphint appended to config errors.[-]feat: read deploy config from [tool.posit-cli] in pyproject.toml[/-][+]feat: read deploy config from [tool.posit.connect] in pyproject.toml[/+]