From 00a3461a99f1817dec33fa42a937af468ac4729b Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 10:55:27 -0500 Subject: [PATCH 1/6] docs: recommend login for Posit Connect --- README.md | 16 +++++++++--- docs/CHANGELOG.md | 2 ++ docs/index.md | 66 ++++++++++++++++++++++++++--------------------- 3 files changed, 50 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 92653ddba..436364dd2 100644 --- a/README.md +++ b/README.md @@ -24,12 +24,10 @@ python -m pip install rsconnect-python ## Usage with Posit Connect -[Get an API key from your Posit Connect server](https://docs.posit.co/connect/user/api-keys/) with at least publisher privileges: - -Store your credentials: +Log in to your Posit Connect server: ```bash -rsconnect add --server https://connect.example.com --api-key --name production +rsconnect login https://connect.example.com --name production ``` Deploy your application: @@ -38,6 +36,16 @@ Deploy your application: rsconnect deploy shiny app.py --title "my shiny app" ``` +Browser login requires Posit Connect 2026.02.0 or later. In Posit Workbench, +remote containers, or other sessions where the browser cannot reach the CLI's +local callback, use `--use-device-code` with Connect 2026.06.0 or later. + +For older servers, or automation that cannot use identity tokens, [get an API +key](https://docs.posit.co/connect/user/api-keys/) and store it with +`rsconnect add --server https://connect.example.com --api-key --name production`. +See the [authentication guide](https://docs.posit.co/rsconnect-python/#managing-server-information) +for identity token requirements and other login options. + [Read more about publisher and admin capabilities on the docs site.](https://docs.posit.co/rsconnect-python) ## Usage with Posit Connect Cloud diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ba1103524..6163c1dce 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +- Getting-started documentation recommends `rsconnect login` for Posit Connect, + with API keys as an alternative. - `rsconnect token` prints the OAuth access token stored by `rsconnect login` for a Posit Connect server, so other tools, such as the Connect SDKs, can make API requests with your login. `--refresh` gets a new token after the server rejects diff --git a/docs/index.md b/docs/index.md index a0024d5b5..30bb37472 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,18 +27,16 @@ pip install git+https://github.com/posit-dev/rsconnect-python.git ### Using the rsconnect CLI -Here's an example command that deploys a Jupyter notebook to Posit Connect. +Log in to Posit Connect, then deploy a Jupyter notebook: ```bash -rsconnect deploy notebook \ - --server https://connect.example.org \ - --api-key my-api-key \ - my-notebook.ipynb +rsconnect login https://connect.example.org --name myserver +rsconnect deploy notebook my-notebook.ipynb ``` > **Note** > The examples here use long command line options, but there are short -> options (`-s`, `-k`, etc.) available also. Run `rsconnect deploy notebook --help` +> options available also. Run `rsconnect deploy notebook --help` > for details. ### Setting up `rsconnect` CLI auto-completion @@ -75,48 +73,56 @@ compinit ### Managing Server Information -The information used by the `rsconnect` command to communicate with a Posit Connect -server can be tedious to repeat on every command. To help, the CLI supports the idea -of saving this information, making it usable by a simple nickname. - -> **Warning** -> One item of information saved is the API key used to authenticate with -> Posit Connect. Although the file where this information is saved is marked as -> accessible by the owner only, it's important to remember that the key is present -> in the file as plain text so care must be taken to prevent any unauthorized access -> to the server information file. +The CLI can save Posit Connect server information under a nickname, so you don't +need to repeat it on every command. #### Remembering Server Information -Use the `add` command to store information about a Posit Connect server: +Use `login` to authenticate and save a server: ```bash -rsconnect add \ - --api-key my-api-key \ - --server https://connect.example.org \ - --name myserver +rsconnect login https://connect.example.org --name myserver ``` -> **Note** -> The `rsconnect` CLI will verify that the serve URL and API key -> are valid. If either is found not to be, no information will be saved. +Browser login requires Posit Connect 2026.02.0 or later. In Posit Workbench, +remote containers, or other sessions where the browser cannot reach the CLI's +local callback, use `--use-device-code`; this requires Connect 2026.06.0 or later. +The `--no-wait` device flow also requires Connect 2026.06.0 or later. -If any of the access information for the server changes, simply rerun the -`add` command with the new information and it will replace the original -information. +For automation, `--identity-token` and `--identity-token-file` require Connect +2026.08.0 or later, or Connect 2026.02.0 or later with identity federation +enabled by an administrator (Early Access). -Once the server's information is saved, you can refer to it by its nickname: +Login sets the server as the default unless `--no-set-default` is supplied. +Later commands can omit `--name`, or select a saved server by nickname: ```bash rsconnect deploy notebook --name myserver my-notebook.ipynb ``` -If there is information for only one server saved, this will work too: +See the [`login`](commands/login.md), [`logout`](commands/logout.md), and +[`token`](commands/token.md) references for more options. + +As an alternative for servers older than Connect 2026.02.0 or automation that +cannot use identity tokens, [create an API key](https://docs.posit.co/connect/user/api-keys/) +and save it with `add`: ```bash -rsconnect deploy notebook my-notebook.ipynb +rsconnect add \ + --server https://connect.example.org \ + --api-key my-api-key \ + --name myserver ``` +You can also pass `--api-key` or set `CONNECT_API_KEY` on individual commands. +The CLI verifies the server URL and API key before saving them. + +> **Warning** +> Saved API keys are stored as plain text in the server information file. +> The file is accessible only by its owner; protect it from unauthorized access. +> See [Stored Information Files](deploying.md#stored-information-files) for +> OAuth token storage. + #### Listing Server Information You can see the list of saved server information with: From 1d04401ab704d3d1bfb94f4580a975ed685ee1f9 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 10:59:48 -0500 Subject: [PATCH 2/6] docs: clarify identity federation requirements --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 30bb37472..54cbd28b1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -90,8 +90,7 @@ local callback, use `--use-device-code`; this requires Connect 2026.06.0 or late The `--no-wait` device flow also requires Connect 2026.06.0 or later. For automation, `--identity-token` and `--identity-token-file` require Connect -2026.08.0 or later, or Connect 2026.02.0 or later with identity federation -enabled by an administrator (Early Access). +2026.08.0 or later, or Connect 2026.02.0 or later with identity federation. Login sets the server as the default unless `--no-set-default` is supplied. Later commands can omit `--name`, or select a saved server by nickname: From 0b7ebea24c0a60a23f3d6895dacd3d596f78eaf6 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 11:00:27 -0500 Subject: [PATCH 3/6] docs: clarify remote login guidance --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 436364dd2..7bb64027b 100644 --- a/README.md +++ b/README.md @@ -36,9 +36,9 @@ Deploy your application: rsconnect deploy shiny app.py --title "my shiny app" ``` -Browser login requires Posit Connect 2026.02.0 or later. In Posit Workbench, -remote containers, or other sessions where the browser cannot reach the CLI's -local callback, use `--use-device-code` with Connect 2026.06.0 or later. +Browser login requires Posit Connect 2026.02.0 or later. In remote containers, +or other sessions where the browser cannot reach the CLI's local callback, use +`--use-device-code` with Connect 2026.06.0 or later. For older servers, or automation that cannot use identity tokens, [get an API key](https://docs.posit.co/connect/user/api-keys/) and store it with From 461b533461bfec80508fe8304e66d1bf33da4940 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 12:57:09 -0500 Subject: [PATCH 4/6] docs: simplify initial login example --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 54cbd28b1..81bcd09f9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ pip install git+https://github.com/posit-dev/rsconnect-python.git Log in to Posit Connect, then deploy a Jupyter notebook: ```bash -rsconnect login https://connect.example.org --name myserver +rsconnect login https://connect.example.org rsconnect deploy notebook my-notebook.ipynb ``` From 3fdc66800c1302a63d4ce00efa3cab8b0ba5517e Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 12:58:19 -0500 Subject: [PATCH 5/6] docs: clarify optional login nickname --- docs/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/index.md b/docs/index.md index 81bcd09f9..224cf696d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -84,6 +84,9 @@ Use `login` to authenticate and save a server: rsconnect login https://connect.example.org --name myserver ``` +The `--name` option is optional; without it, the nickname defaults to the +server's hostname. + Browser login requires Posit Connect 2026.02.0 or later. In Posit Workbench, remote containers, or other sessions where the browser cannot reach the CLI's local callback, use `--use-device-code`; this requires Connect 2026.06.0 or later. From 3e2b998c718395bada0a6e59f804eb078f267c74 Mon Sep 17 00:00:00 2001 From: Taylor Steinberg Date: Thu, 5 Nov 2026 13:03:47 -0500 Subject: [PATCH 6/6] docs: simplify login examples --- README.md | 4 ++-- docs/index.md | 9 +++------ 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 7bb64027b..0f6b4786b 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ python -m pip install rsconnect-python Log in to your Posit Connect server: ```bash -rsconnect login https://connect.example.com --name production +rsconnect login https://connect.example.com ``` Deploy your application: @@ -42,7 +42,7 @@ or other sessions where the browser cannot reach the CLI's local callback, use For older servers, or automation that cannot use identity tokens, [get an API key](https://docs.posit.co/connect/user/api-keys/) and store it with -`rsconnect add --server https://connect.example.com --api-key --name production`. +`rsconnect add`. See the [authentication guide](https://docs.posit.co/rsconnect-python/#managing-server-information) for identity token requirements and other login options. diff --git a/docs/index.md b/docs/index.md index 224cf696d..4c57e984a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -81,12 +81,9 @@ need to repeat it on every command. Use `login` to authenticate and save a server: ```bash -rsconnect login https://connect.example.org --name myserver +rsconnect login https://connect.example.org ``` -The `--name` option is optional; without it, the nickname defaults to the -server's hostname. - Browser login requires Posit Connect 2026.02.0 or later. In Posit Workbench, remote containers, or other sessions where the browser cannot reach the CLI's local callback, use `--use-device-code`; this requires Connect 2026.06.0 or later. @@ -96,10 +93,10 @@ For automation, `--identity-token` and `--identity-token-file` require Connect 2026.08.0 or later, or Connect 2026.02.0 or later with identity federation. Login sets the server as the default unless `--no-set-default` is supplied. -Later commands can omit `--name`, or select a saved server by nickname: +Later commands can use that default: ```bash -rsconnect deploy notebook --name myserver my-notebook.ipynb +rsconnect deploy notebook my-notebook.ipynb ``` See the [`login`](commands/login.md), [`logout`](commands/logout.md), and