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

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-create.md

@@ -0,0 +1,121 @@
+# arkcli infer endpoint create
+
+Create an inference endpoint.
+
+## Usage
+
+```bash
+arkcli infer endpoint create [flags]
+```
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--model` | string | Model ID (foundation model or custom model) | Yes |
+| `--name` | string | Endpoint name | Yes |
+| `--billing-method` | string | Billing / inference method. Currently supports only `token`. If omitted, the default behavior is used. | No |
+| `--rpm` | int | Rate limit RPM | No |
+| `--tpm` | int | Rate limit TPM | No |
+| `--dry-run` | bool | Emit the local create plan without model discovery, activation, or create API calls | No |
+| `-h`, `--help` | | help for create | No |
+
+Model resolution and activation checks require online state, so Client Preview
+uses `fidelity=partial` and lists them under `unresolved`. It is not server
+validation and does not prove that the model is activated or the request will
+be accepted.
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |
+
+## Examples
+
+```bash
+# Create an Endpoint
+arkcli infer endpoint create \
+  --model dola-seed-2-1-turbo-260628 \
+  --name my-endpoint
+
+# Explicitly request the token inference method (currently keeps the same create payload as when omitted, but first checks whether the model supports token)
+arkcli infer endpoint create \
+  --model dola-seed-2-1-turbo-260628 \
+  --name my-token-endpoint \
+  --billing-method token
+
+# Typical response
+{
+  "Id": "ep-20260421180049-ngwkm"
+}
+
+# Extract only the Id for reuse by subsequent commands
+endpoint_id=$(arkcli infer endpoint create \
+  --model dola-seed-2-1-turbo-260628 \
+  --name my-endpoint \
+  --transform Id)
+```
+
+## Return value
+
+After creation succeeds, the command returns the `Id` of the new Endpoint. Example:
+
+```json
+{
+  "Id": "ep-20260421180049-ngwkm"
+}
+```
+
+This `Id` is the primary entry point for subsequent operations.
+
+## Next steps after creation
+
+### 1. View details
+
+```bash
+arkcli infer endpoint get "$endpoint_id"
+```
+
+### 2. Manage the lifecycle
+
+```bash
+arkcli infer endpoint stop "$endpoint_id"
+arkcli infer endpoint start "$endpoint_id"
+```
+
+### 3. Do not call `+deploy` again
+
+If you already obtained an `Id` through `infer endpoint create`, the Endpoint has already been created.
+
+At this point, do not run:
+
+```bash
+arkcli +deploy ...
+```
+
+Because `+deploy` is itself a "create Endpoint" workflow. It creates a new resource instead of reusing the `Id` that was just created.
+
+## Notes
+
+- `infer endpoint create` is oriented toward standard resource creation.
+- `+deploy` is oriented toward the task workflow of "create Endpoint + model activation / reuse check / profile sync".
+- Both commands create Endpoints and should not be executed sequentially as duplicate steps.
+- Voice models (TTS / ASR / dubbing / podcast / voice / real-time voice interaction) cannot currently use this command to create Endpoints. Voice models are not supported.
+- `--billing-method` currently has only one enum value: `token`. Passing `token` does not add extra fields to the CreateEndpoint request. It only checks before creation whether the corresponding model supports token-based inference.
+- Foundation model support methods come from `ArkModels.data[].Features.ShareService`. For custom models, prefer the deployable version's `EndpointSupportedMethods.ShareService`, and fall back to `AvailableDeploymentTypes=Shared` when necessary.
+
+## References
+
+- [arkcli-infer-endpoint](../SKILL.md) -- infer endpoint capability overview
+- [arkcli-infer-endpoint-get](arkcli-infer-endpoint-get.md) -- View Endpoint details
+- [arkcli-infer-endpoint-start](arkcli-infer-endpoint-start.md) -- Start an Endpoint
+- [arkcli-infer-endpoint-stop](arkcli-infer-endpoint-stop.md) -- Stop an Endpoint

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-delete.md

@@ -0,0 +1,71 @@
+# arkcli infer endpoint delete
+
+Delete an inference endpoint (irreversible)
+
+## Usage
+
+```bash
+arkcli infer endpoint delete <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to delete | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit the local `DeleteEndpoint` Client Preview without reading or deleting the endpoint | No |
+| `--yes` | bool | Skip the interactive Y/N prompt (TTY only). **Non-interactive mode: this flag does NOT authorize deletion** — set `ARKCLI_ALLOW_HEADLESS_DELETE=1` instead. | No |
+| `-h`, `--help` | | help for delete | No |
+
+## Confirmation mechanism (high risk, must read)
+
+Deletion is irreversible. `infer endpoint delete` uses a **three-branch confirmation gate**:
+
+| Environment | Behavior |
+|------|------|
+| Interactive terminal (TTY) | Shows a strong warning + `[y/N]`. The command executes only when the user enters `y`. `--yes` skips the prompt and counts as confirmation. |
+| Non-interactive (agent / CI / pipeline) + `ARKCLI_ALLOW_HEADLESS_DELETE=1` | Allows the operation after printing an audit line (for true unattended automation). |
+| Non-interactive + env not set | **hard-refuse** (`requires_headless_gate`). `--yes` is ignored here. |
+
+Design intent: any agent can reflexively add `--yes`, but an agent's stdin is not a real TTY. Therefore, "real TTY or explicit env" is a hard gate that the agent cannot fabricate, preventing agents from silently approving deletion on behalf of the user with `--yes`. This aligns with the `ARKCLI_ALLOW_HEADLESS_ACTIVATION` pattern enabled for `infer endpoint create`.
+
+### Notes for agent calls
+
+When agents (Claude Code / OpenCode, and others) call `infer endpoint delete` through a skill, they run in a non-interactive environment:
+
+- **hard-refuse by default**, even if `--yes` is provided.
+- To delete in an agent / CI environment, the env must be set explicitly:
+
+  ```bash
+  ARKCLI_ALLOW_HEADLESS_DELETE=1 arkcli infer endpoint delete <id> --yes
+  ```
+
+- In an interactive human terminal, run `arkcli infer endpoint delete <id>` directly and confirm as prompted.
+
+`--dry-run` emits the local `DeleteEndpoint` request plan. It calls neither
+`GetEndpoint` nor `DeleteEndpoint` and does not enter the confirmation gate.
+The plan does not prove that the endpoint exists, is deletable, or will be
+accepted by the server.
+
+### Recommendation before deletion
+
+If the endpoint is in the `Running` state, some scenarios require `stop` before `delete`. When the status does not allow deletion, the backend returns `OperationDenied.EndpointStatus`, and arkcli translates it into "endpoint status does not allow this operation" and suggests using `infer endpoint get <id>` to check the status.
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-get.md

@@ -0,0 +1,43 @@
+# arkcli infer endpoint get
+
+Get inference endpoint details
+
+## Diagnose from evidence
+
+- With an exact Endpoint ID, call `get` directly. Preserve the entire ID, including `ep-m-`; never invent a suffix or rewrite its prefix. Record actual status, reason, model binding, scope and limits. Use `resources resolve` for ambiguous bindings; a custom model's base-model lineage is not its bound identity.
+- Keep the original identity, region, base URL, request time, error code and RequestId. Redact credentials; do not rotate keys, change profiles or widen permissions as a diagnostic shortcut. A 401 requires checking credential shape/validity; a 403 requires checking actual resource access and scope; a 404 requires checking the exact ID and API route. None alone proves a specific cause.
+- `Running` is control-plane state, not successful inference. Endpoint usage is aggregated usage, not a single-request error rate or trace. Use Doctor for supported metrics and state missing data or aggregation delay explicitly.
+- Only run a minimal real inference when authorized, using the model's supported API and original input modality. For text, use `+chat --model <endpoint-id>`, not `--endpoint`. A text-only probe cannot prove image input works. Without a real call, report the data plane as unverified.
+- For 500 errors, inspect API/modality compatibility, parameters and service evidence without assuming every vision model supports embeddings or blaming the network. For ClosedEndpoint, read the status first; starting or rebuilding is a separate authorized write.
+
+## Usage
+
+```bash
+arkcli infer endpoint get <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to get | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `-h`, `--help` | | help for get | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-list.md

@@ -0,0 +1,82 @@
+# arkcli infer endpoint list
+
+List inference endpoints
+
+## Inventory and export
+
+- Preserve the requested identity and filters. An empty personal query does not authorize an account-wide query. For an explicitly account-wide running inventory, use `--status Running --page-all --page-size 100`.
+- Parse complete stdout separately from stderr. The array is `Items`, not `items`; check pagination limits and warnings before calling the inventory complete. Never use `head` as a completeness check.
+- Include the exact ID, name, actual bound model, status, creation time and description. Fetch per-Endpoint details only for requested fields absent from the list; distinguish missing values from zero.
+- Fetch details serially by default and respect API QPS. Record partial failures individually; do not mix `2>&1` into JSON or claim full success after failures. Quote IDs as arguments rather than inserting returned values into shell source or file paths.
+- Preserve raw timestamps, label the display timezone and convert offsets only once. Report query scope, filters, count, failures and completeness alongside the export.
+
+## Usage
+
+```bash
+arkcli infer endpoint list [flags]
+```
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--format` | string | Output format: table \| json | No |
+| `--model` | string | Filter by model: a custom model ID (`cm-...`) or a foundation model name (`doubao-seedream-5-0-pro`, or the dotted DisplayName form `doubao-seedream-5.0-pro`) | No |
+| `--status` | string | Filter by endpoint status | No |
+| `--mine` | bool | List only endpoints created by the current SSO sub-user (server-side `sys:ark:createdBy` tag filtering) | No |
+| `--page-number` | int | Page number (>=1) | No |
+| `--page-size` | int | Page size | No |
+| `-h`, `--help` | | help for list | No |
+
+## `--model` semantics
+
+`--model` accepts two kinds of value, dispatched by the CLI:
+
+- `cm-` prefix → filtered as a **custom model ID** (`Filter.CustomModelIds`, case-sensitive).
+- anything else → filtered as a **foundation model name**: the value is normalized to
+  the connector Name first, then sent as `Filter.FoundationModelNames` (exact match
+  server-side).
+
+Normalization does exactly two things and **never rewrites characters**: an exact Name
+match, then a case-insensitive exact DisplayName match. DisplayName is not always the
+same shape as Name — for example the model `doubao-seedream-5-0` has DisplayName
+`Doubao-Seedream-5.0-lite` (the display name carries `lite`, the connector Name does
+not), so replacing dots with hyphens would produce a name that does not exist.
+
+If the value is neither a `cm-` ID nor a match for any foundation model name, the
+command **exits non-zero** with a hint instead of returning an empty list. Do not read
+an empty result as "this account has no endpoint for that model".
+
+```bash
+arkcli infer endpoint list --model doubao-seedream-5-0-pro --page-all --page-size 100 --format json
+```
+
+## Semantics of "my endpoints" (overrides shared default)
+
+This command **has built-in `--mine` support**. According to the "decision order" in [`../../arkcli-auth/references/identity-resolution.md`](../../arkcli-auth/references/identity-resolution.md), you MUST **prefer** this option and must not fall back to client-side filtering with `whoami + jq`.
+
+```bash
+arkcli infer endpoint list --mine --page-all --page-size 100 --page-delay 800 --format json
+```
+
+Behavior:
+
+- At the shortcut layer, `--mine` combines the current `cfg.UserID` / `cfg.UserName` into `IAMUser/<UserID>/<UserName>` and sends it to `ListEndpoints` as `TagFilters.{Key: "sys:ark:createdBy", Values: [...]}`.
+- It can be freely combined with `--status` / `--model` / `--page-*` (for example, `--mine --status Running`).
+- It is available only for **SSO sub-user** login state. Other states **fail directly** and do not silently degrade:
+  - Non-SSO (AK/SK / APIKey): `--mine requires an SSO sub-user login`; run `arkcli auth login` to re-establish BytePlus identity.
+  - SSO root: `--mine is not supported for root logins`; guide the user to log in with a sub-user.
+  - SSO with missing UserID/UserName claims: guide the user to log in again to refresh identity.
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-start.md

@@ -0,0 +1,36 @@
+# arkcli infer endpoint start
+
+Start an inference endpoint
+
+## Usage
+
+```bash
+arkcli infer endpoint start <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to start | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit a local `StartEndpoint` Client Preview without calling the API | No |
+| `-h`, `--help` | | help for start | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-stop.md

@@ -0,0 +1,36 @@
+# arkcli infer endpoint stop
+
+Stop an inference endpoint
+
+## Usage
+
+```bash
+arkcli infer endpoint stop <endpoint-id> [flags]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to stop | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--dry-run` | bool | Emit a local `StopEndpoint` Client Preview without calling the API | No |
+| `-h`, `--help` | | help for stop | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |

package/skills/arkcli-infer-endpoint/references/arkcli-infer-endpoint-update.md

@@ -0,0 +1,78 @@
+# arkcli infer endpoint update
+
+Update an inference endpoint (name / description / rate limits)
+
+## Usage
+
+```bash
+arkcli infer endpoint update <endpoint-id> [flags]
+```
+
+At least one of `--name`, `--description`, `--rpm`+`--tpm`, or any `--cg-*` option must be provided. Otherwise, the command reports "nothing to update" and does not send a request.
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<endpoint-id>` | The ID of the endpoint to update | Yes |
+
+## Flags
+
+| Flag | Type | Description | Required |
+|------|------|-------------|----------|
+| `--name` | string | New endpoint name | No |
+| `--description` | string | New endpoint description (use empty string `""` to clear) | No |
+| `--rpm` | int | Rate limit: requests per minute (must be paired with `--tpm`) | No |
+| `--tpm` | int | Rate limit: tokens per minute (must be paired with `--rpm`) | No |
+| `--cg-concurrent-requests` | int | ContentGeneration: max concurrent requests (image-generation endpoints) | No |
+| `--cg-create-task-rpm` | int | ContentGeneration: CreateTask RPM (image-generation endpoints) | No |
+| `--dry-run` | bool | Emit a local `UpdateEndpoint` Client Preview without calling the API | No |
+| `-h`, `--help` | | help for update | No |
+
+## Global Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--api-key` | string | ARK API key override |
+| `--base-url` | string | Custom API base URL |
+| `--debug` | | Print request and response debug details to stderr |
+| `--format` | string | Output format: json (default "json") |
+| `--page-all` | | Automatically fetch all pages when supported |
+| `--page-delay` | int | Delay in milliseconds between pages (default 200) |
+| `--page-limit` | int | Maximum pages to fetch with --page-all (default 10) |
+| `--profile` | string | Active config profile |
+| `--transform` | string | Transform output with a GJSON-style path expression |
+
+## Examples
+
+Rename only:
+
+```bash
+arkcli infer endpoint update ep-20260428194457-p8b47 --name seed-2-1-turbo-demo-123
+```
+
+Clear the description:
+
+```bash
+arkcli infer endpoint update ep-20260428194457-p8b47 --description ""
+```
+
+Adjust rate limits (`--rpm` and `--tpm` must be provided together):
+
+```bash
+arkcli infer endpoint update ep-20260428194457-p8b47 --rpm 60 --tpm 100000
+```
+
+Adjust content generation parameters for image-generation endpoints (valid only for image-generation scenarios):
+
+```bash
+arkcli infer endpoint update ep-20260507230659-skvgn \
+  --cg-concurrent-requests 10 \
+  --cg-create-task-rpm 60
+```
+
+Local preview (does not send a request):
+
+```bash
+arkcli infer endpoint update ep-20260428194457-p8b47 --name foo --dry-run
+```

package/skills/arkcli-infer-endpoint/references/evals.md

@@ -0,0 +1,24 @@
+# arkcli-infer-endpoint evaluation cases
+
+## Routing goals
+
+- Deployment-form questions must route to `arkcli-infer-endpoint`, even when the prompt contains the generic word "capability".
+- Foundation models use `--model` plus `--version`; custom models use `--custom-model-id`.
+- Marketplace metadata commands must not substitute for the authoritative deployment-method query.
+
+## Regression cases
+
+| case | prompt | expected |
+|---|---|---|
+| `endpoint-capability-foundation` | Which deployment forms does `dola-seed-2-1-turbo` version `260628` support, such as shared service, batch, PTU, scale tier, or fallback? | Load `arkcli-infer-endpoint` and run `arkcli infer endpoint capability get --model dola-seed-2-1-turbo --version 260628 --format json`. |
+| `endpoint-capability-custom` | Can custom model `cm-123` use PTU or shared service? | Run `arkcli infer endpoint capability get --custom-model-id cm-123 --format json`. |
+| `endpoint-capability-read-only` | Check whether this model is deployable, but do not create anything. | Run only the capability query; do not run `+deploy` or `infer endpoint create`. |
+| `endpoint-capability-no-models-fallback` | Tell me the supported inference deployment methods. | Do not use `models get`, `models search`, or Raw API Explorer as a replacement. |
+
+## Key scoring points
+
+- Must route to `arkcli-infer-endpoint`.
+- Must execute `arkcli infer endpoint capability get`.
+- Must read `supported_methods` and the full `capabilities` map.
+- Must not infer deployment support from model name, modality, or another product.
+- Must not mutate an Endpoint during a capability-only request.