docs: refine console login logout guide

Author: yuguo.dtpe

README.EN.MD

@@ -240,35 +240,28 @@ Logout behavior:
 #### Console Login (login)
 
 ```shell
-ve login --profile [profile name]
-# Specify a region to avoid the interactive prompt
-ve login --profile [profile name] --region cn-beijing
-# or cross-device login
-ve login --profile [profile name] --region cn-beijing --remote
-```
+# Sign in with the default profile. If region is omitted, the CLI prompts for it
+ve login
 
-This command signs in through the Volcengine Console using OAuth 2.0 + PKCE and caches temporary STS credentials locally for subsequent CLI calls. Parameters:
+# Recommended: specify profile and region; profile/region support -p/-r
+ve login -p dev -r cn-beijing
 
-```shell
-profile: configuration profile name; optional; defaults to default
-region: optional; when omitted, the CLI prompts for it and defaults to cn-beijing when you press Enter
-remote: enables cross-device login mode; when set, the CLI prints a login URL and prompts for the authorization code shown in the browser
-endpoint-url: optional; overrides the sign-in service endpoint; defaults to https://signin.volcengine.com
+# Use cross-device login for headless, remote-server, or container environments
+ve login -p dev -r cn-beijing --remote
 ```
 
-Login behavior:
-- The default mode is local login: the CLI starts a local callback server, prints an authorization URL, tries to open your browser automatically, and waits for the browser redirect after authentication. If the browser does not open, visit the URL printed in the terminal manually
-- If `--region` is omitted, the CLI prompts with `Please enter region [cn-beijing]: `. Press Enter to use `cn-beijing`; for scripts and automation, pass `--region` explicitly
-- With `--remote`, the CLI uses cross-device login: this is suitable for headless environments or machines that cannot open a browser locally. The CLI prints a login URL, you complete authentication on any device, and then paste the complete base64 authorization code shown in the browser back into the terminal
-- After a successful login, the CLI stores the profile with `mode` set to `console-login` and records the `login-session`; token cache files are stored under `~/.volcengine/login/cache/`
-- You can override the login cache directory with the `VOLCENGINE_LOGIN_CACHE_DIRECTORY` environment variable, which is useful for multi-user machines or CI isolation
-- If the target profile already exists, the command reuses and overwrites that profile, updating its `mode` to `console-login`
-- If the profile is already bound to a different `login-session`, the CLI prompts before replacing it
-
-Usage notes:
-- This is useful when you want temporary credentials obtained from your console identity without manually preparing AK/SK
-- If the local session expires and a refresh token is available in cache, the CLI will try to refresh it automatically; if refresh fails, run `ve login` again
-- To isolate different console identities, use separate `--profile` values
+This command signs in through the Volcengine Console using OAuth 2.0 + PKCE, caches temporary STS credentials locally, and lets later service commands reuse the temporary credentials from that profile.
+
+Parameters:
+- `--profile, -p`: configuration profile name; defaults to `default`
+- `--region, -r`: region; when omitted, the CLI prompts for it and uses `cn-beijing` if you press Enter
+- `--remote`: cross-device login; open the URL printed by the CLI in a browser, finish login, and paste the full authorization code shown in the browser back into the terminal
+- `--endpoint-url`: sign-in service endpoint; defaults to `https://signin.volcengine.com` and normally does not need to be changed
+
+Notes:
+- After login, the profile is written with `mode` set to `console-login` and a `login-session`
+- After logging in with a non-`default` profile, service commands do not automatically switch profiles; run `ve configure profile --profile dev` first
+- Use `--remote` when the browser cannot redirect back to the machine running the CLI
 
 End-to-end example:
 
@@ -286,38 +279,29 @@ ve ecs DescribeInstances
 ve logout --profile dev
 ```
 
-Notes:
-- On the first login, if `current` is empty in the configuration file, the CLI sets the logged-in profile as the current default profile automatically. If another current profile already exists, switch manually with `ve configure profile --profile [profile name]`
-- When subsequent service commands use this profile, the CLI reads temporary STS credentials from the local cache. If the credentials are close to expiration and a refresh token exists, the CLI refreshes them automatically
-- `ve logout` only clears the local cache and the `login-session` in the configuration; it does not delete the whole profile
-
 #### Console Logout (logout)
 
 ```shell
-ve logout --profile [profile name]
-# or clear all login credentials
+# Log out the default profile
+ve logout
+
+# Log out a specific profile
+ve logout -p dev
+
+# Log out all Console Login profiles in the current configuration
 ve logout --all
 ```
 
-This command logs out of a console login session established via `ve login` and removes the locally cached temporary STS credentials. This is a purely local operation — no network requests are made to any server. Parameters:
+This command clears the local login state created by `ve login`. It removes locally cached credentials and clears the profile's `login-session`; it does not delete the profile or send a logout request to the server.
 
-```shell
-profile: configuration profile name; optional; defaults to default
-all: remove cached login credentials for all console-login profiles; when set, --profile is ignored
-```
+Parameters:
+- `--profile, -p`: configuration profile name; defaults to `default`
+- `--all`: clear all `console-login` profiles in the current configuration; ignores `--profile`
 
-Logout behavior:
-- The default mode logs out a single profile: the CLI locates and removes the cached token file under `~/.volcengine/login/cache/` based on the `login-session` recorded in the profile, and clears the `login-session` field in the configuration
-- With `--all`, the CLI iterates all profiles in the configuration, identifies those using `console-login` mode with an active `login-session`, removes the corresponding cache file for each via SHA-1 lookup, and clears the `login-session` field. Failure to clean one profile does not affect the others
-- Only profiles using `console-login` mode can be logged out with this command; the command returns an error for AK or SSO profiles
-- If the profile does not have an active login session (`login-session` is empty), the command prints a message and exits normally
-- `ve logout` is a purely local cleanup operation and does not send a logout request to the server. After logout, credentials that have already been loaded by other tools may remain valid until they expire (typically within 15 minutes)
-- Logout only clears the local token cache and the profile's `login-session`; it does not delete the whole profile or clear other fields such as `region`
-
-Usage notes:
-- On shared devices, it is recommended to run `ve logout` after you finish using the CLI
-- To thoroughly clean all login caches (e.g., for troubleshooting or device handover), use `ve logout --all`
-- After logout, run `ve login` to re-establish a login session when needed
+Notes:
+- `ve logout` without `--profile` only handles the `default` profile; it does not automatically log out `current`
+- This command only applies to `console-login` profiles; AK/SSO profiles are not affected
+- Run `ve login` again when you need to use Console Login credentials after logout
 
 #### Configure Auto-Completion
 

README.MD

@@ -246,35 +246,28 @@ sso-session: 指定要退出的 SSO 会话名称
 #### Console 登录 (login)
 
 ```shell
-ve login --profile [配置名]
-# 指定地域，避免交互输入
-ve login --profile [配置名] --region cn-beijing
-# 或跨设备登录
-ve login --profile [配置名] --region cn-beijing --remote
-```
+# 使用默认 profile 登录，未指定 region 时会提示输入
+ve login
 
-该命令用于通过火山引擎控制台完成 OAuth 2.0 + PKCE 登录，并将临时 STS 凭证缓存到本地，后续调用接口时可直接复用。支持参数及说明：
+# 推荐：指定 profile 和地域，profile/region 支持 -p/-r 简写
+ve login -p dev -r cn-beijing
 
-```shell
-profile: 配置名称，可选，默认为 default
-region: 地域，可选；未指定时会提示输入，直接回车默认使用 cn-beijing
-remote: 是否启用跨设备登录模式；开启后会输出登录链接，并要求手动输入浏览器中展示的授权码
-endpoint-url: 可选；登录服务地址覆盖项，默认值为 https://signin.volcengine.com
+# 无浏览器、远程服务器或容器环境使用跨设备登录
+ve login -p dev -r cn-beijing --remote
 ```
 
-登录行为说明：
-- 默认模式为本机登录：CLI 会启动本地回调服务，打印授权 URL，尝试自动打开浏览器，并等待浏览器完成登录后回跳；如果浏览器没有自动打开，请手动访问终端输出的 URL
-- 未指定 `--region` 时，CLI 会提示 `Please enter region [cn-beijing]: `；直接回车使用 `cn-beijing`，脚本或自动化场景建议显式传入 `--region`
-- 指定 `--remote` 后为跨设备登录：适用于无图形界面或无法本地打开浏览器的环境，CLI 会打印登录 URL，用户可在任意设备完成登录，再将浏览器展示的 base64 授权码完整粘贴回终端
-- 登录成功后，会将 `mode` 写为 `console-login`，并在 profile 中记录 `login-session`；对应的令牌缓存保存在 `~/.volcengine/login/cache/`
-- 可通过环境变量 `VOLCENGINE_LOGIN_CACHE_DIRECTORY` 覆盖登录缓存目录，适用于多用户机器或 CI 隔离场景
-- 若 profile 已存在，命令会直接复用并覆盖该 profile，并将其更新为 `console-login` 模式
-- 若 profile 已绑定其他 `login-session`，CLI 会提示是否替换，只有确认后才会覆盖
-
-使用建议：
-- 适合需要通过控制台身份快速换取临时凭证的场景，无需手动准备 AK/SK
-- 若本地会话过期且缓存中存在 refresh token，CLI 会自动尝试刷新；若刷新失败，则需要重新执行 `ve login`
-- 如需隔离不同身份，建议为不同控制台账号使用不同的 `--profile`
+该命令通过火山引擎控制台完成 OAuth 2.0 + PKCE 登录，并将临时 STS 凭证缓存到本地，后续业务命令可复用该 profile 的临时凭证。
+
+参数说明：
+- `--profile, -p`：配置名称，默认 `default`
+- `--region, -r`：地域；未指定时会提示输入，直接回车使用 `cn-beijing`
+- `--remote`：跨设备登录；按终端输出的 URL 在浏览器完成登录，并将浏览器展示的授权码完整粘贴回终端
+- `--endpoint-url`：登录服务地址，默认 `https://signin.volcengine.com`，通常无需修改
+
+注意事项：
+- 登录成功后，profile 会被写为 `console-login` 模式，并记录 `login-session`
+- 使用非 `default` profile 登录后，业务命令不会自动切换 profile；需要先执行 `ve configure profile --profile dev`
+- 本机浏览器无法回跳 CLI 所在机器时，使用 `--remote`
 
 完整使用流程示例：
 
@@ -292,38 +285,29 @@ ve ecs DescribeInstances
 ve logout --profile dev
 ```
 
-说明：
-- 首次登录且配置文件中的 `current` 为空时，CLI 会自动将登录的 profile 设置为当前默认 profile；如果已经存在其他当前默认 profile，请使用 `ve configure profile --profile [配置名]` 手动切换
-- 后续业务命令使用该 profile 时，CLI 会从本地缓存读取临时 STS 凭证；凭证接近过期且缓存中存在 refresh token 时会自动刷新
-- `ve logout` 仅清理本地缓存和配置中的 `login-session`，不会删除整个 profile
-
 #### Console 登出 (logout)
 
 ```shell
-ve logout --profile [配置名]
-# 或清除所有登录凭证
+# 登出 default profile
+ve logout
+
+# 登出指定 profile
+ve logout -p dev
+
+# 登出当前配置中的所有 Console Login profile
 ve logout --all
 ```
 
-该命令用于退出通过 `ve login` 建立的控制台登录会话，清除本地缓存的临时 STS 凭证。这是一个纯本地操作，不会发起任何网络请求。支持参数及说明：
+该命令用于清理 `ve login` 建立的本地登录状态。它只删除本地缓存凭证并清除 profile 中的 `login-session`，不会删除 profile，也不会向服务端发起请求。
 
-```shell
-profile: 配置名称，可选，默认为 default
-all: 是否清除所有 console-login 类型 profile 的登录凭证缓存；开启后忽略 --profile 参数
-```
+参数说明：
+- `--profile, -p`：配置名称，默认 `default`
+- `--all`：清理当前配置中的所有 `console-login` profile；开启后忽略 `--profile`
 
-登出行为说明：
-- 默认模式为单 profile 登出：CLI 会根据 profile 中记录的 `login-session` 定位并删除 `~/.volcengine/login/cache/` 下对应的缓存文件，同时清除配置中的 `login-session` 字段
-- 指定 `--all` 后为批量登出：CLI 遍历配置文件中的所有 Profile，筛选出 `console-login` 模式且 `login-session` 非空的条目，逐个通过 SHA-1 定位并删除对应的缓存文件，同时清除配置中的 `login-session` 字段。单个 Profile 清理失败不影响其余 Profile 的处理
-- 仅 `console-login` 模式的 profile 允许执行登出操作；若 profile 使用的是 AK 或 SSO 模式，命令会返回错误
-- 若 profile 不存在活跃的登录会话（`login-session` 为空），命令会提示无操作并正常退出
-- `ve logout` 是纯本地清理操作，不会向服务端发起登出请求；登出后，已被其他工具加载的临时凭证可能在过期前（通常 15 分钟内）仍然有效
-- 登出只会清除本地 token 缓存和 profile 中的 `login-session`，不会删除整个 profile，也不会清除该 profile 的 `region` 等其他配置
-
-使用建议：
-- 在共享设备上使用完毕后，建议执行 `ve logout` 清除本地凭证
-- 若需彻底清理所有登录缓存（如排查问题或设备交接），使用 `ve logout --all`
-- 登出后若需重新使用，执行 `ve login` 即可重新建立登录会话
+注意事项：
+- `ve logout` 不带 `--profile` 时只处理 `default` profile，不会自动按 `current` 登出
+- 只有 `console-login` profile 可使用该命令；AK/SSO profile 不适用
+- 登出后若需继续使用，重新执行 `ve login`
 
 #### 配置自动补全
 

cmd/cmd_consolelogin.go

@@ -53,8 +53,8 @@ from the CLI configuration.
 
 Modes:
   - Default: Logs out the specified profile (or "default" if not specified)
-  - --all:   Scans the cache directory and removes all cached login credentials`,
-		Example: `  # Log out current/default profile
+  - --all:   Logs out all configured console-login profiles with active sessions`,
+		Example: `  # Log out the default profile
   ve logout
 
   # Log out a specific profile