arkcli-api-explorer

arkcli api（Raw API Explorer）

CRITICAL — Before starting, you MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains authentication, configuration override troubleshooting, and command selection order CRITICAL — Only when existing product commands and business skills truly do not cover the case is it permitted to enter this skill; it is forbidden to treat arkcli api as the default entry point. CRITICAL — Before any arkcli api ... call, you MUST first use the Read tool to read references/arkcli-api.md, and it is forbidden to blindly guess parameters and output structure.

Usage Principles

• unknown action First check the local api --list, use the complete registered name, and do not guess the Action based on an approximate business name;MissingParameter Fill it in according to the field names and capitalization in the current contract, and do not try Id/ID/KeyID。

• When querying the API Key, first read Auth's API Key query and delivery: list only locates metadata; only authorized export uses the real Id to call apikey.get_raw, and by default do not echo plaintext or rotate.

• The installed state may not have the repository source code: prioritize reading the Skill/reference of the same version and the registered directory; when the source code is accessible, then check the req/resp JSON tags. If there is no certain contract source, state the gap and stop; do not fabricate that the local internal/apis file has been checked.

• Product commands first:arkcli <domain> <verb> or arkcli +<shortcut>

• Then skill / reference: confirm whether a stable entry point and correct parameters already exist

• Only last arkcli api: used only for low-frequency, specialized, or high-risk low-level Action verification and fallback

Do not infer a new top-level skill or cmd/ command just because a certain Action exists; only when it is upgraded to a stable product capability should you consider adding shortcuts/。

Applicable Scenarios

• Existing product commands truly cannot cover the requirement (and the requirement is not worth making into a standard command or +shortcut）
• Need to verify the input/output contract of a registered Action (for example, troubleshooting, regression verification, confirming transport reachability)
• Need to confirm whether a certain Action already exists in the registry (for development or troubleshooting "missing registration")

Trigger Signals (When To Trigger)

• The user explicitly mentions:action / operation / registry / "registered Action" / "contract verification"
• The user provides:arkcli api ... --params ... and needs you to complete/troubleshoot it
• The user encounters:unknown action / needs to confirm whether a certain Action exists
• Development scenario: after adding a new operation in internal/apis/<domain>/ , quickly verify whether it can --list and be callable

Anti-Trigger Signals (When NOT To Trigger)

• The user wants the public API contract catalog, interface identifiers, OpenAPI schema, or required request fields: switch to arkcli-docs 's docs apis list/spec。api --list only lists Actions registered locally in the binary; it is not a public API catalog and does not provide a complete OpenAPI schema.
• The user's goal is: chat (+chat), generation (+gen), deployment (+deploy), usage (usage), model lookup (models) and other existing stable product paths
• The user is merely experiencing authentication failure/not logged in/confusing environment profile (should first go through auth/config, do not direct the problem to api）
• The user just wants to "find out how to use a command" (prioritize arkcli <domain> --help + the corresponding skill/reference)

Agent Quick Execution Order

1. First determine whether the user's goal already has a product entry point:arkcli <domain> --help, and prioritize switching to the corresponding business skill
2. If it is only an authentication/configuration issue, do not misjudge it as requiring api：
   • If authentication fails, first switch to ../arkcli-auth/SKILL.md
   • If profile/base-url/region overrides are inconsistent, first switch to ../arkcli-config/SKILL.md
3. Enumerate registered Actions (no parameters is equivalent to list):
   • arkcli api --list
   • arkcli api
4. Locate the contract and required fields (do not guess JSON):
   • Check the same-version reference/official contract; when the repository is available, then check internal/apis/<domain>/ the corresponding req/resp struct; when there is no source code in the installed state, do not claim to have checked it
   • The same Action fails twice consecutively due to MissingParameter / InvalidParameter , and the error does not give a definite value. Stop trying similar field names by trial and error; go back to the registered operation, req/resp tag, or official contract to confirm. Do not loop through guesses such as Scene / Type / BizType fields.
5. First use the leaf command's Client Preview to verify the final descriptor and payload:
   • arkcli api <registered-action> --params '{...}' --dry-run
   • Preview is purely local behavior; it does not log in, does not request the backend, and does not prove permissions, quota, or resource existence
6. Prefer read-only; write operations must still be confirmed a second time after Preview, then remove --dry-run and execute:
   • arkcli api <registered-action> --params '{...}'
   • The payload's own "DryRun":true is a backend field; without adding CLI --dry-run , a real network request will still be sent
7. Keep output as stable as possible and reduce noise:
   • Prefer the global --transform '<gjson path>' to extract key fields
   • Enable only when needed for troubleshooting --debug(will output request/response debugging information to stderr)

Guard Checklist (must be executed)

Checkpoint	Purpose	Method
Product command coverage judgment	Prevent misuse api	First arkcli <domain> --help and compare with the corresponding skill
Authentication gate	Prevent judging an authentication issue as a missing capability	First arkcli auth status; on failure switch to arkcli-auth
Contract source of truth	Prevent guessing parameters	Generate from the same-version reference, official contract, or accessible req/resp JSON tag --params; if there is no definite contract, stop
Client Preview	Prevent direct execution of raw Action	In invoke mode, first add local --dry-run, verify steps[0].protocol/target/payload
Risk confirmation	Prevent accidental triggering of write operations	Before creation/deletion/modification/cost impact, require explicit user confirmation
Noise control	Prevent whole-blob output from polluting upstream and downstream	By default guide --transform to extract key fields;--debug open only for troubleshooting

Examples

arkcli api --list
arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --dry-run
arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}'

# 只提取 items 里的 name（示例 path，按实际输出结构调整）
arkcli api model.list_foundation_models --params '{"PageSize":10,"PageNumber":1}' --transform 'Result.Items.#.Name'

Common errors and handling

Symptom	Common cause	Handling method
unknown action "..."	Action not registered or misspelled	First arkcli api --list; then in internal/apis/ confirm whether it is registered
invalid --params JSON: ...	JSON is invalid (improper quotes/escaping/single-quote wrapping)	Ensure --params is valid JSON; if necessary, put the JSON in a file and pass it in via shell expansion
api list mode has no request to preview	Used api --list with --dry-run	list itself is already a pure local enumeration; remove --dry-run
Output fields do not match expectations	Guessed the contract directly	First read references/arkcli-api.md and check the req/resp of internal/apis/<domain>/ req/resp

Development constraints

• If the Action is not registered: add the operation registration and req/resp contract for internal/apis/<domain>/ operation registration and req/resp contract
• Do not directly add a new one just because the Action is missing; cmd/<action>；api is the fallback entry point
• Only when it is upgraded to a stable product capability, add the business command in shortcuts/ (along with skill/reference/test)

Reference

• arkcli-shared -- authentication, configuration override troubleshooting, and shared security rules
• arkcli-auth -- fallback entry point when authentication fails
• arkcli-config -- troubleshooting entry point for profile / base-url / region
• references/arkcli-api.md -- command semantics, parameters, and troubleshooting for api explorer
• references/evals.md -- minimal evaluation cases (invocation/de-invocation/troubleshooting)