diff --git a/README.md b/README.md index 92653ddb..0f6b4786 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 ``` 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 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`. +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 26a00bd8..ed23eab0 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 a0024d5b..4c57e984 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 +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,55 @@ 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 ``` -> **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. -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 use that default: ```bash -rsconnect deploy notebook --name myserver my-notebook.ipynb +rsconnect deploy notebook 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: