arkcli-plans

arkcli plans

CRITICAL — Before starting, you MUST first use the Read tool to read ../arkcli-shared/SKILL.md, which contains the authentication gate, configuration troubleshooting, and shared security rules. CRITICAL — Any plans buy / plans renew / plans personal rotate-apikey / plans team seat-assign / plans team rotate-apikey before execution, be sure to first use the Read tool to read the corresponding references/*.md, blind invocation is prohibited. CRITICAL — Token quota packages / Token resource packages are platform pay-as-you-go billing products, not the Agent Plan / Coding Plan managed by this skill. Do not invoke plans get/buy/renewbecause of the word "plan" or price wording; refer to arkcli-profile to explain platform + /api/v3 attribution.

The Agent Plan console's overage postpaid entry

When a user asks why the subscription page does not have an "Overage Postpaid Management" button, this is a console plan issue, not a arkcli helper local TTY matrix issue. First use arkcli plans get to verify whether the current identity holds an active Agent Plan personal edition or team edition; when the control plane query fails, truthfully state that the subscription status is unknown, and do not treat a credential error as not subscribed. Then read the officialOverage Postpaid Managementbody text to verify the current page path and prerequisites, and do not use Helper status to replace console page facts.

The official personal edition documentation places the entry inthe Agent Plan page under Activation Managementin the "Plan Information" area; after entering, models and Harness can be managed separately. What the user calls the "subscription page" may be this Agent Plan page, and you must not assert that "the subscription page does not/should not have a button"; first give the exact page and area from the documentation, then verify the page the user is actually on. Model overage postpaid requires first activating the model service under "Activation Management", and enabling overage postpaid also requires real-name verification. Harness can also be managed in the corresponding card on that page; turning off that Harness's plan deduction will simultaneously turn off its overage postpaid. First ask clearly whether it is the personal edition or enterprise edition and the model service activation status; for the team edition, additionally verify the administrator's authorization rules for seats, and do not directly apply personal edition prerequisites to the enterprise edition. The CLI cannot observe whether a Web button is actually rendered, and cannot assert based solely on documentation that a certain prerequisite is the root cause of this missing button; the user needs to provide the page status or the console needs to troubleshoot. Only provide guidance, and do not enable real billing switches on behalf of the user.

Agent Plan model disappearance and retirement notices

When the user explicitly says that an old model in Agent Plan is gone, or asks whether to reconfigure after a retirement SMS, first read the official Agent Planmodel retirement announcementinthe row for that model and newer subsequent migration rows, and directly deliver the announcement's stop-for-new-users time, official service shutdown time, and recommended migration model; do not cross-check the Coding Plan model overview or exhaust this round on multiple irrelevant documents. The announcement is a product timeline, not a real-time query of the current account; when the user asks "can I still use it now", then use arkcli plans model-list --plan agent-plan --format json to verify this account's list, and if it fails, clearly state that the real-time status is unknown, do not treat an STS error as the model being unavailable, and do not overturn the plan retirement announcement just because the model marketplace still shows Published.

When asked "do I need to reconfigure", distinguish by configuration type: those using auto/ark-code-latest and other automatic routing generally do not need to change the fixed model name in the tool; those with an old Model Name hardcoded in the tool need to change it before service shutdown tocurrently still supportedgoal and verify; for self-built instances bound to the old model, ep-... additionally need to check and migrate the Endpoint. You cannot infer which configuration the user has from the existence of a subscription or the announcement itself; when the user's configuration/resources cannot be read, provide conditional operations and do not change the configuration or create an access point on the user's behalf. If the migration model recommended by the announcement also enters a subsequent deprecation period, the migration chain updated in that announcement and the current support list shall prevail, and the old recommendation shall not be treated as permanently available.

Step-by-step parameter collection for purchase intent and failure re-entry

When purchase information is missing, converge one item at a time in a fixed order, and do not pile all questions into the same round:

First ask for the plan family:Agent Plan or Coding Plan。
Then ask for the version and tier: list only the personal edition tiers of the selected family and one enterprise/team edition entry. The personal edition choice simultaneously determines --plan and --type; the enterprise entry only determines the team --plan。
After choosing the enterprise/team edition, ask separately for the tier in the same family --type, then ask separately for the number of seats --quantity. Agent Plan tiers are small/medium/large/max, Coding Plan is lite/pro。
Finally ask for the duration --duration, and once all are collected, proceed to agreement confirmation.

Tier options must state the current price, typical scenarios, and key limitations, and be checked against the tier descriptions in buy's tier descriptions for the source; do not display only bare tier names; unknown prices/benefits must be explicitly marked as unconfirmed. For duration, 1 / 3 / 6 / 12 month quick options may be provided, but other valid integers within 1–12 are still accepted.

When multiple items are missing at the same time, in the current round ask only about the first unknown decision in the above order. If the host has structured selection capability, prefer to use it, but generic Skills must not hard-code tool names; if not available, fall back to short option text. When all parameters are already clear and the user only wants the command, provide only the first agreement gate command without --yes , and do not execute it.

"Ask only one decision in the current round" also limits the information that may be shown in the current round: list only the options and necessary differences for that layer, and do not leak the option names, valid values, or flags of subsequent layers in explanations, parentheses, examples, or next-step previews. For example, when the plan family has not yet been determined, the reply may contain only Agent Plan and Coding Plan and a brief difference between the two, and must not simultaneously list personal/team,small/medium/large/max、lite/pro, duration, or number of seats. After the user answers the current layer, show the next layer in the next round.

payment_failed and returning an Order ID indicates that the order has already been persisted. You must repeat that Order ID and guide the user to the console to complete payment or cancel this order; do not re-collect parameters, do not execute plans buy / plans renew, and do not use billing records as the payment re-entry point for an existing order.

ProductStockNotEnough indicates insufficient inventory, not a parameter error; do not retry, do not re-ask for confirmed parameters, do not switch tiers or split the order, and follow the failure semantics in buy's failure semantics to deliver the corresponding plan console handling entry. A transport error likewise preserves the current round's parameters, and the purchase wizard must not be restarted.

Renewal does not reselect the tier: first confirm --plan and the number of renewal months; for the team edition, select from the current seat list --seat-ids; reuse the original subscription/seat tier, and do not pass the purchase-specific --type or --quantity. Do not repeatedly ask for parameters the user has already stated clearly. For price inquiry only, use pricing plans or the corresponding command's --estimate, and do not place an order.

After the agreement gate returns, include this plan, tier, duration, seat range, and actual paid price total_amount_cny Deliver together with the original price (if any); prices and entitlements are subject to the current response, and do not use historical example prices to promise discounts, video eligibility, or validity periods. A timeout/connection interruption cannot prove that "the order was not placed or no charge was made": keep the error and any existing order/seat ID, verify the order status first, and do not automatically replay billing write operations.

🔒 Protocol gate (mandatory flow for plans buy / plans renew)

plans buy / plans renew isbilling write operation, add --yes for an actual charge.When neither --yes nor --estimate is passed, the CLI does not place an order, but returns:

{
  "status": "agreement_required",
  "agreements": [{"title": "...", "url": "..."}, ...],
  "next_step": "arkcli plans buy ... --yes"
}

The Agent must strictly execute in the following order:

The first call must not include --yes — obtain the agreements array
Item by itemdisplay each agreement's title and url to the end user (cannot omit, cannot merge)
Wait for the user toexplicitly statethat they have read and agree to all agreements (for example, "I have read and agree", "OK I agree", or other clear statements);cannotpass by default with vague answers ("okay", "mm")
Only after confirmation can you add --yes and rerun the command in the next_step field (just copy next_step directly; the flag has already been echoed back in full)

Violating this flow = helping the user skip a legal compliance step. This is equivalent to the "I have read and agree to 《...》" checkbox in the frontend purchase panel — it can only be checked after a real person has reviewed it.

--estimate is the online inquiry path; it does not place an order and does not require agreement confirmation; it is not Client Preview. When the user ultimately proceeds with --yes for a real order, they still need to review the agreements first.

Business positioning

arkcli plans manages two types of ARK plans:

Agent Plan(agent-plan / agent-plan-team): agent invocation plans, tiered by tier (small/medium/large/max)
Coding Plan(coding-plan / coding-plan-team): coding assistance plans, tiered by tier (lite/pro)

Both types of plans have personal subscriptions and enterprise/team seats, but Key sources cannot be treated uniformly by personal/team：

Profile type	Resource unit	Key source and rotation entry	OpenAI-compatible data plane Base URL path
`agent-plan` personal edition	Personal subscription	`Scene=RealAgentPlanPersonal` dedicated Key; only this type can use `plans personal rotate-apikey`	`/api/plan/v3`
`coding-plan` personal edition	Personal subscription	shared with `platform` the regular API Key pool; handled at the regular Key management entry,there is no Coding Plan personal edition dedicated Key	`/api/coding/v3`
`agent-plan-team`	Enterprise seat	Key of the currently Running seat; manage with `plans team rotate-apikey` Management	`/api/plan/v3`
`coding-plan-team`	Enterprise seat	Key of the currently Running seat; manage with `plans team rotate-apikey` Management	`/api/coding/v3`

personal has one subscription per account; team is managed at the seat (SeatID) granularity, with each seat bound to one sub-user.

This skill does not include plan usage / quota queries("how much has been used / how much is left / what day it refreshes / breakdown by model").plans get It only answers "which plans do Ihold+ status (Effective/Running)", and does not answer "how much has been used". The quota view is in ../arkcli-usage/ — see the "Quick Decision" routing table below.

Evidence boundaries for plan resources and access configuration

plans model-list lists the plan text/routing models,not a complete catalog of image and video resources. When a user asks "Can my Agent Plan generate images / which image models are available", first from this round's arkcli auth status --format json of the profiles_summary[] by type=agent-plan / agent-plan-team find the actual name, then execute arkcli resources list --profile <完整 name> --modality image --format json, read items[].id、resource_kind、invocable and is_default。--profile must be filled with the complete Profile name, not agent-plan a type literal like that; multiple candidates of the same type require verifying identity/project, and guessing is not allowed. Do not, because plans model-list has no Seedream, answer "image generation is not supported", and do not treat the example count as the current entitlement.
"Access points under a Coding Plan" must distinguish between subscription, text routing, and ep-xxx inference access points:ark-code-latest is a plan model routing alias,not an ep-xxx Endpoint. Use the corresponding Coding Plan Profile's resources list --modality text --format json to verify items[].resource_kind / id before answering whether ep-xxxexists; do not use plans get to find a subscription and thereby overturn the candidate conclusion of "no access point". Coding Plan's image/video goes through the platform Endpoint pool and pay-as-you-go Key separately, see arkcli-resources。
When configuring a Plan for the SDK, Claude Code, OpenCode, etc., first confirm the Profile type: Agent Plan's data plane is /api/plan/v3, Coding Plan is /api/coding/v3; ordinary platform is /api/v3. A personal Agent Plan exclusive Key, the ordinary pool Key used by a personal Coding Plan, and a team seat Key must not be mixed; confirm only from this round's identity/Key metadata and the corresponding Profile type matrix, and do not point one plan's Key at another billing path.
plans model-list The display name returned is model_name, and the model in the Plan data plane and Agent configuration should preferably be filled with output_name(such as the actually returned auto or a name without a date suffix), and only when that field is empty fall back according to the model-list field convention ; the versioned model_id is mainly used for precise queries/routing target control-plane writes, and one must not see selected_model_id and directly copy it into the client environment variable. When a user pastes a configuration template, count the placeholder fields one by one, and do not fabricate slots that do not appear.
When a user asks "Where is my Plan Key / how do I get it", first go to arkcli-auth 's Key query and delivery to locate the target;apikey.get_raw/profile apikey get can conditionally provide read capability,do not claim that the CLI can only rotate and cannot read existing Keys. Export is subject to Access and host restrictions, and failures should be reported truthfully; a failed query must never automatically trigger a destructive rotation, and the complete Key must not be echoed in chat.

Applicable scenarios

View which plans the current account holds → plans get
Place an order to buy a plan (including personal / team) → plans buy
Renew an existing plan → plans renew
View the list of models supported by the plan → plans model-list
Switch the routing target of ark-code-latest (Auto intelligent scheduling or a specific shadow model) → plans model-apply
Rotate the Agent Plan personal edition exclusive APIKey → plans personal rotate-apikey; the Coding Plan personal edition ordinary Key does not use this command
List / filter enterprise edition seats → plans team seat-list
Bind an Enterprise seat to a sub-user → plans team seat-assign
Rotate the Enterprise seat's APIKey (yourself or admin in bulk) → plans team rotate-apikey
Check whether the dedicated Harness capability is installed on the local AI Agent (read-only) → plans harness-status: report Doubao Search / professional datasets / Agent memory (MCP) per the capability card, plus globalVolcano Engine Supabase(whether CLI+Skill are installed). "Is my supabase / MCP set up" all goes here (the Agent memory card is Personal edition only agent-plan; Team edition reports absent is expected, not a missing install, see its reference)

anti-trigger signal

Only ask about plan used/remaining quota, refresh time, or seat usage → arkcli-usage, not plans get。
To read/inject the value of an existing API Key rather than rotate → arkcli-auth 's Key query flow; do not call for read-only needs plans personal/team rotate-apikey。
To create or manage a regular ep-xxx endpoint → arkcli-deploy / arkcli-infer-endpoint; Plan holding or ark-code-latest routing information cannot replace an Endpoint query.

Quick decision

User asks "what plans do I have / what am I subscribed to": directly arkcli plans get, zero parameters (holds list + status only, no usage）
User asks "when does it expire / how many days are left": first read get's expiration time rules; only verify the corresponding upstream time field in an environment where debug can be safely captured and redacted, and deliver in Beijing time (UTC+8). Do not directly echo debug, and do not treat Usage's quota refresh time as the subscription expiration time.
User asks "how much have I used / how much is left / what date does it refresh / in-plan vs out-of-plan" —— not in this skill, go to ../arkcli-usage/：
- "how much of my plan is left / what date does it refresh" → arkcli usage plan or arkcli usage balance --type plan
- "which model do I use most / in-plan vs out-of-plan ratio" → arkcli usage plan-details
- "team seat usage" → arkcli usage seats --product agent-plan-team --with-usage
User asks "what models does Agent Plan / Coding Plan support":arkcli plans model-list --plan <plan>
User wants to "switch the underlying model of ark-code-latest / change to Auto intelligent scheduling / lock to a specific model":arkcli plans model-apply --plan <plan> --model <model-id|output-name|auto>（write operation, linked with the console; for optional items first plans model-list confirm)
User wants to "buy a plan": read buy.md, collect all --plan、--type、--duration, for Team edition also collect --quantity, do not make the choice for the user
User wants to "renew a plan": read renew.md, confirm --plan, renewal months, for Team edition also select an existing --seat-ids; keep the original tier, do not pass --type / --quantity
Blocked when using plan plan_agreement_required(first-use signing for third-party channel orders): see references/arkcli-plans-agreement-signing.md；Prohibitedto arbitrarily set ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT to sign on behalf of the user; guide the user to complete signing in an interactive terminal
Returns when using plan plan_agreement_status_unavailable: signing status not yet confirmed, check network and login status and retry;--yes and ARKCLI_ALLOW_HEADLESS_PLAN_AGREEMENT both cannot bypass this error
User wants to "reset / rotate APIKey": distinguish Personal edition from Enterprise edition, refer to the corresponding reference;write operation, the original APIKey is invalidated immediately, must follow the reference for secondary confirmation (unless the user explicitly wants --yes to skip)
User wants "check seats / view team seat binding status / who is bound to which seat / list seats / which seats are activated / team seat admin view" → plans team seat-list --plan <agent-plan-team|coding-plan-team>(This is the default entry point for seat management, management view lists basic info + binding relationships,without usage numbers; to see how many tokens each seat has used / plan percentage → arkcli usage seats --with-usage)
User wants "assign seats to employees / assign a seat to an employee / unbind a seat"→ plans team seat-assign, first prepare the seat-id=user-id pairing list
Useronly knows the employee usernamebut not the exact UserID: first arkcli iam userid --username <prefix> look up to user_id, then feed to seat-assign --bind seat-id=<user_id>

Agent quick execution order

First confirm authentication status:arkcli auth status; if missing, go through ../arkcli-auth/
Read operations (get / model-list / seat-list) execute directly; only consider the current identity when the user asks about "my"
Write operations (buy / renew / rotate-apikey / seat-assign / model-apply） always:
- first read the corresponding reference
- confirm key fields with the user (plan / type / duration / SeatIDs / UserID pairing)
- rotate-apikey by default do not pass --yes, let the CLI go through [Y/N] secondary confirmation
Partial failure (per-item Success/Failed array) is a valid return; when exit code is non-zerodo notdirectly treat it as total failure, first check success_count / failed_count in stdout

Write operation risk checklist (required reading)

Command	Risk	Required action
`plans buy`	Billing，`IsAutoPay=true` automatic deduction	must first go through the agreement gate without `--yes` → show agreements to the user → after the user explicitly agrees, add `--yes`. See Agreement gate process
`plans renew`	Billing, automatic deduction	Same as buy agreement gate; team version must pass `--seat-ids`
`plans personal rotate-apikey`	The original APIKey becomes immediately invalid	Default to [Y/N] confirmation; remind the user to replace the harness configuration accordingly
`plans model-apply`	Change the plan request routing target (takes effect immediately, linked with the console)	Non-interactive must explicitly pass `--model`; first use `plans model-list` to confirm available targets; team version will error if there are no seats
`plans team seat-assign`	Modify seat binding relationships	Explicit `--bind seat-id=user-id`, automatically call IAM to look up UserName
`plans team rotate-apikey`	The original APIKey becomes immediately invalid	self-rotate defaults to agent-plan-team; admin batch passes `--seat-ids`

Command list

Command	Type	Description
`plans get`	Read	List the plans held by the current account (personal + team aggregated)
`plans buy`	Write (billing)	Place an order to purchase a plan
`plans renew`	Write (billing)	Renew an existing plan
`plans model-list`	Read	List the models supported by the plan; for display use `model_name`, for Plan configuration prefer `output_name`, for current routing see `selected_model_id` / `selected`
`plans model-apply`	Write	Set the ark-code-latest routing target (auto or a specific shadow model)
`plans personal rotate-apikey`	Write (destructive)	Rotate Agent Plan Personal Edition APIKey
`plans team seat-list`	Read	List Enterprise Edition seats + multi-dimensional filtering
`plans team seat-assign`	Write	Batch bind Enterprise Edition seats to sub-users
`plans team rotate-apikey`	Write (destructive)	Rotate Enterprise Edition seat APIKey (self / admin batch)
`plans harness-status`	Read	Check the installation status of the Agent Plan built-in MCP on the local AI Agent (claude-code/codex/opencode/openclaw/trae) (read-only, no login required)

Common fallbacks

Authentication error: go to ../arkcli-auth/SKILL.md
Incorrect region / project: go to ../arkcli-config/SKILL.md
Want to see plan usage / quota (used / total / percent / reset_at / broken down by model): go to ../arkcli-usage/SKILL.md — this skill only answers "what is held", not "how much has been used"
Want to see bills / settlement amounts: go to ../arkcli-billing/SKILL.md — plans does not involve payment
Want to generate a model call example: go to ../arkcli-code-example/SKILL.md
Trying out a model without planning a formal deployment: go to ../arkcli-chat/SKILL.md / ../arkcli-gen/SKILL.md
When there is no ready-made product command, fall back to ../arkcli-api-explorer/SKILL.md
Want toinstall / inject / remove MCP (not viewing status): go to ../arkcli-helper/SKILL.md — plans harness-status read-only viewing, does not modify configuration

Reference

arkcli-shared -- authentication / global parameters / output rules
arkcli-usage -- planusage / quotaview (usage plan / usage plan-details / usage balance / usage seats --with-usage), complementing this skill's "hold / purchase / seat management"
arkcli-billing -- plansettlement amount(Volcano billing center split accounting, T+1)
arkcli-deploy -- after purchasing the plan, use +deploy to deploy the endpoint
arkcli-helper -- for AI Agent inject / remove Agent Plan built-in MCP (plans harness-status read-only viewing; injection changes go here)