CRITICAL — before starting, MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, configuration troubleshooting, and shared security rules
CRITICAL — when the user's goal is another business command, you must first determine whether it is blocked by authentication, then decide whether to enter this skill.
CRITICAL — auth is an identity/TTY workflow, and --dry-runis not registered globally; do not generate that flag.
⚠️ 0.1.16 change overview (required reading):
- SSO login introduces Gate 1+2: after the browser flow, compare the SSO trn with
is_default profile.OwnerTrn, and the 4 cases respectively go throughBuildFirstProfile(create new) /GUIDE_SKIP(reuse) / prompt to switch default / prompt to create new. Seedocs/runtime/volc-sso.md。 - AK/SK login channel temporarily closed:
auth login --access-key / --secret-keyis commented out, and promptui also removes the "AK/SK" option; SSO (Volcengine) +arkcli auth login --no-browser(root command flag, not a volc-sso subcommand flag) is the only login entry point. - auth status / auth whoami output adds profile facet fields:
active_profile.{name,type,region,project,owner_trn}andprofiles_summary[...]; top-levelauth_method/logged_in/volc_sso/ark_api_keyand other old fields are all retained (backward compatible). - Profile management migrated to
arkcli profile:config init/list/show/switch/deleteis deprecated, see../arkcli-config/SKILL.md。 - 0.1.17 first-login dynamic project selection:
BuildFirstProfile's project step is changed to interactively select from the real active project list under the current identity pulled via IAMListProjects(on pull failure/no permission, fall back to the fallbackdefault, without blocking login). After login, to change project you don't need to log in again:arkcli profile project [<name>](pull the same list and reselect, re-derive the platform profile to the new project, keep the personal-edition plan profile), see../arkcli-profile/SKILL.md。 - Since 1.0.4,
arkcli auth logininteractive browser SSO branch supports borrowing the local volcengine-cli login state: whenve >= 1.0.45is detected and alreadyve login, directly take over STS and write an arkcli identity (identity_store/<key>/metadata.json.source="ve", without writing IDToken/refresh_token/ClientID; STS is automatically refreshed by volcengine-go-sdk internally holding refresh_token). From the user's perspective: one fewer browser authorization; from the agent's perspective:auth_methodbecomes"sts"instead of"sso", butlogged_in=true. Detection failure / ve not logged in → automatically fall back to arkcli's native SSO OAuth flow. Seereferences/arkcli-auth-login.md's "volcengine-cli login state borrowing" section.
Applicable scenarios
- First login
arkcli - Switch to Volc SSO
- After login, re-obtain or switch the ARK API Key
- View current credential status
- Answer "who am I / what is my IAM ID / which account do I belong to" — use
arkcli auth whoami - Clear local login state
- Other business skills are blocked due to not being logged in, expired credentials, or identity mismatch
- Cloud dev machine / CI has already injected
VOLC_INIT_*credentials, non-interactive bootstrap — usearkcli init-volc(not SSO)
Non-interactive bootstrap (init-volc)
Cloud dev machine / CI, etc.have already injected Volcengine credentials as VOLC_INIT_* environment variablesscenarios, use arkcli init-volc Land a Volcano platform profile and set it as default with a single command and zero interaction, so that subsequent arkcli / OpenCode calls work out of the box (the data plane uses an API Key, the control plane uses STS).
- Trigger words: "cloud dev machine bootstrap / non-interactive initialization / VOLC_INIT already injected, how to make arkcli ready / skip SSO in CI"
- Difference from
auth login:init-volcno login, no interaction, no network access, it purely consumes environment variables; first-time bootstrap for local terminal users still goes throughauth login(SSO) - For detailed environment variable contract, landing behavior, and output, see
references/arkcli-auth-init-volc.md
Agent quick execution order
- Before starting business commands, if you are unsure of the authentication status, first run
arkcli auth status - When you need to identify the current user's identity ("created by me / my xxx" semantics), use
arkcli auth whoami, do not go into~/.arkcli/.envto manually decode the JWT - When not logged in or credentials have expired, for Volcano Ark scenarios directly execute via Bash
arkcli auth login volc-sso(do not just "prompt the user to go run it"). SSO is the only available login channel in 0.1.16, covering the control plane BFF + the vast majority of data plane capabilities- Before execution, inform the user in one sentence: "Detected that you are not logged in; I will now start SSO login for you, please complete authorization in the pop-up browser"
- The Bash call must set
timeout=600000(10 minutes) - Startup failure (browser not installed,
openfailure, port occupied, timeout, etc.) → do not retry in place, paste the stderr back to the user and ask the user to manually run the login command for the corresponding tenant in the terminal (Volcano:arkcli auth login volc-sso) - After the command succeeds, immediately return to the user's original task, do not stop at the auth result
- For agent / sandbox / CI without browser login, use the two-phase
--no-browser(the AK/SK channel is temporarily closed in 0.1.16; when AK/SK is mentioned, inform and guide them here): the agent terminal is usually non-TTY,--no-browseris nowtwo-phase, no longer blocks reading stdin (the old version always reported in the sandbox读取授权码失败: EOF—— the process was interrupted by EOF before obtaining the authorization code):- Phase 1: run
arkcli auth login --no-browser. It prints the authorization URL and outputs in JSON{"stage":"authorize_pending","authorize_url":"...","next_command":"..."}thenexits immediately(does not wait idly). Forwardauthorize_urlas-is to the user, and ask them to complete SSO in a browser onany device, copy the base64 authorization codedisplayed on the page and bring it back. - Phase 2: after obtaining the authorization code, run
arkcli auth login --no-browser --code <授权码>to complete login (reads the PKCE/state persisted by Phase 1 to exchange for a token).--codemust be connected to--no-browser(writing it separately will report--code 仅在 --no-browser 模式下有效)。 - the two phases must be in the same runtime environment: Phase 1 persists to disk
~/.arkcli/.sso-pending.json, Phase 2 reads it to continue;the two commands must share the sameHOME/ the same persistent volume(the same container / dev machine); dispatching across containers or across HOME will cause Phase 2 to report "no pending ... session". During this period, do not touch~/.arkcli/。 - flag position:
--no-browser/--codeare all attached to theauth loginroot command, not to thevolc-ssosubcommand;auth login volc-sso --no-browserwill reportunknown flag。 - error recovery:
会话过期(TTL 10min)/没有待完成的会话→ rerun Phase 1(ensure the same HOME);base64 解码失败/state 不匹配(CSRF)/ token exchange fails momentarily → pending is still on disk,after correcting within the TTL, directly retry Phase 2(paste the code for the current authorize_url, and if necessary re-authorize from the same URL to get a new code),no need torerun Phase 1. - In a real terminal (TTY),
arkcli auth login --no-browseris still a single interactive command (prints the URL and then you paste on the spot), behavior unchanged.
- Phase 1: run
- When the user explicitly asks to choose a login method, since the stdin interactive agent cannot choose for the user, have the user run it themselves
arkcli auth login - Only when the user explicitly asks to clean up local credentials, execute
arkcli auth logout
Core rules
auth statusis the default entry point; do not start withlogin- After a successful login, you should return to the user's original goal and continue executing, rather than stopping at the auth result itself
auth logoutis a destructive operation and must be explicitly requested by the userauth statusmasks sensitive fields, can be used directly for troubleshooting, and will show the currently effectiveproject_nameauth loginoutputs on successauth_method; the credential storage location is an implementation detail and the path is no longer echoed- SSO login (
arkcli auth login volc-sso) andauth apikeyboth write to the credential store after an API Key is selected; 0.1.16 final clean-slate model: the entire arkcli has only one active identity at a time, and when a new SSO is inconsistent with the old sub, all profiles are cleared (including cross-tenant) and rebuilt - API Keys must be understood as separate pools by profile type:
platform/coding-planPersonal Edition uses a regular API Key;agent-planPersonal Edition uses theScene=RealAgentPlanPersonaldedicated Key;agent-plan-team/coding-plan-teamuses theGetSeatInfoseat Key returned. Having a Key in the regular pool does not prove that an Agent Plan/Team Edition Key is usable. - On first TTY login, when the regular pool is found to be empty, it will first ask whether to create one; after confirmation it calls
CreateApiKeyonly once, then reads the status at most 3 times. When an Agent Plan dedicated record exists but is not Active, it will ask whether to rotate; after confirmation it also rotates only once and reads the status at most 3 times. On non-TTY, if the user refuses, or if there is no dedicated record, it never writes. - During first TTY login, if the profile type selected by the user errors during the API Key acquisition stage (for example, after Agent Plan rotation the check is still
Restrictedafter 3 times), the CLI will keep the selected region/project, remove that failed type from this round's candidates, and ask the user again to choose another consumption scenario. The failed type will not be silently backfilled again, avoiding repeated acquisition or a second rotation; this is a profile-level reselection and will never pass off a regular/Coding Plan Key as an Agent Plan dedicated Key. - v3 ve handoff branch (since 1.0.4, only for Volcano SSO interactive login): when it detects that this machine has
volcengine-cli >= 1.0.45installed and alreadyve login,arkcli auth loginwill first try to borrow its login state to directly establish the arkcli identity (saving one browser authorization). For disk write differences seereferences/arkcli-auth-login.md: it does not writetoken.json(IDToken/refresh_token/ClientID are managed by the ve SDK), but it writessts.json+metadata.json.source="ve";auth whoamishowsauth_method="sts"rather than"sso", which is a valid login state. Detection failure / ve not logged in → automatically fall back to arkcli native SSO OAuth. arkcli auth apikeyonly lists and selectsregular API Key pool, and writes identity/.env compatible credentials; it does not read or repair Agent Plan dedicated Keys, nor does it read team seat Keys. When the current profile is a Plan profile, preferprofile keys refreshor the corresponding Plan's rotation/seat flow; do not useauth apikeyofsaved=trueis interpreted as the Plan Key having been restored. It also cannot give the square voice model+chat/+gen/+deploy/+code-example/usage/pricingcapabilities.arkcli auth apikey createCreate, verify, and save aregular API Keyto identity/.env-compatible credentials; TTY must confirm, and in a non-interactive environment, after receivingrequires_confirmationit must go through the shared Skill's host confirmation flow; send only onceCreateApiKey, then perform at most 3 read-only status checks, and on success the output does not include the plaintext Key. It likewise cannot create or repair Agent Plan-specific Keys or team seat Keys; when an existing Profile needs to switch its default Key, still useprofile keys refresh/use。- The voice model capability boundary answer only states that arkcli does not support it; do not proactively offer alternative flows such as "first enable it in the console, then call it via API Key/SDK" unless the user separately asks about official access documentation.
- list API Keys without switching(only want to see which keys are under the account, and do not want to switch the current key): run
arkcli api apikey.list --params '{"PageSize":100}' --page-all --format json,do notrunauth apikey— the latter is an interactive selection that writes to the credential store, and will change the currently effective key - Metadata of the currently selected key(name / suffix / project / status): see the
auth statusin the output ofark_api_keyfield; no need to call the remote side again
Chaining with other skills
Before querying the Key list, distinguishing masked from plaintext, or injecting credentials downstream, first read API Key query and delivery. Preserve the business flow of "query metadata → locate the real ID → authorize export when necessary"; do not echo all plaintext by default.
arkcli-models、arkcli-chat、arkcli-gen、arkcli-deploy、arkcli-usageWhen blocked by an authentication error, first return here- If the user is actually troubleshooting profile / base-url / region override issues, they should switch to
../arkcli-config/SKILL.md
Natural language trigger words + cross-skill guidance table
| What the user says | Which command/skill to use |
|---|---|
| "Who am I / my identity / current user / which account / my own IAM user ID" | arkcli auth whoami |
| "Check colleague zhangsan's IAM user ID / check someone else's IAM user ID" | Switch to arkcli-profile(view the current profile and list available API Keys) + prompt the user to use the arkcli iam command (if any) |
| "API Key leaked / deprecate old Key / replace Key / rotate / rotate API Key" | Switch to arkcli-plans:plans personal rotate-apikey or plans team rotate-apikey |
| "A command suddenly reports key invalid/401/InvalidApiKey but I never changed the key" (suspected backend rotation) | Switch to arkcli-profile: first arkcli profile keys refresh sync the backend key and retry (reactive self-healing triggered only on failure, not preventive); if refresh cannot save it, then check references/auth-modes.md |
| "See which Keys the account has / Key list / query only, no switching" | arkcli api apikey.list, view metadata by paging according to the above reference, without changing the current Key |
| "View the Key inventory of the current Profile" | Switch to arkcli-profile: after explaining the sync impact, use profile keys list |
| "Switch default Key / use another Key" | Switch to arkcli-profile:arkcli profile keys use <key> |
| "Create a regular API Key" | arkcli auth apikey create; in a non-interactive environment, follow requires_confirmation to go through the host confirmation flow |
| "AK/SK login / access key / secret key" | Inform that the channel is temporarily closed:The current AK/SK login channel is temporarily closed. Please use SSO login, run arkcli auth login |
Command list
| Command | Description |
|---|---|
arkcli auth status |
View the current authentication status (credential health) |
arkcli auth whoami |
View the current authenticated identity (username / IAM user ID / account ID, etc.), used by scripts and Skills |
arkcli auth login |
Interactively select the login method (Volcano SSO browser / Volcano SSO browserless) |
arkcli auth login volc-sso |
Browser SSO login |
arkcli auth login --no-browser |
Browserless SSO (cross-device). TTY: interactive paste with a single command; non-TTY (agent/sandbox): Phase 1, print URL + authorize_pending JSON and exit |
arkcli auth login --no-browser --code <授权码> |
Browserless SSO Phase 2: feed the base64 authorization code back to complete login (the second step of the two-phase agent/sandbox flow) |
| arkcli auth apikey | Select a regular API Key and write it to the corresponding identity store; this does not mean that an Agent Plan exclusive/team seat Key is available |
| arkcli auth apikey create | Create, verify, and save a regular API Key to the current identity; do not output the plaintext Key, and do not handle Plan-exclusive/seat Keys |
| arkcli auth logout | Delete local credentials |