@byteplus/ark-cli-darwin-x64 0.0.0-stage → 1.0.46-prerelease.dc921200a42d

package/skills/arkcli-pricing/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: arkcli-pricing
+version: 1.0.0
+description: "Queries BytePlus ModelArk foundation model settlement unit prices (including current-account discounts) and CodingPlan subscription prices. Price is the final unit price after account contract / promotion / plan discounts; OriginalPrice is the published list price. Invoke for model prices, pricing, unit prices, Coding Plan prices, plan prices, discounted prices, token billing, cross-modality price comparisons, or model free quotas. Anti-trigger: TTS/ASR/voice model pricing is unsupported; do not use Audio pricing and clearly state that it is unsupported."
+metadata:
+  requires:
+    bins: ["arkcli"]
+  cliHelp: "arkcli pricing --help"
+---
+
+# arkcli pricing
+
+**CRITICAL — Before starting, you MUST use the Read tool to read [`../arkcli-shared/SKILL.md`](../arkcli-shared/SKILL.md), which contains authentication gates, configuration troubleshooting, and shared safety rules.**
+
+## Applicable scenarios
+
+- Query settlement unit prices for foundation models (input / output / batch inference / context cache and other ChargeItems).
+- View free quotas (`InferenceFreeUsage`, `ResourcePackItems`) and overdue status (`IsOverdue`).
+- View sub-service activation states (`SubServices`: `base` / `context-cache`).
+- Filter the pricing catalog by modality.
+- Query **CodingPlan subscription prices** (personal + enterprise, four tiers in total).
+
+## Business positioning
+
+- **The two pricing categories are managed separately**: **model pay-as-you-go pricing** (`pricing models`) and **plan subscription pricing** (`pricing plans`) are completely independent commands. See "Models vs plans" below for the decision.
+- This covers only catalog pricing for **foundation models**. However, a base model's ChargeItems are **comprehensive**: they include foundation model inference prices, training rates when the model is used for fine-tuning (`Finetune` / `LoraFinetune`), and inference prices for custom models produced by fine-tuning (`FinetuneInference*` / `FinetuneI2I*`, and others). Therefore, querying a base model once returns all related rates.
+- The **backend API** does not return separate entries for custom models (fine-tuned `cm-*` models), because their rates are embedded in the base model's ChargeItems array. However, **arkcli provides reverse-lookup convenience**: `pricing models --model cm-xxx` automatically calls GetCustomModel to obtain the base name and then queries pricing. The top-level response also includes `resolved_custom_model` (`customization_type` + `foundation_model_name` / `foundation_model_version`). The Agent can use it to select the corresponding ChargeItem.Type without manually performing a two-step lookup.
+- Endpoint-level actual consumption is not covered → use [arkcli-usage](../arkcli-usage/SKILL.md).
+- **Rate limits / token limits / context windows are not included**. Those belong to `arkcli-models`; route to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md). Pricing handles only "money".
+- does not offer Agent Plan, do not run `arkcli pricing plans` and do not present Coding Plan prices as Agent Plan prices.
+- **Voice model pricing is not covered**: TTS / ASR / dubbing / reading / podcast / voice / real-time voice interaction models are currently unsupported in arkcli. Do not use `pricing models --model` or `--modality Audio` to answer their prices.
+- **Price = the final unit price including the current account's discount** (already calculated by the backend based on contracts/promotions/plans). No client-side discount calculation is needed.
+- **OriginalPrice = the published list price**. `Price < OriginalPrice` indicates that the account has a discount.
+
+## Commands
+
+| Command | Description |
+|------|------|
+| [`pricing models`](references/arkcli-pricing-models.md) | List the foundation model settlement pricing catalog (pay-as-you-go, token-based billing). |
+| [`pricing plans`](references/arkcli-pricing-plans.md) | List subscription plan prices (CodingPlan personal + enterprise). |
+
+## Models vs plans: which command to use
+
+**Is the user asking for "a unit price calculated by token" or "a monthly plan price"? This is the key distinction.**
+
+| User wording | Use | Reason |
+|---|---|---|
+| "How much does DeepSeek-V4 cost?" / "How much is dola-seed?" / "GPT-X price" | `pricing models` | Model name → token-based billing |
+| "How much does image-to-image cost per image?" | `pricing models` | Per-call billing in ChargeItems |
+| "How much is audio recognition per minute?" / "How much is TTS?" / "Voice model pricing" | `arkcli-models` | arkcli currently supports only voice model marketplace discovery, not pricing queries |
+| "How much does fine-tuning cost?" / "How much does it cost to fine-tune a model?" | `pricing models` | Fine-tuning rates are embedded in the base model's ChargeItems (see `Finetune` / `LoraFinetune` types) |
+| "How much does my cm-xxx cost to invoke?" / "How much is this fine-tuned model?" | `pricing models --model cm-xxx` | The CLI automatically resolves the base model + exposes `resolved_custom_model.customization_type`; select the ChargeItem according to the table below |
+| "How much is Coding Plan?" / "lite / pro plan price" | `pricing plans` | Plan name → monthly subscription |
+| "Coding Plan enterprise price" / "How much is the team edition?" | `pricing plans --edition enterprise` | Same as above |
+
+Ambiguity fallback: if the user asks "How much is X?" and X is a model name → models; if X is a plan name → plans; if it resembles neither → first run `pricing plans` to list all four plan tiers and check for a match, then fall back to models.
+
+## `--modality` value mapping (translated by the Agent)
+
+The backend `FoundationModelDomain` field has **five coarse-grained enum values**. arkcli passes them through without translation. When the user says "video / image / text" in natural language, you (the Agent) must translate it before passing the value:
+
+| User may say | Actual backend enum | Note |
+|---|---|---|
+| Text / LLM / language model | `LLM` | |
+| Image / picture / vision | `ComputerVision` | |
+| Video | `ComputerVision` | ⚠️ The backend does not distinguish image/video/3D and **returns image and 3D models** |
+| 3D / hyper3d | `ComputerVision` | Same as above |
+| Audio / voice / TTS / ASR | Do not query | `Audio` is a backend enum, but this arkcli skill does not use it to answer marketplace voice model pricing; only state that it is unsupported |
+| Vector / embedding | `Embedding` | |
+| Routing / router | `Router` | |
+
+**Important**: When the user asks "How much does video cost?", you should:
+1. Run `arkcli pricing models --modality ComputerVision` (do not pass `--modality video` directly).
+2. Filter video models from the response (using `DisplayName` or `FoundationModelTag`), or explicitly tell the user that "the backend returns the broad vision category, including image / video / 3D."
+
+## Key `ChargeItem.Type` enum mapping (required for response parsing)
+
+Each base model's `ChargeItems` is **comprehensive** and may mix rates for base inference, fine-tuning training, fine-tuned inference, and generation tasks. The Agent should select only the 1–2 entries relevant to the user's question.
+
+| User question semantics | Type to select |
+|---|---|
+| Inference price | `InferencePrompt` + `InferenceCompletion` |
+| Batch inference price | `BatchInferencePrompt` + `BatchInferenceCompletion` |
+| Context cache price | `ContextSessionHit` + `ContextSessionStorage` |
+| Fine-tuning price | `Finetune` (full) or `LoraFinetune` (LoRA) |
+| Price to invoke a fine-tuned model | `FinetuneInferencePrompt` + `FinetuneInferenceCompletion` |
+| Image-to-image price (base model) | `T2ICompletion` / `I2ICompletion` |
+| Image-to-image price (fine-tuned model) | `FinetuneT2ICompletion` / `FinetuneI2ICompletion` |
+| Video generation | `T2VCompletion` / `I2VCompletion` / `V2VCompletion` (and 1080/4K variants) |
+| 3D generation | `To3DCompletion` / `FinetuneTo3DCompletion` |
+
+For the complete Type enum, see "Complete ChargeItem.Type enum mapping" in [`references/arkcli-pricing-models.md`](references/arkcli-pricing-models.md).
+
+## CustomizationType → ChargeItem.Type mapping
+
+The top-level response from `pricing models --model cm-*` includes `resolved_custom_model.customization_type`. Select the rate accordingly. For the complete mapping table, see "Custom model (cm-*) reverse lookup" in [`references/arkcli-pricing-models.md`](references/arkcli-pricing-models.md).
+
+## Quick decisions
+
+- User asks "How much does model X cost?": `arkcli pricing models --model X`; select `InferencePrompt` / `InferenceCompletion` from `ChargeItems`.
+- User asks "How much does my cm-xxx cost?": `arkcli pricing models --model cm-xxx`; inspect `resolved_custom_model.customization_type` → select the corresponding `Finetune*` entry using the mapping above; also tell the user its base model from `resolved_custom_model.foundation_model_name`.
+- User asks "Prices for all LLMs": `arkcli pricing models --modality LLM`.
+- User asks "How much does a TTS / ASR / voice model cost?": do not run pricing; clearly state that pricing queries are currently unsupported.
+- User asks "How much is Coding Plan?": `arkcli pricing plans` to list all four tiers, or add `--plan coding-plan-personal-lite` for one tier.
+- User asks "What free quota do I have?": `pricing models`; inspect `InferenceFreeUsage` and `ResourcePackItems[Type=FreeInference]`.
+- User asks "Does my account have a discount?": compare `Price` and `OriginalPrice`; the difference is the discount (supported by both commands).
+- User asks "What is my actual consumption?": this is not a pricing question; route to [arkcli-usage](../arkcli-usage/SKILL.md).
+- **No permission for enterprise plans**: `pricing plans` fills the `error` field for the two enterprise rows with `AccessDenied: ...`, while the two personal rows return normally. This is expected behavior, not a bug.
+
+## Common fallbacks
+
+- Authentication error: route to [`../arkcli-auth/SKILL.md`](../arkcli-auth/SKILL.md).
+- The user asks about consumed usage rather than unit prices: route to [`../arkcli-usage/SKILL.md`](../arkcli-usage/SKILL.md).
+- The user asks about voice model pricing / TTS pricing / ASR pricing: route to [`../arkcli-models/SKILL.md`](../arkcli-models/SKILL.md), and only explain that the models can be discovered in the marketplace and that arkcli currently does not support pricing queries.
+
+## References
+
+- [arkcli-usage](../arkcli-usage/SKILL.md) — Actual token / request consumption (including historical ranges)
+- [arkcli-deploy](../arkcli-deploy/SKILL.md) — Create an Endpoint (automatically checks activation before deployment)
+- [arkcli-shared](../arkcli-shared/SKILL.md) — Authentication and global parameters

package/skills/arkcli-pricing/references/arkcli-pricing-models.md

@@ -0,0 +1,258 @@
+# pricing models
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List the settlement unit price catalog for ARK foundation models. `Price` is the **final unit price (including discounts)** calculated by the backend according to the current account's contract / promotions / plans; `OriginalPrice` is the published list price.
+
+**Voice models are unsupported**: For TTS / ASR / dubbing / podcast / voice / real-time voice interaction, do not query prices with `pricing models --model` or `--modality Audio`. Clearly state that voice models are unsupported.
+
+## Commands
+
+```bash
+# List all foundation models (default PageSize=50, PageNumber=1)
+arkcli pricing models
+
+# Query one foundation model
+arkcli pricing models --model deepseek-v4-pro
+
+# Query one custom model (a fine-tuned cm-* model)
+# The CLI first calls GetCustomModel to resolve the base model, then performs the standard catalog query;
+# the top-level response includes an additional resolved_custom_model field
+arkcli pricing models --model cm-20260611124416-77wrq
+
+# Filter by modality (backend FoundationModelDomain enum)
+arkcli pricing models --modality LLM
+arkcli pricing models --modality ComputerVision
+arkcli pricing models --modality Embedding
+
+# Pagination
+arkcli pricing models --page-size 20 --page-number 2
+
+# Specify the pricing region (defaults to the current profile region)
+arkcli pricing models --region ap-southeast-1
+```
+
+## Parameters
+
+### Optional filters
+
+| Parameter | Type | Description |
+|------|------|------|
+| `--model` | string | One foundation model name (such as `dola-seed-2-1-turbo` / `deepseek-v4-pro`) or custom model ID (`cm-*`). The CLI automatically resolves the base model for `cm-*` and adds `resolved_custom_model` to the response |
+| `--modality` | string | Backend `FoundationModelDomain` enum; **aliases are not accepted**: `LLM` / `ComputerVision` / `Audio` / `Embedding` / `Router` |
+| `--region` | string | Pricing region; defaults to the current profile region |
+| `--page-number` | int | Page number, 1-based, default 1 |
+| `--page-size` | int | Number of entries per page, default 50 |
+
+### Using `--modality`
+
+The backend `FoundationModelDomain` field **does not distinguish** image / video / 3D; they all belong to `ComputerVision`.
+
+| User semantics | Value to pass | Note |
+|---|---|---|
+| Text / large language model | `LLM` | |
+| Image generation / image | `ComputerVision` | Includes image / video / 3D |
+| Video generation | `ComputerVision` | Same as above; requires secondary client-side filtering |
+| Audio / voice | Do not query | `Audio` is a backend enum, but this arkcli skill does not support voice model pricing queries |
+| Vector | `Embedding` | |
+| Intelligent routing | `Router` | |
+
+⚠️ Do not pass natural-language aliases such as `text` / `video` / `image`. arkcli passes the value unchanged to the backend, while the backend recognizes only five enum values, resulting in an empty result or an error.
+
+## Return value
+
+JSON structure (selected key fields):
+
+```json
+{
+  "page_number": 1,
+  "page_size": 50,
+  "total_count": 75,
+  "items": [
+    {
+      "FoundationModelName": "deepseek-v4-pro",
+      "DisplayName": "DeepSeek-V4-pro",
+      "VendorName": "DeepSeek",
+      "State": "Available",
+      "ChargeItems": [
+        { "Type": "InferencePrompt",     "Price": 0.012, "OriginalPrice": 0.012, "UnitCode": "k tokens" },
+        { "Type": "InferenceCompletion", "Price": 0.024, "OriginalPrice": 0.024, "UnitCode": "k tokens" },
+        { "Type": "ContextSessionHit",   "Price": 0.001, "UnitCode": "k tokens" },
+        { "Type": "ContextSessionStorage","Price": 0.000017, "UnitCode": "k tokens/hour" },
+        { "Type": "BatchInferencePrompt","Price": 0.006, "UnitCode": "k tokens" },
+        { "Type": "BatchInferenceCompletion","Price": 0.012, "UnitCode": "k tokens" }
+      ],
+      "InferenceFreeUsage": { "Total": 500000, "Consumed": 0 },
+      "ResourcePackItems": [
+        { "Type": "FreeInference", "Total": 500000, "Consumed": 500000 }
+      ],
+      "SubServices": [{ "SubService": "base", "Status": "Available" }],
+      "IsOverdue": false
+    }
+  ]
+}
+```
+
+## Key field definitions
+
+| Field | Meaning |
+|---|---|
+| `Price` | **Discounted unit price for the current account** (the backend has applied contracts/promotions/plans); the Agent should display this value directly |
+| `OriginalPrice` | Published list price. `Price < OriginalPrice` indicates a discount; the difference/ratio can describe the discount amount |
+| `UnitCode` | Billing unit, commonly `k tokens`; storage uses `k tokens/hour` |
+| `Type` | ChargeItem type (see the table below). When reporting inference prices, normally show only `InferencePrompt` + `InferenceCompletion` |
+| `State` | Whether the model is available to the current account (`Available` / `Unavailable`) |
+| `InferenceFreeUsage` | Free inference quota: `Total` total amount, `Consumed` consumed amount |
+| `ResourcePackItems` | Resource pack consumption; type `FreeInference` is the free inference resource pack |
+| `SubServices` | Sub-service activation state (`base` / `context-cache`), related to `--moderation` and caching behavior in [arkcli-deploy](../../arkcli-deploy/SKILL.md) |
+| `IsOverdue` | true indicates overdue payment, which affects inference call success |
+| `MultiChargeItems` | Tiered pricing (by token-length range), available for a few models |
+| `resolved_custom_model` | Appears **only when `--model` is passed a cm-*** (top-level field, not inside items); see the next section |
+
+## Custom model (cm-*) reverse lookup
+
+The backend `ListModelChargeItems` does not index custom model entries. Rates for fine-tuned cm-* models are embedded in the base model's ChargeItems with `Finetune*`-prefixed types. The CLI performs the reverse lookup for the user:
+
+**Trigger condition**: `--model` receives any string beginning with `cm-`.
+
+**Execution flow**:
+1. The CLI first calls `custom_model.get_custom_model { Id: "cm-xxx" }`.
+2. It obtains `FoundationModel.Name` / `FoundationModel.ModelVersion` / `CustomizationType` from the result.
+3. It runs the standard `ListModelChargeItems` query using the base name.
+4. Response `Items` contains all ChargeItems for the base model (**not trimmed**), and the top level includes an additional `resolved_custom_model`.
+
+**Additional response field**:
+
+```json
+{
+  "resolved_custom_model": {
+    "id": "cm-20260611124416-77wrq",
+    "customization_type": "FinetuneSft",
+    "foundation_model_name": "dola-seed-2-1-turbo",
+    "foundation_model_version": "260628"
+  },
+  "page_number": 1,
+  "page_size": 50,
+  "total_count": 1,
+  "items": [ /* all ChargeItems for the base model; the Agent selects Finetune* entries */ ]
+}
+```
+
+**ChargeItem selection for the Agent (by `customization_type`)**:
+
+| customization_type | Invocation rate (select these two when asked about cm-* inference price) | Training rate (select this when asked about the cost to train it) |
+|---|---|---|
+| `FinetuneSft` (full SFT) | `FinetuneInferencePrompt` + `FinetuneInferenceCompletion` | `Finetune` |
+| `FinetuneLoRA` / `DPOLoRA` / `GRPOLoRA` / `OPDLoRA` | `FinetuneInferencePrompt` + `FinetuneInferenceCompletion` | `LoraFinetune` |
+| `DPO` / `GRPO` / `PPO` / `OPD` (full RL) | `FinetuneInferencePrompt` + `FinetuneInferenceCompletion` | `Finetune` |
+| `Pretrain` | `FinetuneInferencePrompt` + `FinetuneInferenceCompletion` | `Finetune` |
+
+> Invocation rates for cm-* models fine-tuned for vision/video use `FinetuneT2ICompletion` / `FinetuneI2ICompletion` / `FinetuneT2VCompletion` / `FinetuneI2VCompletion` / `FinetuneTo3DCompletion`, and others. See the complete ChargeItem.Type enum mapping below.
+
+**Reverse-lookup errors**:
+- `cm-xxx` does not exist → `GetCustomModel "cm-xxx": ... The specified CustomModel cm-xxx is not found.`
+- No permission → passes through `AccessDenied`; route to [arkcli-auth](../../arkcli-auth/SKILL.md).
+
+## Complete ChargeItem.Type enum mapping
+
+The base model's `ChargeItems` array is **comprehensive**. All types below may appear under the same base model node. The Agent should select the relevant entry based on the user's question.
+
+### Inference types (direct invocation of the base model)
+
+| Type | Meaning |
+|---|---|
+| `Inference` | Average overall inference price (provided by some models) |
+| `InferencePrompt` | Inference input price |
+| `InferenceCompletion` | Inference output price |
+| `BatchInferencePrompt` | Batch inference input price |
+| `BatchInferenceCompletion` | Batch inference output price |
+| `BatchInferenceCacheHit` | Batch inference prompt cache-hit price |
+| `ContextSessionHit` | Context Cache hit price |
+| `ContextSessionStorage` | Context Cache storage price (unit: `k tokens/hour`) |
+| `VisionPrompt` / `BatchVisionPrompt` | Multimodal vision input price |
+
+### Fine-tuning training types (training rates when using a base model for fine-tuning)
+
+| Type | Meaning |
+|---|---|
+| `Finetune` | Full fine-tuning training price |
+| `LoraFinetune` | LoRA fine-tuning training price |
+
+### Fine-tuned inference types (inference price for invoking a fine-tuned custom model)
+
+| Type | Meaning |
+|---|---|
+| `FinetuneInferencePrompt` | Fine-tuned model inference input price |
+| `FinetuneInferenceCompletion` | Fine-tuned model inference output price |
+| `FinetuneI2ICompletion` | Fine-tuned model image-to-image output price |
+| `FinetuneI2VCompletion` | Fine-tuned model image-to-video output price |
+| `FinetuneT2ICompletion` | Fine-tuned model text-to-image output price |
+| `FinetuneT2VCompletion` | Fine-tuned model text-to-video output price |
+| `FinetuneTo3DCompletion` | Fine-tuned model 3D generation output price |
+
+### Vision/multimodal generation types (output price when a base model performs generation)
+
+| Type | Meaning |
+|---|---|
+| `T2ICompletion` / `T2ITokenCompletion` | Text-to-image |
+| `I2ICompletion` / `I2ITokenCompletion` | Image-to-image |
+| `T2VCompletion` / `I2VCompletion` | Text-to-video / image-to-video |
+| `V2VCompletion` / `V2V1080Completion` / `V2V4KCompletion` | Video-to-video (standard / 1080p / 4K) |
+| `NV2VCompletion` / `NV2V1080Completion` / `NV2V4KCompletion` | Silent video-to-video |
+| `FLF2VCompletion` | First-and-last-frame-to-video |
+| `To3DCompletion` / `BatchTo3DCompletion` | 3D generation |
+| `ToVCompletion` / `ToVSilentCompletion` / `BatchToVCompletion` / `BatchToVSilentCompletion` | General video generation (including silent video) |
+| `BatchV2VCompletion` / `BatchV2V1080Completion` / `BatchV2V4KCompletion` | Batch video-to-video |
+
+### Audio types
+
+| Type | Meaning |
+|---|---|
+| `FastAudioPrompt` / `FastAudioCacheHit` | Low-latency audio inference (low-latency inference is not currently supported) |
+
+> **Important**: A user question usually concerns only 1–2 types. Common mappings:
+> - "How much is inference?" → `InferencePrompt` + `InferenceCompletion`
+> - "How much does fine-tuning cost?" → `Finetune` or `LoraFinetune` (multiplied by `tokens × epoch`)
+> - "How much does it cost to invoke a fine-tuned model?" → `FinetuneInferencePrompt` + `FinetuneInferenceCompletion`
+> - "How much is image-to-image?" → `T2ICompletion` / `I2ICompletion` (base model) or `FinetuneT2ICompletion` / `FinetuneI2ICompletion` (fine-tuned model)
+
+## Common usage
+
+**Report a model's input/output price to the user**
+
+```bash
+arkcli pricing models --model dola-seed-2-1-turbo \
+  --transform 'items.0.ChargeItems.#(Type=="InferencePrompt").Price'
+```
+
+Alternatively, omit transform to retrieve all entries, and let the Agent select `InferencePrompt` / `InferenceCompletion`.
+
+**Determine whether the account has a discount**
+
+```bash
+arkcli pricing models --model X
+# Compare Price and OriginalPrice; Price < OriginalPrice means there is a discount
+```
+
+**List and compare prices for all models in a modality**
+
+```bash
+arkcli pricing models --modality LLM --page-size 100
+# The Agent sorts and summarizes the result by vendor / FoundationModelName
+```
+
+## Common errors
+
+| Error | Cause | Handling |
+|------|------|---------|
+| Empty items / total_count=0 | `--modality` was passed an alias such as `text` / `video` instead of a backend enum (this path applies only when `--model` is omitted) | Translate it to `LLM` / `ComputerVision`, and others, before passing it |
+| `foundation model "X" not found in pricing list` (exit=2) | Model name X was not found in the pricing list | Check the spelling, or run `arkcli pricing models` without `--model` to retrieve all supported names |
+| Model State=Unavailable | The current account has not activated it | Route to `arkcli +deploy` (automatic activation) or `arkcli models activate` |
+| `IsOverdue=true` | The account has overdue payments | Does not affect pricing queries, but affects inference calls |
+| `GetCustomModel "cm-xxx": ... is not found` | The cm-prefixed ID does not exist or does not belong to the current account | Check the ID spelling, or first run `arkcli api custom_model.list_custom_models` to retrieve the list |
+
+## References
+
+- [arkcli-pricing](../SKILL.md) — Pricing skill overview
+- [arkcli-shared](../../arkcli-shared/SKILL.md) — Authentication and global parameters
+- [arkcli-usage](../../arkcli-usage/SKILL.md) — View actual consumption (tokens / requests already consumed)

package/skills/arkcli-pricing/references/arkcli-pricing-plans.md

@@ -0,0 +1,139 @@
+# pricing plans
+
+> **Prerequisite:** Read [`../arkcli-shared/SKILL.md`](../../arkcli-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List CodingPlan subscription prices (personal + enterprise, four tiers in total). `Price` is the **final subscription unit price (including discounts)** calculated by the backend for the current account; `OriginalPrice` is the published list price.
+
+`pricing plans` and `pricing models` are **two completely independent commands**:
+- `pricing models` — Token-based billing (pay-as-you-go model invocation)
+- `pricing plans` — Monthly subscription (complete plan)
+
+## Commands
+
+```bash
+# List all four plan tiers (personal 2 + enterprise 2 = 4)
+arkcli pricing plans
+
+# Query a single tier
+arkcli pricing plans --plan coding-plan-personal-pro
+
+# Filter by product
+arkcli pricing plans --product coding-plan       # CodingPlan only, four tiers in total
+
+# Filter by edition
+arkcli pricing plans --edition personal          # Personal edition only, two tiers in total
+arkcli pricing plans --edition enterprise        # Enterprise edition only, two tiers in total
+
+# Combine filters
+arkcli pricing plans --product coding-plan --edition personal   # Two CodingPlan personal tiers
+```
+
+## Complete Plan ID enumeration
+
+| Plan ID | Product | Edition | Tier |
+|---|---|---|---|
+| `coding-plan-personal-lite` | CodingPlan | personal | lite |
+| `coding-plan-personal-pro` | CodingPlan | personal | pro |
+| `coding-plan-enterprise-lite` | CodingPlan | enterprise | lite |
+| `coding-plan-enterprise-pro` | CodingPlan | enterprise | pro |
+
+`--plan` accepts the four IDs above (three-part kebab-case). If misspelled, the command returns a structured error and lists all valid IDs.
+
+## Output fields
+
+```json
+{
+  "items": [
+    {
+      "plan_id": "coding-plan-personal-lite",
+      "product": "CodingPlan",
+      "edition": "personal",
+      "tier": "lite",
+      "price": 10,
+      "original_price": 10,
+      "period": "monthly",
+      "currency": "USD"
+    },
+    {
+      "plan_id": "coding-plan-enterprise-lite",
+      "product": "CodingPlan",
+      "edition": "enterprise",
+      "tier": "lite",
+      "price": 0,
+      "original_price": 0,
+      "period": "monthly",
+      "currency": "USD",
+      "error": "AccessDenied: caller lacks permission"
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `plan_id` | Three-part ID that can be used as the `--plan` argument |
+| `product` | `CodingPlan` |
+| `edition` | `personal` or `enterprise` |
+| `tier` | Tier identifier; personal/enterprise share the same set (lite/pro) |
+| `price` | Final subscription unit price for the current account (after backend settlement) |
+| `original_price` | Published list price |
+| `period` | Subscription period, currently fixed to `monthly` |
+| `currency` | Currency, currently fixed to `USD` |
+| `error` | Reason why this row's query failed. Populated for **this row only**; other rows are unaffected |
+
+## Error isolation mechanism
+
+The backend separates "personal batch" and "enterprise batch" into two Actions, so success / failure for personal and enterprise editions is independent:
+
+- Your account has no enterprise-edition permission → the backend returns `AccessDenied`.
+- Result: the two enterprise rows have an error message in `error` and `price = 0`; the two personal rows return prices normally.
+- The command itself **does not fail**. `arkcli pricing plans` still exits with code 0, and the JSON output contains all four rows.
+
+This matches the BytePlus ModelArk console UI: it also has two tabs (Coding Plan / Coding enterprise edition), and each tab queries pricing and fails independently. A failure in one does not affect the other.
+
+**When the Agent processes the response**:
+1. First identify the tier the user asked about → read that row's `price` directly.
+2. If that row's `error` is non-empty → tell the user, "The account does not have permission for edition X; contact an administrator."
+3. Do not invalidate prices in other rows merely because one row has an `error`.
+
+## Parameter details
+
+### `--plan <plan-id>`
+
+Exactly matches one of the four canonical IDs. Match → query only that tier (only one API call is needed). Misspelling → error message + list of all valid IDs.
+
+### `--product coding-plan`
+
+Also accepts PascalCase (`CodingPlan`). Other values → return an empty items array (no error, because the known-value set is closed, but the Agent workflow is not blocked).
+
+### `--edition personal | enterprise`
+
+Exact match.
+
+### Combination rules
+
+- No flags → all four tiers.
+- `--plan X` has the highest priority (when plan is supplied, other flags are ignored because the plan uniquely identifies the product + edition + tier).
+- `--product` + `--edition` can be combined (logical AND).
+
+## Comparison with other commands
+
+- User asks "How much is DeepSeek?", "How much is image-to-image?", or "How much does fine-tuning cost?" → [`pricing models`](arkcli-pricing-models.md).
+- User asks "How much is Coding Plan small?" or "Personal / enterprise pricing" → this command.
+- User asks "How much have I **already** used / consumed?" → [`../arkcli-usage/SKILL.md`](../../arkcli-usage/SKILL.md).
+
+## Backend Actions involved (for raw API troubleshooting)
+
+| Action | Used for |
+|---|---|
+| `EstimateSubscribePrice` | One CodingPlan personal tier (called once per tier) |
+
+If `pricing plans` completely fails to respond, use the raw API for self-checking:
+
+```bash
+arkcli api trade.estimate_subscribe_price --params '{
+  "Items": [
+    {"BizInfo":"lite","ResourceType":"CodingPlan","ResourceName":"RealCodingPlanPersonal","Period":"monthly","Times":1}
+  ]
+}'
+```