SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsarkcli-profile

arkcli-profile

Deployment & operations

View repository

Updated 10-16 10:51

About this skill

arkcli profile

CRITICAL — Before starting, you MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, configuration troubleshooting, and command selection order

CRITICAL — Once it is determined to go with profile create、profile delete or profile project(reselecting the project will rename/re-derive the platform profile), you must first restate the impact on config.yaml and obtain user confirmation; before other write operations (use / set-default / keys use / keys refresh / models refresh / rename) are executed, the target profile name must also be restated. CRITICAL — profile is local identity facet management; it does not register --dry-run。profile show/list/keys list globally and will perform a best-effort online Key sync, which may write back to the local Key inventory or default Key; use it only when the user explicitly requests Profile management, and explain this impact first. Other write operations are still protected by explicit confirmation.

First distinguish between verification and management

  • Read-only verification of whether the current identity and default resources are visible or whether credentials are compatible is not Profile management; even if the user provides a Profile name or type, first read the Auth and Resources Skills and let them handle it. Missing information does not authorize entering profile show/list/keys list。
  • When the user explicitly wants to manage Profiles and is preparing to run show/list/keys list , first inthe user-visible text before the tool callexplain two specific impacts: attempting to sync remote API Keys online; possibly writing back to the local Key inventory or default Key. For example: "This management query will attempt to sync API Keys online and may write back to the local Key inventory or default Key."
  • "I will explain first" is only a plan, not disclosure; the tool description, internal thinking, and the final reply after execution also cannot replace this prior explanation. After execution, these management queries must not be called "purely read-only" or used to guarantee that "the local Key has not changed."

Usage principles

  • profile is the unified identity facetintroduced in 0.1.16, binding (type × region × project × owner_trn × api_keys) five attributes into one group
  • profile write operations (create / use / set-default / keys / models / delete / rename) all go through arkcli profile <verb>; the old arkcli config init/list/show/switch/delete is deprecated, do not guide users to use it again
  • Ordinary identity admission uses arkcli auth status / arkcli auth whoami, default resource and routing checks use arkcli resources list; do not automatically enter Profile management for business admission
  • Run only when the user explicitly wants to view or manage Profiles profile show/list/keys list, and before execution explain that they may sync online and write back Keys; redacted stdout does not mean the local configuration has no side effects
  • Five ProfileTypes:platform / agent-plan / agent-plan-team / coding-plan / coding-plan-team; their required data planes, credentials, and resources for text/image/video differ
  • When the user only wants to temporarily pass an API Key / Base URL / Endpoint, do not create, switch, or modify a profile; first read ../arkcli-shared/references/execution-context.md

Applicable scenarios

  • The user asks "what profiles do I have / which profile is current / switch profile"
  • The user wants to create a new profile (platform / agent-plan / coding-plan)
  • The user asks what the default model / resource is, or wants to change the default
  • The user's API Key list is expired, and the new key has not yet been pulled in, so a refresh is needed
  • Business command +chat / +gen / resources list reports the error "profile xxx is missing ...", return here to troubleshoot

Anti-trigger signals

Hard state machine for switching profiles

  1. Before executing profile use , you must first run arkcli profile list --format jsononce; it can be reused only if there is already a complete, untruncated same-source list from the current round, and the target must not be assumed to exist from memory.
  2. profile list 's structured stdout is the sole source of truth for local profiles; if the list is empty, report that nothing is configured and stop, without searching the filesystem, reading the state directory, or guessing at config files. When the user gives an exact name, do only an exact match; if the name does not exist, state that truthfully and offer only the available profiles from the actual list results. Do not reinterpret that name as a project / region, and do not automatically project / create / rename。
  3. When the user gives only a type, purpose, or vague description, filter only using authoritative fields such as name / type / region / project from the list, then disambiguate strictly according to arkcli-shared 's 0 / 1 / N candidate rules; do not perform write operations before the user has chosen.
  4. Only after the target is unique and the user's intent is clear, execute arkcli profile use <name>, then you must run arkcli profile show --format json to verify the actual active profile.
  5. Only claim the switch succeeded if the verification result matches the target; report the effective facets name / type / region / project / base_url , and do not treat profile use 's exit=0 as final evidence.

Hard state machine for switching the default resource

  1. When the user has not given a specific resource ID, first determine the modality, then run arkcli resources list --modality <m> --format json only once to obtain the complete candidates for the current or --profile -specified facet.
  2. Candidates may come only from this actual result, and are handled according to arkcli-shared 's 0 / 1 / N rules: for multiple candidates, prefer invoking the host's structured selection capability; a generic Skill does not hardcode tool names.
  3. Before execution, restate the target profile, modality, and exact ID; use arkcli profile set-default --modality <m> <id> 's default inline verify. Unless the user explicitly requests it and accepts the risk of skipping verification, do not add --skip-verify。
  4. After writing, you must run arkcli profile show --format json or arkcli resources list --modality <m> --format json to verify the new default; only claim the switch succeeded if the structured result matches the target ID.

Exact semantics of the --profile flag (0.1.16 correction)

优先级:  --profile flag > ARK_PROFILE env > config.yaml default_profile
         > 第一个 type=platform 的 profile > "default" sentinel

Key correction (codex P0-A): on commands such as resources list / profile keys refresh / profile set-default / profile models refresh ,--profile no longer merely changes the target object name, but actually switches the execution identity — internally it uses Factory.RebuildForProfile(name) to rebuild the invoker, so arkcli profile keys refresh --profile B will hit the control plane with B's token / UserID, rather than hitting it as active=A and then writing to B.

Agent behavior conventions:

  • When the user runs a subcommand such as --profile B ,do not assume it is equivalent to the active profile; tell the user "operations will be performed as B"
  • 0.1.16 final clean-slate model: the entire arkcli has only one active identity at a time. When a new SSO completes, sso.ActivateIdentity detects newKey vs cfg.DefaultProfile.IdentityKey: if identical (alice logs in again as alice) → do not touch the yaml profile / --profile B is used for temporary switching across types within the same identity; if not identical (cross-sub / cross-tenant) → fully clear and rebuild all three layers yaml/.env/identities (BuildFirstProfileSet Volcano multi-type derivation)

Agent quick execution order

  1. Ordinary business only needs the current identity/Profile summary → arkcli auth whoami --format json; do not call Profile management commands to fill in ordinary admission
  2. The user explicitly wants to view the active profile or the local Profile list → first explain the Key sync/write-back impact, then use arkcli profile show --format json or arkcli profile list --format json
  3. The user wants to switch the default profile → follow the hard state machine above, first profile list, after pinpointing profile use <name>, then profile show
  4. The user wants to create a new profile: first ask clearly about the type (platform / agent-plan / coding-plan) → arkcli profile create --type ... --set-default
  5. The user asks what the default model is → for plan types use arkcli profile models list, for platform use arkcli profile show to view the resources field
  6. The user wants to change the default resource → follow the hard state machine above to get real candidates, disambiguate,profile set-default, then read-only verify
  7. The user's default API Key reports an error / the key list is stale → arkcli profile keys refresh, then arkcli profile keys list --format json to view the new list. refresh selects the corresponding pool by profile type: the ordinary pool, the Agent Plan personal edition exclusive pool, or team seat Keys; an empty result will report an error and keep the local Key, and will not successfully clear it.
  8. The user wants to select another key as default → arkcli profile keys use <api-key>(must ∈ profile.available_api_keys）
  9. The user wants to change the active project (without logging in again) → arkcli profile project(with no arguments, pull the real ListProjects for interactive selection; first restate "will rename/re-derive the platform profile to the new project, personal edition plan profiles are retained" and confirm)

Profile attribution of Token quota packages / resource packages

Products such as the "19 yuan Token quota package", "Token resource package", and "prepaid Token deduction package" still belong to the billing products for standard platform pay-as-you-go calls, and are not Agent Plan or Coding Plan subscription identities:

  • Should continue to use the profile of type=platform , and the data plane uses platform /api/v3。
  • Price, "quota package / plan" market names, and Token amounts are not ProfileType criteria; only explicit Agent Plan / Coding Plan subscriptions or team seats use the corresponding plan profile.
  • When the user only asks "which type of profile does it belong to", explain the classification directly; automatically executing is prohibited profile create / profile use / profile set-default。
  • When the user wants to actually use it, first use arkcli auth whoami --format json to check the current persistent Profile summary; when Profile details need to be viewed or modified, then follow this skill's sync disclosure and write operation confirmation contract.

Command list

Command Description Change source
arkcli profile list List all profiles (including type/region/project facets) Replaces config list
arkcli profile show [name] Show detailed information of the current/specified profile Replaces config show
arkcli profile use [name] Switch the default profile (interactive selection when no arguments) Replaces config switch
arkcli profile create --type ... Create a new profile (interactive or inline) Replaces config init(type changed to required)
arkcli profile delete <name> Delete a profile (must --yes to skip confirmation) Replaces config delete
arkcli profile rename <old> --to <new> Rename a profile (validate format + uniqueness) Added in 0.1.16
arkcli profile project [<name>] Reselect the active project (with no arguments, pull the real ListProjects for interactive selection; the list pins "all account resources" at the top = do not pass ProjectName/account-wide); re-derive the platform profile to the new project, keep personal edition plan profiles as-is; do not log in again Added in 0.1.17
arkcli profile keys list List default + available API Keys (masked) Added in 0.1.16
arkcli profile keys use <key> Switch default API Key (key must ∈ available list) Added in 0.1.16
arkcli profile keys refresh Re-fetch the regular pool / Agent Plan dedicated pool / team seat Key by profile type; update the available list when non-empty Added in 0.1.16
arkcli profile models list PlanTier + Resources defaults for plan-type profiles Added in 0.1.16
arkcli profile models refresh Re-fetch ListAgentPlanLatestModel, update Text.Default Added in 0.1.16
arkcli profile set-default --modality <m> <id> Set the default resource ID for a given modality Added in 0.1.16

ProfileType Selection Quick Reference

type Applicable Data plane base URL Control plane Vision models (image/video)
platform Standard usage of the Volcano Ark console /api/v3 OpenTOP ✓ Default endpoint
agent-plan Volcano Ark Agent Plan subscription (personal edition) /api/plan/v3 OpenTOP + Plan API ✓ AgentPlanImage/VideoModels hardcoded
coding-plan Volcano Ark Coding Plan subscription (personal edition) /api/coding/v3 OpenTOP + CodingPlan API text: text models included in the plan; image/video: via the platform data plane + the endpoint id of the user's +deploy (S10, commit f69be53)
agent-plan-team Agent Plan team seat /api/plan/v3 OpenTOP + Plan API text/image/video all use the plan models + team seat Key
coding-plan-team Coding Plan team seat /api/coding/v3 OpenTOP + CodingPlan API text uses the plan models + team seat Key; image/video use the platform Endpoint + pay-as-you-go API Key

The text lane of Coding Plan personal edition uses a pay-as-you-go API Key; for Coding Plan Team, only the text lane uses a team seat Key. For the full matrix, see ../arkcli-shared/references/execution-context.md。

plan-tier：

  • agent-plan：small / medium / large / max
  • coding-plan：lite / pro

profile create decision tree

用户提到 "Agent Plan / 我买了 plan"?
  yes -> --type agent-plan (--plan-tier 由 Detect 自动识别；后端可见性问题时手动加 --plan-tier=<tier>)
  no  -> 用户提到 "Coding Plan / claude code 整合"?
           yes -> --type coding-plan
           no  -> --type platform (默认场景, region+project 必填)

Common errors

  • set-default: <id> 不在当前 profile (... ) 可用列表 → run arkcli resources list --modality <m> to see available IDs, or add --skip-verify to force-write
  • models refresh: profile %q type=%q (仅 agent-plan 支持) → not an agent-plan profile, first profile use <agent-plan-profile> or switch to the correct --profile
  • After S10, under a coding-plan profile profile set-default --modality image|video <ep> no longer fail-fast: verify will validate whether the ep-id exists via the platform control plane ListEndpoints
  • keys refresh: fetch api keys: NotLogin → control plane authentication failure (e.g., login state/STS expired); the fetcher will use the .env cached single key as a fallback, profile.available_api_keys contains only 1 item, refresh again after recovery
  • keys refresh reports no available Key → first determine by profile type:platform / coding-plan personal edition: go to the regular API Key management page;agent-plan personal edition: go to the Agent Plan usage configuration page to check the dedicated Key; team edition: check the Running seat. Do not direct all types to the regular API Key page.
  • arkcli auth apikey only operates on the regular API Key pool; it returning saved=true does not mean the Agent Plan dedicated Key or team seat Key has recovered.
  • After switching accounts, keys / models refresh behaves strangely → check arkcli auth whoami, the active profile may still be bound to the old identity; after P0-D, STS / token are both in the per-identity store, but active profile.identity_key is a yaml field, so across accounts either profile use <new>, or go through SSO Gate 2 to automatically create a new one

deprecated command natural language redirection table

User mentions Actually executes
"config init / create new config / initialize config / create new profile" arkcli profile create --type ...
"config list / see how many profiles there are / list profiles" arkcli profile list
"config show / show my config / display profile" arkcli profile show
"config switch / switch config / switch profile / change profile" arkcli profile use [name]
"config reset / wipe everything / restore factory settings / config is messed up, start over / clear all config" switch to arkcli-config：arkcli config reset(destructive operation, must confirm first)
"what models are available under my agent-plan / what models are there / model list" arkcli profile models list(plan-type profile) or arkcli resources list

Reference