From cf51f2ec7c0fcd80867c8f06b7260534a3dbc01f Mon Sep 17 00:00:00 2001 From: Altay Date: Thu, 27 Aug 2026 12:22:24 +0300 Subject: [PATCH] docs: clarify browser-backed CLI authentication --- README.md | 5 ++++- skills/putio-cli/SKILL.md | 7 +++++++ skills/putio-cli/references/auth.md | 15 +++++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ac54f53..9775e04 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ putio auth status --profile devs-fe-auto --output json If auth is missing, start login with: putio auth login --profile devs-fe-auto -Tell the human to open the printed URL, enter the printed code, and complete approval. After auth succeeds, select the named profile with: +Tell the human to open the printed URL. If the shared account is not already signed in, get its credentials from the owning workspace's private credential vault and enter them only in the browser. Enter the printed code and complete approval. Never put account credentials or private vault details in the CLI, prompt, logs, or public documentation. After auth succeeds, select the named profile with: putio auth profiles use devs-fe-auto After that, continue with the requested task instead of stopping after setup. @@ -114,6 +114,9 @@ putio auth profiles use devs-fe-auto The CLI does not accept put.io account credentials. Its login flow delegates authorization to the configured web app (`app.put.io` by default) and stores only the returned OAuth token. +For a shared account, get its credentials from the owning workspace's private credential vault and +enter them only in that browser flow. Keep credential values and private vault topology out of the +CLI, logs, chat, and public documentation. Check the auth source: diff --git a/skills/putio-cli/SKILL.md b/skills/putio-cli/SKILL.md index 6896253..98476d5 100644 --- a/skills/putio-cli/SKILL.md +++ b/skills/putio-cli/SKILL.md @@ -55,6 +55,13 @@ putio auth login --profile devs-fe-auto putio auth profiles use devs-fe-auto ``` +`putio auth login` delegates account authentication to the browser; it never +accepts the account username, password, or one-time code. For a shared account, +get those credentials from the owning workspace's private credential vault and +enter them only in the browser before approving the CLI's device code. Keep +credential values and private vault topology out of commands, logs, chat, and +public documentation. + Use `PUTIO_CLI_PROFILE=devs-fe-auto` when a harness should select that profile without repeating `--profile`. Use `PUTIO_CLI_TOKEN` only when headless token auth is the better fit; it overrides selected and persisted profiles. Manage persisted profiles explicitly: diff --git a/skills/putio-cli/references/auth.md b/skills/putio-cli/references/auth.md index ba579b1..ce1f6cb 100644 --- a/skills/putio-cli/references/auth.md +++ b/skills/putio-cli/references/auth.md @@ -20,6 +20,21 @@ putio auth login --profile devs-fe-auto putio auth profiles use devs-fe-auto ``` +The named-profile login is a browser-backed device-code flow: + +1. Run `putio auth login --profile devs-fe-auto` and keep the process running. +2. Open the printed URL in a browser. +3. If the shared account is not already signed in, get its credentials from + the owning workspace's private credential vault and enter them only in the + browser. +4. Enter and approve the CLI's printed device code. +5. Let the CLI finish storing the returned OAuth token, then select and verify + the profile. + +The CLI never accepts the account username, password, or one-time code. Do not +put credential values, private vault topology, approval codes, or approval URLs +in commands, logs, chat, or public documentation. + For interactive login: ```bash