SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsarkcli-shared

arkcli-shared

General & other

View repository

Updated 10-16 04:59

About this skill

arkcli shared rules

This skill is the arkcli unified execution protocolentry point. All arkcli-* skills should read this file before execution.

Layering convention: the main text of this document only contains rules that "almost every task hits". Rare paths / lookup-type details are pushed down to references and read only when the corresponding scenario is hit:

Scenario Which to read
"my / my xxx" self-referential resource filtering ../arkcli-auth/references/identity-resolution.md
What can be called in AK/SK state / data-plane API Key error recovery ../arkcli-auth/references/auth-modes.md
Real-name check before activation / deployment / fine-tuning ../arkcli-auth/references/realname-gate.md
+chat/+gen/+deploy default resources and drift nudge references/profile-defaults.md
Temporarily pass in Profile / API Key / Base URL / Endpoint / model name references/execution-context.md
Whether the version is latest / refresh version information / explicitly upgrade arkcli references/update.md
Global flags quick reference references/global-flags.md
Error cannot be categorized / fault triage references/troubleshooting.md

Configuration and first-time use

  • On first use or when configuration attribution is suspected to be wrong (--profile / ARK_PROFILE / global flags / .env who overrides whom), first check ../arkcli-config/SKILL.md
  • profile-type write operations (create / use / set-default / keys / models / delete / rename) go through ../arkcli-profile/SKILL.md
  • To view available resources (endpoint / plan model ID), go through ../arkcli-resources/SKILL.md
  • Before the first remote call, first check ../arkcli-auth/SKILL.md
  • arkcli is a product CLI, not an OpenAPI Action browser; do not infer command design from Action names
  • Install: npm i @volcengine/ark-cli -g(public version)
  • Version check and explicit upgrade are read on demand references/update.md；update.mode reading, writing, and automatic gate still go through ../arkcli-config/SKILL.md

Invocation attribution protocol

When an AI Agent executes arkcli-* commands through any arkcli business skill, it must use the following single-command environment variable prefix. It both marks the invocation source and owning skill, and freezes the CLI version for this Skill workflow: it does not perform implicit registry update checks, does not print update prompts, and does not schedule automatic apply after any subcommand ends. When a human directly invokes arkcli in the terminal, do not manually add these variables.

ARKCLI_NO_UPDATE_NOTIFIER=1 \
ARKCLI_CALLER_TYPE=ai_agent \
ARKCLI_CALLER_NAME=<agent-id> \
ARKCLI_SKILL_NAME=<current-arkcli-skill> \
arkcli <command> ...

Convention:

  • ARKCLI_CALLER_NAME uses a stable Agent ID, for example codex / claude-code / opencode / openclaw / trae / cursor; when it cannot be reliably determined, use unknown_agent
  • ARKCLI_SKILL_NAME fill in the current business skill name, for example arkcli-gen / arkcli-chat / arkcli-models / arkcli-deploy
  • General business workflows should not put arkcli-shared into ARKCLI_SKILL_NAME, attribution must land on the actual owning skill; only when this skill directly handles version checks or explicit upgrades is it the owning skill, use ARKCLI_SKILL_NAME=arkcli-shared
  • ARKCLI_NO_UPDATE_NOTIFIER=1 Although the compatible variable name only writes notifier, the contract covers allimplicitupdate activities: cache reading/refresh, prompts, and automatic scheduling; it does not block the user's explicitly requested arkcli update / arkcli update --check
  • Every arkcli subcommand within the Skill must carry the complete prefix, not just the first one; this way a multi-command workflow uses the same installed version from start to finish
  • Only add the prefix to the current command, do not export to the entire shell session, avoiding leakage into subsequent unrelated commands

Unify CLI and Profile

Currently arkcli product identity is fixed at compile time; Profile only selects the identity and consumption facets within that product, and cannot switch products:

arkcli profile create --type platform --set-default          # 新建火山 profile（旧 config init/switch 已 deprecated）
arkcli profile use <name>                                    # 切换默认 profile

Switching profiles will correspondingly switch the login identity, API Key, control-plane routing, and other contexts. For the detailed command tree, see ../arkcli-profile/SKILL.md. You cannot infer or switch the currently compiled product from the Profile name or the tenant field.

When only querying the current identity/Profile, ordinary CLI uses arkcli auth status / arkcli auth whoami; for the default model and routing use arkcli resources list --modality <text|image|video> and verify according to the Resources Skill.profile show/list/keys list may synchronize remote Keys and write back to the local inventory or default Key, and cannot be used as a side-effect-free query for routine Chat/Gen admission or "do not change configuration/Key" requests. Explicit Profile management tasks retain these commands, but first explain the synchronization impact; do not switch to the deprecated config show/list to bypass restrictions. This boundary also constrains old suggestions in business Skills/references. When read-only verifying identity and default resources, each Bash call executes only one arkcli auth status、auth whoami or resources list --modality ... --format json; directly inspect the command's raw JSON and execution status. Do not use ; echo, pipe truncation, or redirection to wrap verification commands, to avoid host rejection or loss of the source of truth. If a command is rejected, report the incomplete verification, and do not infer the rejection as account or resource status.

Command routing and execution order

Prioritize judging byuser goal, not by thinking in terms of command names:

User goal Path Key points
Try out a model / quickly verify results auth → resources / models(optional) → +chat / +gen Plan lane uses the model name; Platform lane uses the Endpoint
Specialized multimodal understanding (transcription/extraction/subtitles/box targets...) auth → +understand When there is a clear output form, use understand, not chat
Speech model discovery / selection (TTS / ASR / podcast / voice / real-time voice interaction) auth → models search Only supports marketplace search; does not support +chat / +gen / +deploy / +code-example / usage / pricing / onboard
Formal integration / stable invocation auth → models → infer endpoint list → if none, then +deploy The core resource is the Endpoint, not +chat/+gen
Troubleshoot existing invocations / view consumption auth → usage —
Local AI Agent integration +connect —
Explicitly look up official documentation / read documentation URLs / business Skill lacks product knowledge docs After searching, read the body text; does not replace resource operations, authentication, diagnostics, and CLI help

Easily confused verb routing(to avoid choosing the wrong skill):

  • List / bind / distribute / rotate seat APIKeys → arkcli-plans；Usage / consumption / how much quota remains → arkcli-usage
  • profile write operations（create/use/set-default/keys）→ arkcli-profile; configurationtroubleshooting / old yaml → arkcli-config
  • Open-ended with imagesconversation → +chat；generationimage/video → +gen; with an output form,understanding → +understand
  • speech synthesis / TTS / dubbing / reading aloud, or the user names doubao-seed-tts-* and other marketplace speech models → only models search is allowed for discovery and selection explanation; do not switch to +chat / +gen / +deploy / +code-example / usage / pricing. Do not proactively add non-arkcli access paths or links such as console / OpenAPI / SDK unless the user separately asks "where is the official documentation". If the user just wants to "convert an audio file to text" and has not requested use of a plaza speech model, you may instead go through +understand asr; do not interpret +understand as supporting plaza ASR models.

Command selection order(always follow this):

  1. First use product command arkcli <domain> <verb> or arkcli +<workflow>
  2. if there is a corresponding reference document, read the reference first before executing
  3. product commands truly do not cover it, only then go through arkcli api（do nottreat Raw API Explorer as the default entry point)
  4. read operations should preferably be executed directly; before writing / deleting / switching default configuration, the user's intent must be confirmed

Authentication gate

Except for arkcli auth ...、arkcli profile list/show、arkcli +connect list、arkcli update ... , by default consider business commandsrequire passing the authentication check first. Do not skip the authentication check and then continuously retry a string of business commands.

  1. First run arkcli auth status; if already logged in, continue with the target command
  2. Not logged in / credentials invalid: keep the current compiled product, choose the login command according to its authentication Skill, and do not infer through Profile or switch products
    • Volcano: directly execute with Bash arkcli auth login volc-sso
    • Before execution, tell the user in one sentence "Not logged in detected; starting SSO login, please complete authorization in the browser"; set the Bash call timeout=600000(10 minutes); after success, immediately return to the original task and do not stop at the auth result
    • SSO covers both the control plane BFF and the data plane, so use SSO by default;AK/SK login channel temporarily disabled in 0.1.16. CI / agent / sandbox (non-TTY) use arkcli auth login --no-browser two-stage: Phase 1 run it to get authorize_pending in the JSON, authorize_url forward it to the user; after they authorize in the browser and paste back the base64 authorization code, then run arkcli auth login --no-browser --code <授权码> to complete (details in ../arkcli-auth/SKILL.md）。do notin non-TTY directly expect it to block waiting for paste (older versions will EOF crash)
    • Failed to start SSO (no browser / open failure / port occupied / timeout) → do not retry in place; paste stderr back to the user as-is and ask them to log in manually in the terminal and then come back
    • For login flow details, whoami, and apikey selection, see ../arkcli-auth/SKILL.md

Additional gate / error recovery(read only when hit, to avoid remaining resident):

Output rules

  • Global --format supports json、yaml、table、csv、jsonl、pretty; for script scenarios prefer json/yaml, and when fields need to be extracted use together with --transform
  • stdout only place structured results; explanations / debugging / errors all go through stderr
  • When consuming structured output, it is forbidden to first use head / tail / sed -n / head -c Truncate by line or byte and then parse. This may corrupt the JSON and also miss target items later in the array, the default marker, or the data corresponding to the warning. When the output is large, prioritize using the command's own --output <file>; when that flag is unavailable, redirect only the complete stdout to a file, then use jq / yq to extract the required fields.
  • The first call and the call that determines the conclusion must not use 2>/dev/null to swallow stderr; scope hints, soft truncation warnings, and recoverable errors may appear only on stderr.

Safety Rules

  • Do not output complete AK/SK, token, or secret
  • Before writing, deleting, or switching configurations, confirm the user's intent
  • Only registered Actions can be called via arkcli api invocation
  • For operations involving creating an Endpoint, modifying a profile, cleaning up credentials, etc., first check the leaf command --help: only if Client Preview is supported can you use --dry-run; if it is not supported, switch to read-only commands to verify and obtain explicit confirmation, and never generate a nonexistent flag

Intent Clarification and Structured Selection

Intent clarification only resolves "which real target the user wants to operate on"; it does not replace authorization for write operations. When the user's target is already unique, or can be safely determined from this round's input and the current authoritative result, do not ask additional questions. When ambiguity truly exists, follow these hard rules:

  1. First perform one minimal, bounded read-only query; candidates may come only from this round's complete structured results, and must not be completed from model memory, examples, or truncated output.
  2. Only the hard constraints explicitly given by the user and the product's authoritative eligibility fields may be used to filter candidates; relevance ranking, display order, recommendation text, and the Agent's own judgment of pros and cons are not hard constraints, and subjective "best fit" must not be used to converge N candidates into 1 on your own.
  3. Converge by 0 / 1 / N: for 0, add one most critical condition; for 1, restate the exact ID and continue; for N, when the choice would change the remote result, you must ask the user and stop until the user selects, and must not proceed to downstream preview, create, update, or delete.
  4. For N candidates, prioritize using the structured selection capability provided by the current host, with options directly carrying the real ID and key fields needed to distinguish the targets; recommendations and their basis may be labeled, but a recommendation cannot replace the user's choice. A general Skill does not hard-code any host tool name, nor does it repeatedly add the free-input item automatically provided by the host.
  5. When the host has no structured selection capability, fall back to a concise numbered list and require the user to reply with the exact ID. After the user selects, continue only along the original workflow and do not re-query the same batch of candidates.
  6. When stopping to ask due to N candidates, besides letting the user choose "which one to use this time", also provide a way to fix it, so the user can also choose "use it from now on"—if that candidate set has a persistence switch, explain how to enable it: for generation-type modality defaults, go through arkcli profile set-default --modality <image|video> <ep-id> to write the current profile's default for that modality, and the next similar request will no longer ask. Otherwise, similar requests will have to ask again every time, and unattended scenarios will remain stuck. This iswrite operation, and is executed only after the user explicitly agrees; the inquiry itself still stops according to the above rules, and do not preselect on the user's behalf.

Task-oriented model selection exception: when the user requests creating a Managed Agent and does not specify the primary model, follow the owning arkcli-agent model selection process, allowing selection based on real-time eligibility, details, and user intent in the current round with an explanation of the basis, without necessarily asking just because there is more than one candidate. Optimal selection does not mean falsely claiming multiple candidates are the only candidate; clear hard constraints must have corresponding version evidence, and when cost/capability differences materially affect the task and cannot be safely judged, still ask first. This exception does not permit replacing the user's explicit model, switching identity/billing paths, or arbitrarily choosing an existing resource for operations such as updates or deletions, nor does it replace execution authorization.

secondary confirmation error handling (human-in-the-loop)

High-risk operations (deleting resources, changing credentials, incurring costs, etc.) require secondary confirmation. The CLI automatically detects the environment: an interactive terminal shows a Y/N prompt; non-interactive (Agent invocation) returns ExitValidation error,type="requires_confirmation"。

When arkcli returns ExitValidation and type="requires_confirmation" :

  1. Do not directly report the error to the user — this is the normal secondary confirmation process
  2. Call the user confirmation capability provided by the host — the prompt content can be extracted from the CLI error's hint field, or use the generic prompt "A high-risk operation is about to be executed. Confirm to continue?"
  3. User confirms → add --yes flag to the original command and retry
  4. User cancels → return "Operation canceled"

Commands that currently trigger secondary confirmation:plans personal rotate-apikey、plans team rotate-apikey、models activate <model-name>、profile delete <profile-name>、profile project [<project-name>]、config delete <profile-name>. Subsequent newly added high-risk commands follow the same convention.

Prohibited Agent Behaviors

  • Do not treat arkcli api as the default entry point
  • Do not continuously retry business commands before checking authentication status
  • Do not treat intermediate steps as the final result; after login, model query, and profile switching are complete, return to the user's original task
  • Do not repeat shared rules in business skills; shared rules are uniformly governed by this skill (and its references)
  • Do not blanket-claim "trials do not require an Endpoint": the Plan lane uses the model name, while the Platform lane must use an Endpoint. Judge by references/execution-context.md ; official integration still goes through +deploy
  • Do not mistakenly write speech models searchable in the marketplace as already supported by arkcli for invocation, deployment, examples, usage, or cost queries; in arkcli, speech models currently only support models search discovery capability.
  • Do not expand the answer about speech model boundaries into alternatives like "go to the console to enable / use OpenAPI / use SDK integration"; this skill currently only explains arkcli support boundaries.
  • Do not add temporary Project/Region overrides to business commands; the root command has removed --project-name and --region. Persistent context is managed through arkcli profile create/use , and a one-time switch uses --profile。

Reference