From 910bb397e14862d0e0330b5ddbb2c93abdfff8d9 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Fri, 12 Jun 2026 14:02:00 +0000
Subject: [PATCH] docs: document v2 CLI login default and token overrides

---
 .../cli/command-reference/porter-auth.mdx     | 13 +++++++++-
 .../cli/command-reference/porter-auth.mdx     | 24 ++++++++++++++++++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/enterprise/cli/command-reference/porter-auth.mdx b/enterprise/cli/command-reference/porter-auth.mdx
index 7c48b9f..e21af62 100644
--- a/enterprise/cli/command-reference/porter-auth.mdx
+++ b/enterprise/cli/command-reference/porter-auth.mdx
@@ -16,6 +16,17 @@ porter auth login --manual
 
 ```
 
+#### Default login method (v2)
+
+New CLI installs default to the **v2** login method, which uses a refreshable session and stores credentials in your operating system's keyring instead of `~/.porter/porter.yaml`. Sessions refresh automatically while you use the CLI.
+
+- Existing configs are upgraded to v2 automatically on the next CLI run; any legacy plaintext token in `porter.yaml` is cleared and replaced by a session stored in the keyring.
+- To keep the legacy JWT-based flow on older self-hosted instances, set `login_method: v1` in `~/.porter/porter.yaml`.
+
+#### Token overrides
+
+The `--token` flag and the `PORTER_TOKEN` environment variable still take precedence over the v2 default and are the recommended way to authenticate from CI/CD pipelines. If `PORTER_TOKEN` is set but rejected by the server, the CLI prompts you to `unset PORTER_TOKEN` before retrying.
+
 ### `porter auth logout`[](#porter-auth-logout "Direct link to heading")
 
-Logs a user out from a Porter instance.
\ No newline at end of file
+Logs a user out from a Porter instance. For v2 sessions, this also clears the session stored in your OS keyring.
diff --git a/standard/cli/command-reference/porter-auth.mdx b/standard/cli/command-reference/porter-auth.mdx
index 97f12f8..da52633 100644
--- a/standard/cli/command-reference/porter-auth.mdx
+++ b/standard/cli/command-reference/porter-auth.mdx
@@ -36,11 +36,33 @@ porter auth login --token <YOUR_TOKEN>
 After logging in, Porter automatically sets your default project and cluster if you have access to any. You can view these with `porter config`.
 </Info>
 
+### Default login method (v2)
+
+New CLI installs default to the **v2** login method, which uses a refreshable session and stores credentials in your operating system's keyring instead of `~/.porter/porter.yaml`. Sessions refresh automatically while you use the CLI, so you no longer need to re-run `porter auth login` as often.
+
+- **First-time users**: no action required — `porter auth login` uses v2 automatically.
+- **Existing users upgrading**: your config is migrated to v2 on the next CLI run. Any legacy plaintext token in `porter.yaml` is cleared and replaced by a session stored in the keyring.
+- **Legacy hosts**: set `login_method: v1` in `~/.porter/porter.yaml` to keep the previous JWT-based flow.
+
+### Token and environment overrides
+
+Explicit token authentication still takes precedence over the v2 default — useful for CI/CD pipelines and service accounts:
+
+- The `--token` flag on any command
+- The `PORTER_TOKEN` environment variable
+
+When either is set, the CLI uses that token directly and skips the browser-based session flow. If `PORTER_TOKEN` is set but the server rejects it, the CLI tells you to `unset PORTER_TOKEN` before retrying.
+
+```bash CI/CD example
+export PORTER_TOKEN="$PORTER_DEPLOY_TOKEN"
+porter apply -f porter.yaml
+```
+
 ---
 
 ## `porter auth logout`
 
-Log out from Porter and clear your local credentials.
+Log out from Porter and clear your local credentials. For v2 sessions, this also clears the session stored in your OS keyring.
 
 **Usage:**
 ```bash