SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsarkcli-config

arkcli-config

Deployment & operations

View repository

Updated 10-16 09:50

About this skill

arkcli config

⚠️ Command tree migration starting from 0.1.16：arkcli config init/list/show/switch/delete has been marked deprecated, please use arkcli profile create/list/show/use/deleteinstead (consistent behavior + new profile facet fields type/project/owner_trn/available_api_keys).arkcli config reset is retained (clears the entire local state, beyond a single profile). 0.2.x deletes all deprecated subcommands.

CRITICAL — Before starting, MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, command selection order and shared security rules CRITICAL — Before configuration-type write operations, user intent must be confirmed.profile show/list/keys list may synchronize remote Keys and write back to local inventory or the default Key, and cannot be treated as an admission probe with no configuration side effects.

Trigger Signals (When To Trigger)

  • User mentions:profile、base-url、api-key coverage confusion, or is still using the deleted global --region/--project-name
  • User symptom: the same business command "hit the wrong environment/wrong base URL/wrong account", suspected to be caused by inconsistent configuration sources
  • User goal: initialize/update profile, switch default profile, reset local configuration file
  • User goal: enable, disable or restore arkcli's auto-update/update prompt policy

Anti-Trigger Signals (When NOT To Trigger)

  • What the user wants to solve is "not logged in/401/authentication failure/no permission": first go through arkcli auth status, and if necessary switch to ../arkcli-auth/SKILL.md
  • User goal is business functionality (models/+chat/+gen/+deploy/usage, etc.): do not dwell on config; after ruling out configuration, return to the original task

Applicable Scenarios

  • Initialize or update profile
  • View the currently resolved configuration
  • Switch default profile
  • Delete a single profile or reset the entire local configuration
  • Troubleshoot why a business command connected to the wrong environment, wrong account or wrong base URL

Agent Quick Execution Order

  1. First comply with shared authentication and host boundaries. For current identity/Profile diagnosis of a normal CLI use arkcli auth status --format json、arkcli auth whoami --format json; when the host prohibits additional authentication probing, use the context already provided by the host and do not probe on your own.
  2. For Chat/Gen default model and routing use arkcli resources list --modality <text|image|video> --format json, distinguishing discovery, compatibility and real call verification according to the Resources Skill. Merely viewing the default model does not equal authorization to send billable requests.
  3. Switch default profile:arkcli profile use <name>
  4. Create profile:arkcli profile create --type=...(see the arkcli-profile subtree for details, not repeated in this skill)
  5. arkcli config reset is a destructive operation (clears the entire local configuration file), user intent must be confirmed
  6. Update policy only uses allowlist commands:arkcli config set update.mode automatic|disabled
  7. Only consider arkcli profile show / arkcli profile listwhen the user explicitly needs Profile details, inventory or Key management; before execution explain that it may synchronize and write back Keys. When the user requests "do not change configuration/Keys", do not execute them, and do not switch to the old config show/list to bypass the restriction.

Configuration Attribution (Priority)

arkcli resolution priority (from high to low):

  • Profile selection: --profile flag > ARK_PROFILE environment variable > config.yaml of default_profile > the first type=platform profile > "default" sentinel
  • API Key: --api-key > ARK_API_KEY > profile > same identity store > product .env compatible value
  • Base URL: --base-url > ARK_BASE_URL > profile custom value > derived from the Profile's Region/Type > default value
  • Region/Project: held by the selected Profile;ARK_REGION / ARK_PROJECT_NAME no longer overrides at runtime

--api-key/--base-url For data-plane commands only. When there is no Profile, they must be provided as a pair; when overriding the Base URL, the API Key must also be explicitly provided. If control-plane/local commands explicitly receive these two flags, they will fail-fast.

When troubleshooting, you must clarify "who overrode whom"; do not just guess.

0.1.16 correction：--profile now takes precedence over ARK_PROFILE(aligned with the CLI industry convention flag > env > config). Version 0.1.15 and earlier was env > flag, the opposite of this rule.

Evidence and conclusions

Explain what was actually checked in this round and which sources of override remain unverified; do not repeat fixed evaluation phrases.auth whoami The Profile fields are a persistent slice summary; you cannot claim based on them that a temporary API Key/Base URL override has been verified or that a data-plane call will definitely succeed. When evidence is lacking, explicitly keep the unknown as unknown, and do not run commands that might write back configuration just to fill in fields. For path display, use $HOME/..., and do not read credential files.

Core rules

  • This skill is responsible for explaining "why a command hit the wrong environment/wrong account/wrong base URL", and is compatible with historical config init/list/show/switch/delete command troubleshooting semantics
  • Routine admission follows auth status/whoami → resources, and does not treat Profile management commands as side-effect-free queries
  • profile write operations (create / use / set-default / delete) go through the arkcli profile subtree
  • arkcli config reset is responsible for full cleanup;arkcli config set update.mode <mode> only writes update policies. Do not use it to write arbitrary YAML paths.

Guard Checklist (required)

  • Read-only intent: do not execute profile show/list/keys list, which may write the Key back; redaction does not mean no side effects, and a command named show/list is not necessarily read-only
  • Write operation confirmation: before executingprofile use/delete and config reset , you must restate the scope of impact and obtain confirmation
  • Full cleanup reminder:arkcli config reset deletes config.yaml/config.json, and will not clean up $HOME/.arkcli/.env(token) or the identity store; to clean up credentials, use arkcli auth logout

Chaining with other skills

  • profile creation / switching / resource default setting / API Key management → go to arkcli-profile(recommended) or continue to this skill's compatibility mapping
  • When a business command fails and you suspect it is --profile、--base-url, the API Key source, or a Profile Region/Project mismatch, come here first
  • After the configuration issue is ruled out, return to the original business skill to continue
  • If the configuration still cannot explain the problem, then consider going to ../arkcli-auth/SKILL.md or ../arkcli-api-explorer/SKILL.md

Command list

Command Description Status
arkcli config reset Delete the entire local configuration file (preserved) ✅ Active
arkcli config set update.mode automatic Explicitly enable automatic for the current exact install; when restoring from a non-latest version, install latest first and then execute ✅ Active
arkcli config set update.mode disabled Turn off silent auto-install, keeping the implicit version check, update prompts, and manual update ✅ Active
arkcli profile show [--profile <name>] View Profile; may sync and write the Key back ✅ Profile management, replaces config show
arkcli profile list List Profiles; may sync and write back each Profile's Key ✅ Profile management, replaces config list
arkcli profile use <name> Switch the default profile ✅ Replacement config switch
arkcli profile delete <name> Delete a single profile ✅ Replacement config delete
arkcli profile create --type=... Create profile (replaces old config init） ✅ Replacement config init
arkcli config init/list/show/switch/delete Old subcommand, removed in 0.2.x ⚠️ deprecated

In public mode, only automatic and disabled。disabled retain implicit version checks and update prompts, but never install silently; explicit arkcli update and arkcli update --check are also always available. Missing update.mode and notify in historical configurations are both treated externally as disabled , and notify in historical configurations continues to be read compatibly as disabled , but users must no longer be advised to set notify。

The fail-closed transaction and six product/platform production gates for Windows, macOS, and Linux are all enabled. The stable global npm postinstall compares the installed version with the registry's current latest : if not latest, it persists disabled; if currently latest, it does not change mode, and when automatic already exists, it issues a new authorization for the new exact install. postinstall does not perform version replacement immediately.

New install enrollment

Only a stable global npm new install that can prove "there was no product state directory previously" and whose installed version equals the registry's latest will by default write automatic and create lazy pending evidence bound to the current exact install:

  1. The first successful, safety-compliant manual business command completes pending → grace → active in one policy transaction.
  2. After rechecking and confirming that exact-install consent is active, that invocation can schedule automatic patch updates.

All CLI processes started by npm postinstall (including +connectwithin them) as well as user-executed +connect do not consume enrollment, do not perform implicit version checks, and do not schedule automatic. AI Skill, CI, non-TTY, Client Preview,config、update and internal maintenance commands likewise do not consume enrollment and do not schedule automatic. After a successful update, the next successful manual business command displays the 旧版本 -> 新版本 result only once on stderr, without modifying stdout or the business exit code.

Current production automatic is disabled by explicit product policy for 24/48/72-hour and 10%/50%/100% cohort admission; the original rollout implementation and regression tests are still retained, and the online Probe still requires two independent observations. Ordinary automatic must still satisfy exact consent, real-time registry target/SRI/tarball verification, reservation, backoff, and all staged-apply safety boundaries.

Every npm reinstall must not reuse the old exact-install receipt. If the installed version equals the current latest, the existing mode is not changed:automatic issues a new receipt, whiledisabled / historical notify remain disabled. If the installed version does not equal latest, persist disabled. If the registry fails, do not change mode and do not issue a new receipt;--ignore-scripts will not complete alignment either. When recovering from a non-latest version, first install latest, then explicitly run arkcli config set update.mode automatic. For long-term version pinning, use:

arkcli config set update.mode disabled
npm i @volcengine/ark-cli@<exact-version> -g --registry https://registry.npmjs.org

To avoid uncertainty when the registry is unavailable, when deterministic version pinning is needed it is still recommended to first run arkcli config set update.mode disabled and then install the exact version.disabled is located at $HOME/.arkcli/config.yaml, and installing @latest will not automatically change it back to automatic。arkcli config reset will make a best effort to revoke exact consent before clearing the configuration. If a new version is published exactly between npm resolving @latest and the postinstall query, there is a very small probability of a race condition causing it to be misjudged as not latest.

Reference