SuperAPI AI Directory

arkcli-auth

General & other

View repository

Updated 10-16 04:56

About this skill

arkcli auth

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):

  1. 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 through BuildFirstProfile (create new) / GUIDE_SKIP (reuse) / prompt to switch default / prompt to create new. See docs/runtime/volc-sso.md。
  2. AK/SK login channel temporarily closed:auth login --access-key / --secret-key is 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.
  3. auth status / auth whoami output adds profile facet fields:active_profile.{name,type,region,project,owner_trn} and profiles_summary[...]; top-level auth_method/logged_in/volc_sso/ark_api_key and other old fields are all retained (backward compatible).
  4. Profile management migrated to arkcli profile:config init/list/show/switch/delete is deprecated, see ../arkcli-config/SKILL.md。
  5. 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 IAM ListProjects (on pull failure/no permission, fall back to the fallback default, 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。
  6. Since 1.0.4, arkcli auth login interactive browser SSO branch supports borrowing the local volcengine-cli login state: when ve >= 1.0.45 is detected and already ve 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_method becomes "sts" instead of "sso", but logged_in=true. Detection failure / ve not logged in → automatically fall back to arkcli's native SSO OAuth flow. See references/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 — use arkcli 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-volc no login, no interaction, no network access, it purely consumes environment variables; first-time bootstrap for local terminal users still goes through auth login(SSO)
  • For detailed environment variable contract, landing behavior, and output, see references/arkcli-auth-init-volc.md

Agent quick execution order

  1. Before starting business commands, if you are unsure of the authentication status, first run arkcli auth status
  2. 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/.env to manually decode the JWT
  3. 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,open failure, 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
  4. 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-browser is 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). Forward authorize_url as-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).--code must 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 same HOME / 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 / --code are all attached to the auth login root command, not to the volc-sso subcommand;auth login volc-sso --no-browser will report unknown 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-browser is still a single interactive command (prints the URL and then you paste on the spot), behavior unchanged.
  5. 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
  6. Only when the user explicitly asks to clean up local credentials, execute arkcli auth logout

Core rules

  • auth status is the default entry point; do not start with login
  • 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 logout is a destructive operation and must be explicitly requested by the user
  • auth status masks sensitive fields, can be used directly for troubleshooting, and will show the currently effective project_name
  • auth login outputs on success auth_method; the credential storage location is an implementation detail and the path is no longer echoed
  • SSO login (arkcli auth login volc-sso) and auth apikey both 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-plan Personal Edition uses a regular API Key;agent-plan Personal Edition uses the Scene=RealAgentPlanPersonal dedicated Key;agent-plan-team / coding-plan-team uses the GetSeatInfo seat 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.45 installed and already ve login , arkcli auth login will first try to borrow its login state to directly establish the arkcli identity (saving one browser authorization). For disk write differences see references/arkcli-auth-login.md: it does not write token.json (IDToken/refresh_token/ClientID are managed by the ve SDK), but it writes sts.json + metadata.json.source="ve"; auth whoami shows auth_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 apikey only 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, prefer profile keys refresh or the corresponding Plan's rotation/seat flow; do not use auth apikey of saved=true is interpreted as the Plan Key having been restored. It also cannot give the square voice model +chat / +gen / +deploy / +code-example / usage / pricing capabilities.
  • arkcli auth apikey create Create, verify, and save aregular API Keyto identity/.env-compatible credentials; TTY must confirm, and in a non-interactive environment, after receiving requires_confirmation it must go through the shared Skill's host confirmation flow; send only once CreateApiKey, 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 use profile 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 notrun auth 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 status in the output of ark_api_key field; 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-usage When 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 |

Reference