SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsarkcli-deploy

arkcli-deploy

Deployment & operations

View repository

Updated 10-16 04:57

About this skill

arkcli +deploy

CRITICAL — routing exceptions must precede any command: when the user explicitly requests scripted / CI / no-guardrails / raw raw CRUD creation of an Endpoint, immediately read ../arkcli-infer-endpoint/SKILL.md and let it take over; before the handoff is complete, authentication checks, model queries, or other commands are prohibited.

Prerequisite: First use Read to read ../arkcli-shared/SKILL.md to obtain the shared authentication/configuration/write-operation guard rules.

Model clarification in creation intent

As long as the user's ultimate goal is still "create / new / deploy an Endpoint," even if a complete model ID has not yet been provided, you must remain in the arkcli-deploy workflow;arkcli-models at this point it is only a temporarily invoked read-only candidate query capability, and the creation task must not be rerouted into pure model discovery.

Candidates must come fromthis round's ArkCLI live structured output; completion from model memory, examples, or old version numbers is prohibited.

The query budget is exactly one Bash call in the current user turn. Before execution, determine the keyword, filter conditions, and --size。models search 's keyword is a single catalog substring; do not combine multiple concepts into a space-separated phrase: first choose the one ASCII token that best narrows the scope, and put the remaining conditions into flags in the same call or jq local filtering. For example, for "Doubao code model" use keyword code, then in the same pipeline filter by name 's doubao|seed filter; for "image generation" use seedream. When unsure of a stable token, prefer omitting the keyword and using the existing structured filter; submitting an untranslated Chinese phrase directly and then changing words to retry is prohibited. If worried about overly long output, put the field projection directly into the same pipeline, for example arkcli models search "<keyword>" --size 0 --format json | jq -c '{items: [(.items // [])[] | {name, primary_version, lifecycle_status, input_modalities, output_modalities}]}'. Regardless of whether this call succeeds, returns empty results, is truncated, or fails, you must not change keywords, increase pagination, rerun the same command, or call ArkCLI once more just to reformat; use only the captured stdout, and if information is insufficient, stop truthfully.

  1. No model given at all: execute one bounded query, for example arkcli models search --size 10 --format json. If the user has already stated the purpose or modality, add the corresponding keyword / --modality to the same query.
  2. Only a brand, series, or family name is given(for example "Doubao" or "Seed 2"): execute one arkcli models search <keyword> --size 10 --format json; the family name is not a complete ID that can be passed directly to --model the full ID of
  3. From the same returned items , read the existing fields such as name、primary_version、lifecycle_status and modality. Prefer retaining candidates where lifecycle_status=Published and whose name does not contain internal / test . When the status is missing or not Published, you may only truthfully mark it as unverified, and must not call it "deployable." The complete model ID is determined according to the model query contract:primary_version When non-empty, use the returned value to precisely compose <name>-<primary_version>, and only when empty use <name>; this is a structured field combination, not guessing the version from naming or date patterns. Do not on your own append to name the suffixes pro、lite or any version suffix that was not returned.
  4. 0 usable candidates: state that nothing was found this round, and ask the user to supplement the purpose, modality, or keyword; do not guess one and continue.
  5. 1 available candidate: repeat the full ID returned in this round and ask the user to confirm; if the user has requested that this round be query-only, then stop here.
  6. Multiple available candidates: list the condensed candidates and their full IDs, and ask the user to make an explicit choice; if there are still too many candidates, narrow the scope based on the user's purpose, and do not arbitrarily select the first item.

Convergence boundary for the clarification stage: after the first search in this round returns,do not execute models searchagain, and do not execute models get, price queries, or other detail calls in a loop over the candidates. Only after the user has selected a single candidate and then explicitly requests comparison of some missing attribute should one targeted query be added in a subsequent round. Before the model has uniquely determined it, do not execute +deploy、infer endpoint create or Raw API creation.

The Endpoint name should not block the above read-only candidate queries; after the model is selected, collect the name and confirm the final creation parameters.

New flag --set-default <modality>: after successful deployment, automatically set the new endpoint as the default resource for that modality (text / image / video) of the active profile. It takes effect only when the deployment actually succeeds and the user explicitly passes the modality; on failure, only warn to stderr and do not block the main deployment flow. See ../arkcli-shared/references/profile-defaults.md。

Write operations + billing：+deploy Creating an online inference Endpoint is a real write operation and will generate billable resources. This workflow depends on online probing,does not support --dry-run; the final parameters must be explicitly confirmed with the user before execution.

Model activation is an independent billable write action, and in non-interactive environments it must never be activated automatically: if the target base model has not yet been activated,+deploy will trigger "activate model" (an account-level billable write).In non-TTY environments such as agents / CI / pipelines, activation is hard-rejected—--yes will not allow it either（--yes It is used only in a real human interactive terminal to skip [y/N]). When it is hit, the CLI returns model_activation_required + a console link; youmust end this round and hand the matter of "activation (billing)" together with the link back to the human, so that the human can confirm in an interactive terminal or activate it in the web console.It is strictly forbidden to add --yes / echo Y / set ARKCLI_ALLOW_HEADLESS_ACTIVATION yourself to activate it on the user's behalf—printing a line like "please confirm" and then adding --yes yourself in the same round and running away is equivalent to not asking at all.ARKCLI_ALLOW_HEADLESS_ACTIVATION=1 It is reserved only for truly unattended automation (CI pipelines), and is not something an agent should set.

Real-name verification prerequisite (hard gate for activation-type actions)：+deploy will trigger model activation,The first stepis to first arkcli auth status read volc_sso.identity.verified——false and stop immediately, paste the real-name verification page https://console.volcengine.com/user/authentication/detail/ to the user, and pause and wait (see ../arkcli-auth/references/realname-gate.md）。Do nottry +deployfirst, and after hitting an invalid model-id / model not activated error, go back and check real-name verification—those errors will lead you astray.

Hard boundary for speech models: For TTS / ASR / dubbing / reading aloud / podcasts / voice design / real-time voice interaction, or when the model name matches doubao-seed-tts-*、doubao-seed-asr-*、seedasr-* ,do not execute +deploy. In arkcli, these models currently support only models search for plaza discovery; they cannot create an Endpoint, nor can model activation be used to bypass this.

Sample code:+deploy automatically rendered after creation + independent command +code-example

Both paths are available, and both use OpenTOP OpenGetSampleCode：

  • +deploy Automatically render after successful creation: write the multilingual invocation examples for this endpoint to ./ark-examples/<ep-id>/(use the ep-id as the directly callable model id; the examples call the endpoint you just created directly), and print a one-line persistence summary to stderr. Best-effort — if examples cannot be fetched, only soft-prompt; this does not affect Endpoint creation/startup.
  • Standalone command arkcli +code-example: generate examples separately by base model name/version, convert to ../arkcli-code-example/SKILL.md; note that it is provided by model-version, and some versions' backends have no group and will return not found; when missing, fall back to ark-examples/ static examples or the Ark console example code page.

Subcommand enumeration (there is only this one)

Invoke Description
arkcli +deploy --name <ep-name> --model <model-id> [...] Create Endpoint; execution means real creation

⚠️ There is no arkcli deploy ... / arkcli endpoint create / arkcli +deploy create and other subcommands. The entire capability is just one +deploy command plus flags.

Anti-hallucination checklist

  • Before delivery, read the return values and acceptance boundaries: distinguish new creation/reuse, creation/inference verification, and example generation success/soft failure. Use real stdout, stderr, and files as evidence; do not repeatedly create billable resources because of example or default-setting failures.
  • --name、--model required
  • Model versions, prices, and quotas may only cite the structured results returned by this round's read-only commands;do not fabricate model versions or prices. When a query fails or you are not logged in, clearly mark it as "not yet verified"; do not substitute "typical prices" or guessed values
  • After a query failure, do not fill in dependent fields: if any authentication, model, price, or resource query fails, keep the corresponding field as "not yet verified" and clearly point out the source of the failure; do not continue to assert specific amounts, idle billing policies, exact model versions, or "there is no existing Endpoint"
  • When checking existing Endpoints, use arkcli resources list --format json and then filter by the returned fields;do not add undocumented --filter or other resources list --help flags that do not exist in
  • JSON-type flags (--rate-limit / --moderation / --intelligent-router / --tags , etc.) field names are always PascalCase：Rpm、Tpm、Strategy、Mode, not rpm/tpm
  • The flags of the standalone +code-example are --model(base model name/versioned id) + --language, not --endpoint-id：arkcli +code-example --model <id> --language python(for details see ../arkcli-code-example/SKILL.md）
  • +deploy After successful creation,automaticallyrender the examples to ./ark-examples/<ep-id>/(by ep-id); if you want another copy by base model name, run +code-example
  • When the model is not activated, +deploy activation ishard-rejected under non-TTY,--yes is also not allowed；Do not fill in --yes / echo Y yourself / set ARKCLI_ALLOW_HEADLESS_ACTIVATION; activation (billing) must be handed back to a human to handle in the terminal / console
  • Speech models (TTS / ASR / podcast / voice / real-time voice interaction) being searchable in the marketplace does not mean they are deployable; when such a model is matched, stop at arkcli models search <keyword>, do not give the +deploy command

Model clarification in creation intent

As long as the user's ultimate goal is still "create / new / deploy Endpoint", even if a complete model ID has not yet been given, you must stay in the arkcli-deploy workflow;arkcli-models at this point is only a read-only candidate query capability for temporary invocation, and the creation task must not be rerouted into pure model discovery.

Candidates must come fromThis round ArkCLI's real-time structured output; completion from model memory, examples, or old version numbers is prohibited.

First determine the user's hard conditions and keywords; on the first attempt use models search "<keyword>" --size 10 --format json; if there are no keywords, omit it. Keywords use substrings of real names/families; capabilities and modalities use real flags; do not concatenate multiple natural-language concepts into a model name. If a complete result for this round already exists, reuse it.

  1. No model given at all: query by purpose/output modality; if there is no purpose, show real-time representatives for selection; do not list model names from memory.
  2. Only brand/family: recall using that family keyword; for empty results, first follow search's normalization and recovery chain to correct once; do not treat the brand as an exact ID.
  3. Candidate fields: read the real display_name/name/primary_version/lifecycle_status/input_modalities/output_modalities/create_time/update_time. For new integrations, prefer Published; exclude recommendations whose names explicitly indicate internal/test and those that are Shutdown/Retiring; unknown status does not mean deployable. Only concatenate when the version is non-empty name-version; do not guess dates; custom models retain cm-... identity.
  4. Sorting and coverage: by default, strictly sort in descending order by the real create_time , with the most recently created/published candidates first; only when the user explicitly asks for "recently updated" sort in descending order by update_time . It is prohibited to pin an old model to the top because of historical preference or because it was mentioned earlier in the context; you may remind in the question body, but must not change the order or invent "recommended/mainstay/flagship" labels. Do not pass off names, timestamps inside IDs, or search's default relevance as creation time; when time is missing/unparseable, mark it as unknown and do not fabricate sorting. When there is no preference, show 5–8 representatives, covering actually existing text, multimodal, image, and video; if there are hard task conditions, list only matches and do not mix in other tasks just to fill the count. label uses the original display name; description includes the full ID, modality, and status.
  5. 0/1/N: if 0, state it truthfully and ask one key follow-up condition; if 1, restate the real ID; if N, use the host-provided structured selection capability, stop before the user selects, and do not choose the first item for them. Do not create when only a query/command is requested.
  6. Recovery is not unlimited retrying: separate stderr from stdout and check the exit code. First read the complete JSON already saved by the tool; if there is truly no complete capture, the same read-only query may be re-fetched to a file, but options must not be generated from a truncated preview. If successful but empty, normalizing keywords or relaxing one non-hard preference is allowed, with explanation; authentication/permission failures are not treated as empty, and identity must not be switched. If it is still incomplete/no match, report the boundary and conditions to be supplemented; do not repeat blind queries.
  7. Return to the creation flow: only after selecting the exact target, read the required details/real request fields. Stop when the version or modality is explicitly unsupported; do not use activate to fix a wrong version. The user selecting a model does not equal approval to create; finally execute according to the shared authorization flow;+deploy does not support --dry-run, do not invent a preview flag.

For a concise field template, see search reference. The following is local sorting of the saved complete candidates, without adding new API requests:

jq '[.items[]
  | select(.lifecycle_status == "Published")
  | select((.name | test("internal|test"; "i")) | not)
  | {display_name,name,primary_version,lifecycle_status,input_modalities,output_modalities,create_time}]
  | sort_by(.create_time // "") | reverse' "$candidate_file"

First check whether the top-level items is an array and whether the key fields are complete; if time is missing, it can only be marked "time unknown". This projection is not a verification of account deployability; do not loop get/price endpoints for each candidate; only supplement the evidence needed to complete the current task.

Routing decision

  • The user wants to create / deploy an Endpoint, but the model is missing or only a brand / family name is given → still route to this arkcli-deploy skill; perform one real-time read-only query as in the previous section and let the user choose; do not create directly
  • User already has a model ID + wants to formally deploy → restate model/name/region; after confirmation, execute arkcli +deploy --name <ep> --model <id>
  • User wants to deploy / integrate a speech model, or the model name looks like *-tts-* / *-asr-* / seedasr-* → redirect to arkcli-models explaining "only square search is supported, Endpoint creation is not supported"
  • When the user passes a custom model ID (cm-xxxxx), before actually creating, first check whether there is already an Endpoint referencing that custom model with status Running ; if so, reuse it directly and output the existing endpoint-id, and will not create a second billable resource. This online reuse decision is also one of the reasons +deploy cannot provide a reliable offline Client Preview
  • User has an urgent tone and asks to "create immediately" → do not skip confirmation, restate model/name/region
  • has already obtained via arkcli infer endpoint create obtained Id → do notagain +deploy create a second one, redirect to arkcli-infer-endpoint; for a call example, redirect to arkcli-code-example(generated by model name)

anti-trigger (route elsewhere, attach the complete command to avoid downstream hallucination)

User intent Route to Complete example command
Just want to try the model effect / one-off generation arkcli-chat / arkcli-gen arkcli +chat --model <id> '...' or arkcli +gen --model <id> '...'
want a call example for a model arkcli-code-example arkcli +code-example --model <model-id> --language python(generated by model name/version; if version is missing, fall back to a static example or the console examples page)
Only want to discover / compare models, no Endpoint creation intent yet arkcli-models arkcli models search <keyword> or arkcli models list
Speech model deployment / TTS access point / ASR Endpoint arkcli-models arkcli models search <keyword>(square discovery only; Endpoint creation is currently not supported)
401 / authentication failure arkcli-auth arkcli auth status, if necessary arkcli auth login
profile / region / project does not match expectations arkcli-config For identity summary use arkcli auth whoami --format json; for default resources use arkcli resources list --format json. Only explicit Profile management uses the profile show/list
scripted / CI / need fine-grained control over each parameter, skip guardrails arkcli-infer-endpoint arkcli infer endpoint create --model <id> --name <ep>

Typical flow

  1. From model selection to formal integration：arkcli auth status → arkcli models search/get → restate and confirm the final model, name, and billing impact → arkcli +deploy ...(a custom model with an existing Running Endpoint will be reused)
  2. Switch from trial to formal integration：arkcli +chat / arkcli +gen verify the effect → restate the final parameters and confirm → actually create
  3. Do call integration after creation：+deploy has already automatically written the example to ./ark-examples/<ep-id>/, just use it directly; if you want to produce another copy by base model name, run arkcli +code-example --model <model-id> --language <lang>(if some versions have no example, fall back to ark-examples/ static example or the console examples page)

For detailed flags, JSON field examples, and error codes, see references/arkcli-deploy.md。

Reference