README.md
# bailian-cli
> [中文版 / Chinese →](README.zh.md)
Agent skill for **Alibaba Cloud Model Studio CLI** (`bl`) resource hub — apps, memory, RAG, usage/quota, MCP, and hub `reference/`.
- Shared protocol: `bailian-protocol` (install via `bl skill init`)
- Soft hand-offs (optional skills): `bailian-gen` · `bailian-finetune` · `bailian-managed-agent` · `bailian-web-search`
```bash
bl skill init
```
For CLI installation, authentication, and examples, see the [main README](../../README.md).
## License
Apache-2.0
README.zh.md
# 百炼 CLI
> [English →](README.md)
**阿里云百炼 CLI**（`bl`）的资源管理 Agent 技能 — 应用、记忆、RAG、用量/额度、MCP，以及 hub `reference/`。
- 共享协议：`bailian-protocol`（通过 `bl skill init` 与整家族同装）
- 软 hand-off（可选）：`bailian-gen` · `bailian-finetune` · `bailian-managed-agent` · `bailian-web-search`
```bash
bl skill init
```
CLI 的安装、认证和使用示例请查看[主 README](../../README.zh.md)。
## License
Apache-2.0
reference/advisor.md
# `bl advisor` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| `bl advisor recommend` | API Key | Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking) |
## Command details
### `bl advisor recommend`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| **Name** | `advisor recommend` |
| **Description** | Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking) |
| **Authentication** | API Key |
| **Usage** | `bl advisor recommend --message <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------- |
| `--message <text>` | string | yes | Describe your requirements |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl advisor recommend --message "I need a visual-understanding chatbot"
```
```bash
bl advisor recommend --message "Build an Agent that auto-generates animations"
```
```bash
bl advisor recommend --message "Legal contract review, high precision required"
```
```bash
bl advisor recommend --message "Low-cost high-concurrency online customer service" --output text
```
```bash
bl advisor recommend --message "Long document summarization" --dry-run
```
reference/app.md
# `bl app` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------- | -------------- | ---------------------------------------------- |
| `bl app call` | API Key | Call a Bailian application (agent or workflow) |
| `bl app list` | Console | List Bailian applications |
## Command details
### `bl app call`
| Field | Value |
| ------------------ | --------------------------------------------------- |
| **Name** | `app call` |
| **Description** | Call a Bailian application (agent or workflow) |
| **Authentication** | API Key |
| **Usage** | `bl app call --app-id <id> --prompt <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | --------------------------------------------- |
| `--app-id <id>` | string | yes | Application ID (required) |
| `--prompt <text>` | string | yes | Input prompt text |
| `--image <url>` | array | no | Image URL(s) to pass to the app (repeatable) |
| `--file-id <id>` | array | no | Pre-uploaded file ID(s) (repeatable) |
| `--session-id <id>` | string | no | Session ID for multi-turn conversation |
| `--stream` | switch | no | Stream response (default: on in TTY) |
| `--pipeline-ids <ids>` | string | no | Knowledge base pipeline IDs (comma-separated) |
| `--memory-id <id>` | string | no | Memory ID for long-term memory |
| `--biz-params <json>` | string | no | Business parameters JSON (workflow variables) |
| `--has-thoughts` | switch | no | Show agent thinking process |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl app call --app-id abc123 --prompt "Hello"
```
```bash
bl app call --app-id abc123 --prompt "Describe this image" --image https://example.com/photo.jpg
```
```bash
bl app call --app-id abc123 --prompt "Analyze the image" --image img1.jpg --image img2.jpg
```
```bash
bl app call --app-id abc123 --prompt "Continue" --session-id sess_xxx --stream
```
```bash
bl app call --app-id abc123 --prompt "Search for materials" --pipeline-ids pipe1,pipe2
```
```bash
bl app call --app-id abc123 --prompt "Start" --biz-params '{"key":"value"}'
```
### `bl app list`
| Field | Value |
| ------------------ | ------------------------- |
| **Name** | `app list` |
| **Description** | List Bailian applications |
| **Authentication** | Console |
| **Usage** | `bl app list [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--name <name>` | string | no | Filter by app name (keyword search) |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 30) |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl app list
```
```bash
bl app list --name customer service
```
```bash
bl app list --page 2 --page-size 10
```
```bash
bl app list --output json
```
reference/auth.md
# `bl auth` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `bl auth generate-access-token` | No Auth | Generate a CLI access token using OpenAPI AK/SK |
| `bl auth login` | No Auth | Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist) |
| `bl auth logout` | No Auth | Clear stored credentials; full logout also clears the model Base URL |
| `bl auth status` | No Auth | Show current authentication state |
## Command details
### `bl auth generate-access-token`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Name** | `auth generate-access-token` |
| **Description** | Generate a CLI access token using OpenAPI AK/SK |
| **Authentication** | No Auth |
| **Usage** | `bl auth generate-access-token --access-key-id <id> --access-key-secret <secret> --security-token <token>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ---------------------------------------------------- |
| `--access-key-id <id>` | string | yes | Alibaba Cloud Access Key ID |
| `--access-key-secret <secret>` | string | yes | Alibaba Cloud Access Key Secret |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token to store (optional) |
#### Examples
```bash
bl auth generate-access-token --access-key-id LTAIxxxxx --access-key-secret xxxxx --security-token <token>
```
### `bl auth login`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Name** | `auth login` |
| **Description** | Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist) |
| **Authentication** | No Auth |
| **Usage** | `bl auth login --api-key <key> \| --console \| --open-api --access-key-id <id> --access-key-secret <secret>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------- |
| `--api-key <key>` | string | no | Model API key to store |
| `--base-url <url>` | string | no | Model API base URL to store with --api-key |
| `--console` | switch | no | Sign in via browser; use --console-site to choose domestic (default) or international |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--open-api` | switch | no | Store Alibaba Cloud OpenAPI AK/SK credentials |
| `--access-key-id <id>` | string | no | Alibaba Cloud Access Key ID to store |
| `--access-key-secret <secret>` | string | no | Alibaba Cloud Access Key Secret to store |
#### Examples
```bash
bl auth login --api-key sk-xxxxx
```
```bash
bl auth login --config token-plan --api-key sk-sp-xxxxx
```
```bash
bl auth login --console
```
```bash
bl auth login --open-api --access-key-id LTAIxxxxx --access-key-secret xxxxx
```
### `bl auth logout`
| Field | Value |
| ------------------ | -------------------------------------------------------------------- |
| **Name** | `auth logout` |
| **Description** | Clear stored credentials; full logout also clears the model Base URL |
| **Authentication** | No Auth |
| **Usage** | `bl auth logout [--console \| --open-api] [--dry-run]` |
#### Flags
| Flag | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------------------------------------------------- |
| `--console` | switch | no | Only clear the console access_token, keep api_key intact |
| `--open-api` | switch | no | Only clear OpenAPI AK/SK/STS credentials, keep other credentials intact |
#### Examples
```bash
bl auth logout
```
```bash
bl auth logout --console
```
```bash
bl auth logout --open-api
```
```bash
bl auth logout --dry-run
```
### `bl auth status`
| Field | Value |
| ------------------ | --------------------------------- |
| **Name** | `auth status` |
| **Description** | Show current authentication state |
| **Authentication** | No Auth |
| **Usage** | `bl auth status` |
#### Flags
_No command-specific flags._
#### Examples
```bash
bl auth status
```
```bash
bl auth status --output json
```
reference/config.md
# `bl config` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ----------------- | -------------- | ------------------------------------------------ |
| `bl config agent` | No Auth | Configure a coding agent to use DashScope API |
| `bl config list` | No Auth | List config profiles and show the active profile |
| `bl config set` | No Auth | Set a config value |
| `bl config show` | No Auth | Display current configuration |
| `bl config ui` | No Auth | Open a local web UI to manage config profiles |
| `bl config use` | No Auth | Set the active config profile |
## Command details
### `bl config agent`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `config agent` |
| **Description** | Configure a coding agent to use DashScope API |
| **Authentication** | No Auth |
| **Usage** | `bl config agent --agent <name> (--base-url <url> \| --region <region>) (--api-key <key> \| --key <encoded>) --model <model>` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------------------------------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `--agent <claude-code\|qwen-code\|opencode\|openclaw\|hermes\|codex>` | string | yes | Target agent: claude-code, qwen-code, opencode, openclaw, hermes, codex |
| `--base-url <url>` | string | no | API base URL |
| `--region <region>` | string | no | Model Studio region (e.g. cn-beijing, ap-southeast-1); converted into --base-url. Token Plan only |
| `--api-key <key>` | string | no | API key |
| `--key <encoded>` | string | no | Obfuscated API key from the web console (starts with "o1\_"); decoded into --api-key |
| `--model <model>` | string | yes | Default model name |
| `--context-window <tokens>` | number | no | OpenClaw only: model context window in tokens (default: 256000) |
| `--wire-api <chat\|responses>` | string | no | Codex only: wire protocol (default: responses). "chat" only works with legacy Codex <= 0.80.0 |
#### Examples
```bash
bl config agent --agent claude-code --base-url https://dashscope.aliyuncs.com/apps/anthropic --api-key sk-xxxxx --model qwen3-max
```
```bash
bl config agent --agent qwen-code --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
```
```bash
bl config agent --agent codex --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 --api-key sk-xxxxx --model qwen3-coder-plus
```
### `bl config list`
| Field | Value |
| ------------------ | ------------------------------------------------ |
| **Name** | `config list` |
| **Description** | List config profiles and show the active profile |
| **Authentication** | No Auth |
| **Usage** | `bl config list` |
#### Flags
_No command-specific flags._
#### Examples
```bash
bl config list
```
```bash
bl config list --output json
```
### `bl config set`
| Field | Value |
| ------------------ | ------------------------------------------- |
| **Name** | `config set` |
| **Description** | Set a config value |
| **Authentication** | No Auth |
| **Usage** | `bl config set --key <key> --value <value>` |
#### Flags
| Flag | Type | Required | Description |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--key <key>` | string | yes | Config key (language, base*url, output, output_dir, timeout, api_key, api_key_capabilities, access_token, access_key_id, access_key_secret, security_token, default*\*\_model, workspace_id) |
| `--value <value>` | string | yes | Value to set |
#### Examples
```bash
bl config set --key language --value zh-CN
```
```bash
bl config set --key output --value json
```
```bash
bl config set --key timeout --value 600
```
```bash
bl config set --key base_url --value https://dashscope.aliyuncs.com
```
```bash
bl config set --config company-plan --key api-key-capabilities --value text.chat,image.generate
```
### `bl config show`
| Field | Value |
| ------------------ | ----------------------------- |
| **Name** | `config show` |
| **Description** | Display current configuration |
| **Authentication** | No Auth |
| **Usage** | `bl config show` |
#### Flags
_No command-specific flags._
#### Examples
```bash
bl config show
```
```bash
bl config show --output json
```
### `bl config ui`
| Field | Value |
| ------------------ | --------------------------------------------- |
| **Name** | `config ui` |
| **Description** | Open a local web UI to manage config profiles |
| **Authentication** | No Auth |
| **Usage** | `bl config ui [--port <port>] [--no-open]` |
#### Flags
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------- |
| `--port <port>` | number | no | Port to listen on (default: random free port) |
| `--no-open` | switch | no | Do not open the browser automatically |
#### Examples
```bash
bl config ui
```
```bash
bl config ui --port 8787
```
```bash
bl config ui --no-open
```
### `bl config use`
| Field | Value |
| ------------------ | ----------------------------- |
| **Name** | `config use` |
| **Description** | Set the active config profile |
| **Authentication** | No Auth |
| **Usage** | `bl config use --name <name>` |
#### Flags
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------- |
| `--name <name>` | string | yes | Existing profile name, or default |
#### Examples
```bash
bl config use --name token-plan
```
```bash
bl config use --name default
```
reference/console.md
# `bl console` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ----------------- | -------------- | ---------------------------------------------- |
| `bl console call` | Console | Call a Bailian console API via the CLI gateway |
## Command details
### `bl console call`
| Field | Value |
| ------------------ | --------------------------------------------------- |
| **Name** | `console call` |
| **Description** | Call a Bailian console API via the CLI gateway |
| **Authentication** | Console |
| **Usage** | `bl console call --api <api> --data <json> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------ |
| `--api <api>` | string | yes | API name (e.g. zeldaEasy.broadscope-bailian.memory-library.getLibraries) |
| `--data <json>` | string | yes | Request data as JSON string |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl console call --api zeldaEasy.bailian-commerce.freeTrial.queryFreeTierQuota --data '{"queryFreeTierQuotaRequest":{"models":["qwen3-max"]}}'
```
```bash
bl console call --api some.api.name --data '{"key":"value"}' --console-region cn-beijing
```
reference/file.md
# `bl file` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------- | -------------- | -------------------------------------------------------- |
| `bl file upload` | API Key | Upload a local file to DashScope temporary storage (48h) |
## Command details
### `bl file upload`
| Field | Value |
| ------------------ | -------------------------------------------------------- |
| **Name** | `file upload` |
| **Description** | Upload a local file to DashScope temporary storage (48h) |
| **Authentication** | API Key |
| **Usage** | `bl file upload --file <path> --model <model>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ----------------------------------------------- |
| `--file <path>` | string | yes | Local file to upload (image, video, audio) |
| `--model <model>` | string | yes | Target model name (file is bound to this model) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl file upload --file photo.jpg --model qwen3-vl-plus
```
```bash
bl file upload --file video.mp4 --model wan2.1-t2v-plus
```
```bash
bl file upload --file audio.wav --model qwen3-asr-flash
```
```bash
bl file upload --file cat.png --model qwen-image-3.0
```
reference/index.md
# `bailian-cli` command reference
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Command **details** are in sibling `<group>.md` files in this directory.
This index only covers groups owned by this skill. Other `bl` groups live in sibling bailian-\* skills.
Use this index for the skill-scoped quick index and global flags.
## Quick index
| Command | Authentication | Description | Detail |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
| `bl advisor recommend` | API Key | Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking) | [advisor.md](advisor.md) |
| `bl app call` | API Key | Call a Bailian application (agent or workflow) | [app.md](app.md) |
| `bl app list` | Console | List Bailian applications | [app.md](app.md) |
| `bl auth generate-access-token` | No Auth | Generate a CLI access token using OpenAPI AK/SK | [auth.md](auth.md) |
| `bl auth login` | No Auth | Authenticate with API key, console browser login, or OpenAPI AK/SK (credentials can coexist) | [auth.md](auth.md) |
| `bl auth logout` | No Auth | Clear stored credentials; full logout also clears the model Base URL | [auth.md](auth.md) |
| `bl auth status` | No Auth | Show current authentication state | [auth.md](auth.md) |
| `bl config agent` | No Auth | Configure a coding agent to use DashScope API | [config.md](config.md) |
| `bl config list` | No Auth | List config profiles and show the active profile | [config.md](config.md) |
| `bl config set` | No Auth | Set a config value | [config.md](config.md) |
| `bl config show` | No Auth | Display current configuration | [config.md](config.md) |
| `bl config ui` | No Auth | Open a local web UI to manage config profiles | [config.md](config.md) |
| `bl config use` | No Auth | Set the active config profile | [config.md](config.md) |
| `bl console call` | Console | Call a Bailian console API via the CLI gateway | [console.md](console.md) |
| `bl file upload` | API Key | Upload a local file to DashScope temporary storage (48h) | [file.md](file.md) |
| `bl knowledge category add` | API Key | Create a data-center category | [knowledge.md](knowledge.md) |
| `bl knowledge category delete` | API Key | Delete a data-center category | [knowledge.md](knowledge.md) |
| `bl knowledge category list` | API Key | List data-center categories | [knowledge.md](knowledge.md) |
| `bl knowledge chat` | API Key | Chat with a Bailian knowledge base (RAG Q&A with streaming) | [knowledge.md](knowledge.md) |
| `bl knowledge chunk add` | API Key | Add a chunk directly to a knowledge base | [knowledge.md](knowledge.md) |
| `bl knowledge chunk delete` | API Key | Delete chunks from a knowledge base (irreversible) | [knowledge.md](knowledge.md) |
| `bl knowledge chunk list` | API Key | List chunks in a knowledge base with content and status | [knowledge.md](knowledge.md) |
| `bl knowledge chunk update` | API Key | Update chunk content or toggle its retrieval visibility | [knowledge.md](knowledge.md) |
| `bl knowledge collection create` | API Key | Create a FILE data collection | [knowledge.md](knowledge.md) |
| `bl knowledge collection get` | API Key | Show data collection details | [knowledge.md](knowledge.md) |
| `bl knowledge create` | API Key | Create a knowledge base and import data-center files or categories | [knowledge.md](knowledge.md) |
| `bl knowledge delete` | API Key | Delete a knowledge base with all its documents and chunks | [knowledge.md](knowledge.md) |
| `bl knowledge doc delete` | API Key | Delete documents and their chunks from a knowledge base | [knowledge.md](knowledge.md) |
| `bl knowledge doc import-oss` | API Key | Batch import files from an authorized OSS bucket into the data center | [knowledge.md](knowledge.md) |
| `bl knowledge doc list` | API Key | List documents in a knowledge base with parse/index status | [knowledge.md](knowledge.md) |
| `bl knowledge doc status` | API Key | Check knowledge base import job status | [knowledge.md](knowledge.md) |
| `bl knowledge doc tag` | API Key | Batch update tags on data-center files | [knowledge.md](knowledge.md) |
| `bl knowledge doc upload` | API Key | Upload local files or directories to the data center and optionally import into a knowledge base | [knowledge.md](knowledge.md) |
| `bl knowledge file delete` | API Key | Permanently delete a file from the data center | [knowledge.md](knowledge.md) |
| `bl knowledge file get` | API Key | Show data-center file details (size, MD5, tags, timestamps) | [knowledge.md](knowledge.md) |
| `bl knowledge file list` | API Key | List files in a data-center category | [knowledge.md](knowledge.md) |
| `bl knowledge info` | API Key | Show knowledge base configuration details | [knowledge.md](knowledge.md) |
| `bl knowledge list` | API Key | List knowledge bases in the workspace | [knowledge.md](knowledge.md) |
| `bl knowledge retrieve` | API Key | Retrieve from a Bailian knowledge base (deprecated, use `search` instead) | [knowledge.md](knowledge.md) |
| `bl knowledge search` | API Key | Search a Bailian knowledge base (RAG semantic retrieval) | [knowledge.md](knowledge.md) |
| `bl knowledge service copy` | API Key | Copy a service into a new draft (name gets a copy\_ prefix) | [knowledge.md](knowledge.md) |
| `bl knowledge service create` | API Key | Create a retrieval / Q&A service (initial status: draft, version: beta) | [knowledge.md](knowledge.md) |
| `bl knowledge service delete` | API Key | Delete a retrieval / Q&A service (soft delete, idempotent) | [knowledge.md](knowledge.md) |
| `bl knowledge service deploy` | API Key | Publish the beta draft of a service as a new version | [knowledge.md](knowledge.md) |
| `bl knowledge service get` | API Key | Show service (agent) details including per-version configuration | [knowledge.md](knowledge.md) |
| `bl knowledge service list` | API Key | List retrieval / Q&A services (agents) in the workspace | [knowledge.md](knowledge.md) |
| `bl knowledge service update` | API Key | Update service name, description or draft configuration | [knowledge.md](knowledge.md) |
| `bl knowledge stats` | API Key | Show knowledge base storage and QPS monitoring data | [knowledge.md](knowledge.md) |
| `bl knowledge update` | API Key | Update knowledge base name, description or rerank threshold | [knowledge.md](knowledge.md) |
| `bl mcp call` | API Key | Call a tool on an MCP server (tools/call) | [mcp.md](mcp.md) |
| `bl mcp list` | Console | List MCP servers activated under your Bailian account | [mcp.md](mcp.md) |
| `bl mcp tools` | API Key | List tools exposed by an MCP server (tools/list) | [mcp.md](mcp.md) |
| `bl memory add` | API Key | Add memory from messages or custom content | [memory.md](memory.md) |
| `bl memory delete` | API Key | Delete a memory node | [memory.md](memory.md) |
| `bl memory list` | API Key | List memory nodes for a user | [memory.md](memory.md) |
| `bl memory profile create` | API Key | Create a user profile schema for memory profiling | [memory.md](memory.md) |
| `bl memory profile get` | API Key | Get user profile by schema ID and user ID | [memory.md](memory.md) |
| `bl memory search` | API Key | Search memory nodes by query or messages | [memory.md](memory.md) |
| `bl memory update` | API Key | Update a memory node content | [memory.md](memory.md) |
| `bl model list` | No Auth | Browse model families or show detailed model info in the Bailian model marketplace | [model.md](model.md) |
| `bl permission grant` | API Key | Grant model permissions (inference / finetune / deploy) | [permission.md](permission.md) |
| `bl permission list` | API Key | List model permissions (inference / fine-tune / deploy) in the workspace | [permission.md](permission.md) |
| `bl permission revoke` | API Key | Revoke model permissions (inference / finetune / deploy) | [permission.md](permission.md) |
| `bl pipeline run` | No Auth | Run a pipeline workflow definition | [pipeline.md](pipeline.md) |
| `bl pipeline validate` | No Auth | Validate a pipeline definition without executing | [pipeline.md](pipeline.md) |
| `bl plugin install` | No Auth | Install or upgrade an allowlisted Command Pack | [plugin.md](plugin.md) |
| `bl plugin link` | No Auth | Link an allowlisted local Command Pack for development | [plugin.md](plugin.md) |
| `bl plugin list` | No Auth | List installed Command Packs and their load status | [plugin.md](plugin.md) |
| `bl plugin remove` | No Auth | Remove an installed Command Pack | [plugin.md](plugin.md) |
| `bl quota check` | Console | Check current usage against rate limits | [quota.md](quota.md) |
| `bl quota delete` | API Key | Clear all custom rate limits (QPM/TPM) for a model | [quota.md](quota.md) |
| `bl quota history` | Console | View quota change history | [quota.md](quota.md) |
| `bl quota list` | API Key | View model rate limits (QPM/TPM, account and workspace level) | [quota.md](quota.md) |
| `bl quota update` | API Key | Update model rate limits (QPM/TPM) | [quota.md](quota.md) |
| `bl search web` | API Key | Search the web using DashScope MCP WebSearch service | [search.md](search.md) |
| `bl skill add` | No Auth | Install skills from the Bailian skill registry into local agents | [skill.md](skill.md) |
| `bl skill init` | No Auth | Install all bailian-\* skills (one-shot bootstrap for new environments) | [skill.md](skill.md) |
| `bl skill list` | No Auth | List registry skills and diff against local installs | [skill.md](skill.md) |
| `bl skill remove` | No Auth | Remove locally installed skills (registry is untouched) | [skill.md](skill.md) |
| `bl skill update` | No Auth | Update installed skills to the latest registry versions | [skill.md](skill.md) |
| `bl text chat` | API Key | Send a text model request (OpenAI compatible, DashScope) | [text.md](text.md) |
| `bl token-plan add-member` | AK/SK | Add a member to a Token Plan organization | [token-plan.md](token-plan.md) |
| `bl token-plan assign-seats` | AK/SK | Batch assign Token Plan seats to members | [token-plan.md](token-plan.md) |
| `bl token-plan create-key` | AK/SK | Create a Token Plan API key for a seat | [token-plan.md](token-plan.md) |
| `bl token-plan list-seats` | AK/SK | List Token Plan subscription seat details | [token-plan.md](token-plan.md) |
| `bl update` | No Auth | Update the CLI to the latest or a specified version | [update.md](update.md) |
| `bl usage coding-plan` | Console | Show Coding Plan quota usage | [usage.md](usage.md) |
| `bl usage free` | Console | Query free-tier quota for models (all models if --model is omitted) | [usage.md](usage.md) |
| `bl usage freetier` | Console | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable | [usage.md](usage.md) |
| `bl usage stats` | Console | Query model usage statistics | [usage.md](usage.md) |
| `bl usage summary` | Console | Show a unified usage summary: free-tier quota and recent usage overview | [usage.md](usage.md) |
| `bl usage token-plan` | Console | Show Token Plan quota usage | [usage.md](usage.md) |
| `bl workspace init` | No Auth | Initialize Bailian workspace and activate postpaid services | [workspace.md](workspace.md) |
| `bl workspace list` | Console | List all workspaces | [workspace.md](workspace.md) |
## By group
| Group | Commands | Reference |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `advisor` | `recommend` | [advisor.md](advisor.md) |
| `app` | `call`, `list` | [app.md](app.md) |
| `auth` | `generate-access-token`, `login`, `logout`, `status` | [auth.md](auth.md) |
| `config` | `agent`, `list`, `set`, `show`, `ui`, `use` | [config.md](config.md) |
| `console` | `call` | [console.md](console.md) |
| `file` | `upload` | [file.md](file.md) |
| `knowledge` | `category add`, `category delete`, `category list`, `chat`, `chunk add`, `chunk delete`, `chunk list`, `chunk update`, `collection create`, `collection get`, `create`, `delete`, `doc delete`, `doc import-oss`, `doc list`, `doc status`, `doc tag`, `doc upload`, `file delete`, `file get`, `file list`, `info`, `list`, `retrieve`, `search`, `service copy`, `service create`, `service delete`, `service deploy`, `service get`, `service list`, `service update`, `stats`, `update` | [knowledge.md](knowledge.md) |
| `mcp` | `call`, `list`, `tools` | [mcp.md](mcp.md) |
| `memory` | `add`, `delete`, `list`, `profile create`, `profile get`, `search`, `update` | [memory.md](memory.md) |
| `model` | `list` | [model.md](model.md) |
| `permission` | `grant`, `list`, `revoke` | [permission.md](permission.md) |
| `pipeline` | `run`, `validate` | [pipeline.md](pipeline.md) |
| `plugin` | `install`, `link`, `list`, `remove` | [plugin.md](plugin.md) |
| `quota` | `check`, `delete`, `history`, `list`, `update` | [quota.md](quota.md) |
| `search` | `web` | [search.md](search.md) |
| `skill` | `add`, `init`, `list`, `remove`, `update` | [skill.md](skill.md) |
| `text` | `chat` | [text.md](text.md) |
| `token-plan` | `add-member`, `assign-seats`, `create-key`, `list-seats` | [token-plan.md](token-plan.md) |
| `update` | `(root)` | [update.md](update.md) |
| `usage` | `coding-plan`, `free`, `freetier`, `stats`, `summary`, `token-plan` | [usage.md](usage.md) |
| `workspace` | `init`, `list` | [workspace.md](workspace.md) |
## Global flags
Available on every command (in addition to command-specific flags):
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------- |
| `--output <format>` | string | no | Output format: text, json |
| `--timeout <seconds>` | number | no | Request timeout |
| `--quiet` | switch | no | Suppress non-essential output |
| `--verbose` | switch | no | Print HTTP request/response details |
| `--dry-run` | switch | no | Dry run mode |
| `--config <name>` | string | no | Use a config profile for this command |
| `--help` | switch | no | Show help |
| `--version` | switch | no | Print version |
## Model auth flags
Available on model-domain commands (API-key auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------ |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
## Console auth flags
Available on console-domain commands (console login auth); also listed per command below:
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
## OpenAPI auth flags
Available on OpenAPI-domain commands (AK/SK auth); also listed per command below:
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
## Notes
- Console commands (`app list`, `usage free`, `console call`) require `bl auth login --console`.
- Most API commands use `DASHSCOPE_API_KEY` or `bl auth login --api-key`.
- Token Plan commands use OpenAPI AK/SK via `bl auth login --open-api` or `ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`.
- Default output: **text** unless explicitly set to `json` with `--output`, `DASHSCOPE_OUTPUT`, or config.
reference/knowledge.md
# `bl knowledge` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| `bl knowledge category add` | API Key | Create a data-center category |
| `bl knowledge category delete` | API Key | Delete a data-center category |
| `bl knowledge category list` | API Key | List data-center categories |
| `bl knowledge chat` | API Key | Chat with a Bailian knowledge base (RAG Q&A with streaming) |
| `bl knowledge chunk add` | API Key | Add a chunk directly to a knowledge base |
| `bl knowledge chunk delete` | API Key | Delete chunks from a knowledge base (irreversible) |
| `bl knowledge chunk list` | API Key | List chunks in a knowledge base with content and status |
| `bl knowledge chunk update` | API Key | Update chunk content or toggle its retrieval visibility |
| `bl knowledge collection create` | API Key | Create a FILE data collection |
| `bl knowledge collection get` | API Key | Show data collection details |
| `bl knowledge create` | API Key | Create a knowledge base and import data-center files or categories |
| `bl knowledge delete` | API Key | Delete a knowledge base with all its documents and chunks |
| `bl knowledge doc delete` | API Key | Delete documents and their chunks from a knowledge base |
| `bl knowledge doc import-oss` | API Key | Batch import files from an authorized OSS bucket into the data center |
| `bl knowledge doc list` | API Key | List documents in a knowledge base with parse/index status |
| `bl knowledge doc status` | API Key | Check knowledge base import job status |
| `bl knowledge doc tag` | API Key | Batch update tags on data-center files |
| `bl knowledge doc upload` | API Key | Upload local files or directories to the data center and optionally import into a knowledge base |
| `bl knowledge file delete` | API Key | Permanently delete a file from the data center |
| `bl knowledge file get` | API Key | Show data-center file details (size, MD5, tags, timestamps) |
| `bl knowledge file list` | API Key | List files in a data-center category |
| `bl knowledge info` | API Key | Show knowledge base configuration details |
| `bl knowledge list` | API Key | List knowledge bases in the workspace |
| `bl knowledge retrieve` | API Key | Retrieve from a Bailian knowledge base (deprecated, use `search` instead) |
| `bl knowledge search` | API Key | Search a Bailian knowledge base (RAG semantic retrieval) |
| `bl knowledge service copy` | API Key | Copy a service into a new draft (name gets a copy\_ prefix) |
| `bl knowledge service create` | API Key | Create a retrieval / Q&A service (initial status: draft, version: beta) |
| `bl knowledge service delete` | API Key | Delete a retrieval / Q&A service (soft delete, idempotent) |
| `bl knowledge service deploy` | API Key | Publish the beta draft of a service as a new version |
| `bl knowledge service get` | API Key | Show service (agent) details including per-version configuration |
| `bl knowledge service list` | API Key | List retrieval / Q&A services (agents) in the workspace |
| `bl knowledge service update` | API Key | Update service name, description or draft configuration |
| `bl knowledge stats` | API Key | Show knowledge base storage and QPS monitoring data |
| `bl knowledge update` | API Key | Update knowledge base name, description or rerank threshold |
## Command details
### `bl knowledge category add`
| Field | Value |
| ------------------ | ------------------------------------------------- |
| **Name** | `knowledge category add` |
| **Description** | Create a data-center category |
| **Authentication** | API Key |
| **Usage** | `bl knowledge category add --name <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------ |
| `--name <text>` | string | yes | Category name (1-20 chars) |
| `--parent-id <id>` | string | no | Create as a sub-category of this category |
| `--collection-id <id>` | string | no | Create under this collection (defaults to the platform collection) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Use categories to organize data-center files by business domain.
#### Examples
```bash
bl knowledge category add --name product-docs --workspace-id ws-xxx
```
```bash
bl knowledge category add --name sub --parent-id cate-xxx
```
### `bl knowledge category delete`
| Field | Value |
| ------------------ | -------------------------------------------------------------------- |
| **Name** | `knowledge category delete` |
| **Description** | Delete a data-center category |
| **Authentication** | API Key |
| **Usage** | `bl knowledge category delete --category-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This deletes the selected data-center category and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--category-id <id>` | string | yes | Category ID to delete |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Behavior for categories containing files or sub-categories is server-defined — the server error is passed through as-is.
#### Examples
```bash
bl knowledge category delete --category-id cate-xxx --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge category delete --category-id cate-xxx --yes
```
### `bl knowledge category list`
| Field | Value |
| ------------------ | ------------------------------------ |
| **Name** | `knowledge category list` |
| **Description** | List data-center categories |
| **Authentication** | API Key |
| **Usage** | `bl knowledge category list [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `--collection-id <id>` | string | no | Filter by exact collection ID |
| `--parent-id <id>` | string | no | List sub-categories of this exact parent category |
| `--name <text>` | string | no | Filter by category name (exact match, unlike the knowledge base list) |
| `--next-token <token>` | string | no | Cursor for the next page (from previous output) |
| `--max-result <n>` | number | no | Items per page (default: 20) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Categories marked [default] are where files land when no category is specified.
- Pagination is cursor-based: reuse the printed next token to continue.
#### Examples
```bash
bl knowledge category list --workspace-id ws-xxx
```
```bash
bl knowledge category list --name my-category
```
```bash
bl knowledge category list --next-token <token>
```
### `bl knowledge chat`
| Field | Value |
| ------------------ | ------------------------------------------------------------ |
| **Name** | `knowledge chat` |
| **Description** | Chat with a Bailian knowledge base (RAG Q&A with streaming) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge chat --message <text> --agent-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `--message <text>` | array | no | Message text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format |
| `--agent-id <id>` | string | yes | Q&A service ID (find in console knowledge Q&A page) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--agent-version <version>` | string | no | Service version to call: beta (draft for debugging) or a published number; default is the latest published version |
| `--image <url>` | array | no | Image URL (repeatable). Attached to the last user message as multimodal content |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Response is returned as SSE stream events. Event lifecycle: tool_calling → tool_return → plan_start → planning → plan_end → generation_start → generating → generation_end. tool_calling → tool_return may loop multiple times.
- Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
- `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.
- Multi-turn: use --message "user:..." and --message "assistant:..." to pass conversation history.
- `--agent-version beta` calls the draft config for debugging before it is deployed.
#### Examples
```bash
bl knowledge chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
bl knowledge chat --message "user:What is RAG?" --message "assistant:RAG is..." --message "How does it work?" --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
bl knowledge chat --message "Describe these images" --image https://example.com/a.png --image https://example.com/b.png --agent-id aid-xxx --workspace-id ws-xxx
```
### `bl knowledge chunk add`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------ |
| **Name** | `knowledge chunk add` |
| **Description** | Add a chunk directly to a knowledge base |
| **Authentication** | API Key |
| **Usage** | `bl knowledge chunk add --index-id <id> (--content <text> \| --field <k=v>) [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--doc-id <id>` | string | no | Owning document ID from the doc list command; required in practice for all knowledge base types |
| `--content <text>` | string | no | Chunk body text, up to 6000 chars (document-type); alternative to --content-file |
| `--content-file <path>` | string | no | Read chunk body from a UTF-8 plain text file (.md/.txt etc.) |
| `--title <text>` | string | no | Chunk title, up to 50 chars (document-type) |
| `--image-url <url>` | array | no | Chunk image URL (repeatable, up to 10; document-type) |
| `--field <key=value>` | array | no | Arbitrary field entry (repeatable) for table/image knowledge bases where keys are Excel column headers; mutually exclusive with content/title/image flags |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Document / table / image knowledge bases are supported; audio-video ones are not.
- --doc-id is required in practice for all knowledge base types. Use the document-level id from the doc list command; the per-row doc_id in chunk list output is not accepted.
- Image-type documents do not support text chunks. Target a text-type document (docx/pdf/txt) instead.
- The API is idempotent but rate-limited to 10 calls per second — throttle batch scripts.
- The response carries no chunk id; list chunks afterwards to find the new one.
- For table/image knowledge bases use --field with Excel column headers as keys; values are passed through as strings.
#### Examples
```bash
bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
```
```bash
bl knowledge chunk add --index-id idx-xxx --field columnA=v1 --field columnB=v2
```
### `bl knowledge chunk delete`
| Field | Value |
| ------------------ | ------------------------------------------------------------------- |
| **Name** | `knowledge chunk delete` |
| **Description** | Delete chunks from a knowledge base (irreversible) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the selected chunks and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--chunk-id <id>` | array | yes | Chunk ID to delete (repeatable; batches of 10 are sent automatically) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Accepts at most 10 chunk ids per call; larger sets are batched automatically.
#### Examples
```bash
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
```
### `bl knowledge chunk list`
| Field | Value |
| ------------------ | ------------------------------------------------------- |
| **Name** | `knowledge chunk list` |
| **Description** | List chunks in a knowledge base with content and status |
| **Authentication** | API Key |
| **Usage** | `bl knowledge chunk list --index-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--doc-id <id>` | string | no | Only show chunks belonging to this document |
| `--page-number <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size per request |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Use metadata.\_id as the chunk id and metadata.doc_id as the document id in chunk update/delete commands.
- Page size defaults to 20 (server default), max 100.
#### Examples
```bash
bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
```
```bash
bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
```
### `bl knowledge chunk update`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------- |
| **Name** | `knowledge chunk update` |
| **Description** | Update chunk content or toggle its retrieval visibility |
| **Authentication** | API Key |
| **Usage** | `bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--chunk-id <id>` | string | yes | Chunk ID (metadata.\_id from the chunk list output) |
| `--doc-id <id>` | string | yes | Document ID owning the chunk (metadata.doc_id from the chunk list output) |
| `--content <text>` | string | no | New chunk content, 10-6000 chars; alternative to --content-file |
| `--content-file <path>` | string | no | Read new content from a UTF-8 plain text file (.md/.txt etc.) |
| `--title <text>` | string | no | Chunk title, 0-50 chars (empty string clears it; omit to keep unchanged) |
| `--exclude` | switch | no | Exclude this chunk from retrieval |
| `--include` | switch | no | Include this chunk in retrieval (default) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Content must be 10-6000 characters and within the knowledge base's max chunk size.
- --content-file expects a UTF-8 plain text file; document formats (.docx/.pdf) are not parsed here.
- Toggling --exclude/--include without new content re-submits the existing content automatically.
#### Examples
```bash
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text"
```
```bash
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
```
### `bl knowledge collection create`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------- |
| **Name** | `knowledge collection create` |
| **Description** | Create a FILE data collection |
| **Authentication** | API Key |
| **Usage** | `bl knowledge collection create --name <text> --description <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `--name <text>` | string | yes | Collection name |
| `--description <text>` | string | yes | What this collection holds and what it is for — tells collections apart in the list |
| `--store-type <type>` | string | no | Storage: platform (managed) or custom (your own OSS bucket) |
| `--oss-region <id>` | string | no | OSS region id (required with --store-type custom) |
| `--oss-bucket <name>` | string | no | OSS bucket name (required with --store-type custom) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Store type defaults to platform (managed storage); custom uses your authorized OSS bucket.
- Custom buckets must carry the bucket tag bailian-connector-access=ReadAndWrite (Bailian's tag-based access control); without it the server rejects creation with a misleading 'setBucketCORS failed' error.
- There is no collection delete API — create collections deliberately.
#### Examples
```bash
bl knowledge collection create --name my-collection --description 'team docs' --workspace-id ws-xxx
```
```bash
bl knowledge collection create --name oss-coll --description 'own bucket' --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
```
### `bl knowledge collection get`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------- |
| **Name** | `knowledge collection get` |
| **Description** | Show data collection details |
| **Authentication** | API Key |
| **Usage** | `bl knowledge collection get (--collection-id <id> \| --name <text>) [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--collection-id <id>` | string | no | Collection ID; alternative to --name |
| `--name <text>` | string | no | Collection name; alternative to --collection-id |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl knowledge collection get --collection-id conn-xxx --workspace-id ws-xxx
```
```bash
bl knowledge collection get --name my-collection
```
### `bl knowledge create`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **Name** | `knowledge create` |
| **Description** | Create a knowledge base and import data-center files or categories |
| **Authentication** | API Key |
| **Usage** | `bl knowledge create --name <text> --description <text> (--doc-id <id> \| --category-id <id>) [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `--name <text>` | string | yes | Knowledge base name (1-20 chars, unique in workspace) |
| `--description <text>` | string | yes | What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars) |
| `--doc-id <id>` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id |
| `--category-id <id>` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id |
| `--embedding-model <name>` | string | no | Embedding model name (default: text-embedding-v4) |
| `--chunk-size <n>` | number | no | Chunk size in characters (default: 600, recommended 300-800) |
| `--wait` | switch | no | Poll the initial import job to a terminal state |
| `--poll-interval <seconds>` | number | no | Polling interval when waiting (default: 5) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Structure/sink types are fixed to the default document knowledge base (unstructured, BUILT_IN storage).
- Returns the knowledge base id (pipelineId) and the initial import job id (ingestionId).
- Use the import job status command (or --wait) to track the initial import.
#### Examples
```bash
bl knowledge create --name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx
```
```bash
bl knowledge create --name demo --description 'product docs' --category-id cate-xxx --wait
```
### `bl knowledge delete`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **Name** | `knowledge delete` |
| **Description** | Delete a knowledge base with all its documents and chunks |
| **Authentication** | API Key |
| **Usage** | `bl knowledge delete --index-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the knowledge base and all of its documents and chunks. Data-center files are not deleted. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Irreversible — the knowledge base and all indexed content are permanently removed.
- Files in the data center are not affected; only the knowledge base index is deleted.
#### Examples
```bash
bl knowledge delete --index-id idx-xxx --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge delete --index-id idx-xxx --yes
```
### `bl knowledge doc delete`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------ |
| **Name** | `knowledge doc delete` |
| **Description** | Delete documents and their chunks from a knowledge base |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc delete --index-id <id> --doc-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the selected documents and all of their chunks. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--doc-id <id>` | array | yes | Document ID to delete (repeatable) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Removes documents from the knowledge base index only; the source files remain in the data center.
- Use the doc_id from `knowledge doc list --quiet`, not the fileId from `knowledge doc upload`. For documents created via `knowledge create --doc-id`, the doc_id equals the fileId; for documents imported via `knowledge doc upload --index-id`, the doc_id may include a workspace suffix.
- Deletion may take up to ~30s to propagate — the document may still appear in the doc list briefly.
- The output lists the ids actually deleted.
#### Examples
```bash
bl knowledge doc delete --index-id idx-xxx --doc-id file-xxx --workspace-id ws-xxx --dry-run
```
```bash
# Only after explicit user confirmation:
bl knowledge doc delete --index-id idx-xxx --doc-id file-a --doc-id file-b --yes
```
### `bl knowledge doc import-oss`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------- |
| **Name** | `knowledge doc import-oss` |
| **Description** | Batch import files from an authorized OSS bucket into the data center |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--bucket <name>` | string | yes | Authorized OSS bucket name |
| `--region <id>` | string | yes | OSS region id (e.g. cn-beijing) |
| `--oss-key <key>` | array | yes | OSS object key to import (repeatable, 1-10 per call) |
| `--category-id <id>` | string | no | Target data-center category (default: the default category) |
| `--tag <text>` | array | no | File tag applied to every imported file (repeatable, up to 10) |
| `--overwrite` | switch | no | Overwrite files previously imported from the same OSS keys |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- The bucket must be authorized to the platform service role beforehand; permission errors from the server are passed through with a pointer to check AliyunServiceRoleForBailian in the RAM console.
- File names are derived from the OSS key basename.
- --overwrite replaces the previously imported file and issues a NEW fileId (the old one becomes invalid) — verified live.
#### Examples
```bash
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
```
```bash
bl knowledge doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
```
### `bl knowledge doc list`
| Field | Value |
| ------------------ | ---------------------------------------------------------- |
| **Name** | `knowledge doc list` |
| **Description** | List documents in a knowledge base with parse/index status |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc list --index-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--page-number <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size per request |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Documents with status FAILED are highlighted in text mode — use the import job status command to inspect failures.
- Page size defaults to 10 (server default), max 100.
#### Examples
```bash
bl knowledge doc list --index-id idx-xxx --workspace-id ws-xxx
```
```bash
bl knowledge doc list --index-id idx-xxx --page-size 100
```
### `bl knowledge doc status`
| Field | Value |
| ------------------ | --------------------------------------------------------------- |
| **Name** | `knowledge doc status` |
| **Description** | Check knowledge base import job status |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc status --index-id <id> --job-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--job-id <id>` | string | yes | Import job ID (ingestionId returned by import commands) |
| `--page-number <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size per request |
| `--wait` | switch | no | Poll until the job reaches a terminal state |
| `--poll-interval <seconds>` | number | no | Polling interval when waiting (default: 5) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Both --index-id and --job-id are required (passing only one returns SystemError).
- If you see a SystemError, the job may not exist — check the ingestion id in the document list output.
- Overall job states are PENDING / RUNNING / COMPLETED; per-document failures (for example PARSE_FAILED) exit non-zero with the error message passed through.
#### Examples
```bash
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
```
```bash
bl knowledge doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
```
### `bl knowledge doc tag`
| Field | Value |
| ------------------ | --------------------------------------------------------- |
| **Name** | `knowledge doc tag` |
| **Description** | Batch update tags on data-center files |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc tag --doc-id <id> --tag <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--doc-id <id>` | array | yes | Data-center file ID to tag (repeatable, 1-20 per call) |
| `--tag <text>` | array | yes | Tag applied to every --doc-id (repeatable, each up to 32 chars) |
| `--mode <mode>` | string | no | Update mode: append (default) or overwrite |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- The same tag set is applied to every --doc-id; run the command multiple times for different tag sets.
- Server limits: up to 100 tags per file, total tag length up to 700 chars, tag up to 32 chars.
#### Examples
```bash
bl knowledge doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
```
```bash
bl knowledge doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
```
### `bl knowledge doc upload`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `knowledge doc upload` |
| **Description** | Upload local files or directories to the data center and optionally import into a knowledge base |
| **Authentication** | API Key |
| **Usage** | `bl knowledge doc upload --file <path> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------- |
| `--file <path>` | array | yes | Local file or directory path (repeatable). Directories are scanned recursively; unsupported formats are skipped |
| `--index-id <id>` | string | no | Import into this knowledge base after registration (one job for all files) |
| `--category-id <id>` | string | no | Target data-center category; defaults to the workspace default category |
| `--tag <text>` | array | no | File tag (repeatable), applied to every uploaded file |
| `--wait` | switch | no | Poll the import job to a terminal state (needs --index-id) |
| `--poll-interval <seconds>` | number | no | Polling interval when waiting (default: 5) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Pipeline: apply upload lease → PUT to OSS → register file → (with --index-id) create import job.
- Without --category-id the workspace default category is resolved automatically.
- Directories are scanned recursively; node_modules, .git, and similar are skipped automatically.
- Multiple files are processed sequentially; on failure, already-registered file ids are listed in the error hint.
#### Examples
```bash
bl knowledge doc upload --file ./a.md --workspace-id ws-xxx
```
```bash
bl knowledge doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
```
```bash
bl knowledge doc upload --file ./docs/ --workspace-id ws-xxx
```
```bash
bl knowledge doc upload --file ./docs/ --dry-run --verbose
```
### `bl knowledge file delete`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Name** | `knowledge file delete` |
| **Description** | Permanently delete a file from the data center |
| **Authentication** | API Key |
| **Usage** | `bl knowledge file delete --file-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This permanently deletes the data-center file. Knowledge-base document indexes that reference it may become invalid. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--file-id <id>` | string | yes | Data-center file ID to delete |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Irreversible. If knowledge bases reference this file, their related document indexes become invalid.
- To remove a document from a single knowledge base only, use the document delete command instead.
#### Examples
```bash
bl knowledge file delete --file-id file-xxx --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge file delete --file-id file-xxx --yes
```
### `bl knowledge file get`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `knowledge file get` |
| **Description** | Show data-center file details (size, MD5, tags, timestamps) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge file get --file-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--file-id <id>` | string | yes | Data-center file ID |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl knowledge file get --file-id file-xxx --workspace-id ws-xxx
```
### `bl knowledge file list`
| Field | Value |
| ------------------ | --------------------------------------------------- |
| **Name** | `knowledge file list` |
| **Description** | List files in a data-center category |
| **Authentication** | API Key |
| **Usage** | `bl knowledge file list --category-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------- |
| `--category-id <id>` | string | yes | Category to list (find ids via the category list command); exact match |
| `--name <text>` | string | no | Filter by exact file name without its extension (a.md → pass a) |
| `--file-id <id>` | array | no | Filter by exact file ID (repeatable) |
| `--next-token <token>` | string | no | Cursor for the next page (from previous output) |
| `--max-result <n>` | number | no | Items per page |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- A real category id is required — the default value is not resolved here. Find the id via the category list command.
- --name matches the exact file name without its extension (for a.md pass a); partial keywords return no results.
- Pagination is cursor-based: reuse the printed next token to continue.
#### Examples
```bash
bl knowledge file list --category-id cate-xxx --workspace-id ws-xxx
```
```bash
bl knowledge file list --category-id cate-xxx --name report
```
### `bl knowledge info`
| Field | Value |
| ------------------ | ------------------------------------------- |
| **Name** | `knowledge info` |
| **Description** | Show knowledge base configuration details |
| **Authentication** | API Key |
| **Usage** | `bl knowledge info --index-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Indexing settings are immutable; changing them requires recreating the knowledge base.
#### Examples
```bash
bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
```
### `bl knowledge list`
| Field | Value |
| ------------------ | ------------------------------------- |
| **Name** | `knowledge list` |
| **Description** | List knowledge bases in the workspace |
| **Authentication** | API Key |
| **Usage** | `bl knowledge list [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--name <text>` | string | no | Filter by knowledge base name (fuzzy match, 1-20 chars) |
| `--page-number <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size per request |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Auth: uses DashScope API Key (Bearer token).
- `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or config workspace_id.
- Use the returned id as --index-id in knowledge base / document management commands.
#### Examples
```bash
bl knowledge list --workspace-id ws-xxx
```
```bash
bl knowledge list --name demo --page-number 2 --page-size 50
```
### `bl knowledge retrieve`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------- |
| **Name** | `knowledge retrieve` |
| **Description** | Retrieve from a Bailian knowledge base (deprecated, use `search` instead) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge retrieve --index-id <id> --query <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------- | ------ | -------- | -------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base index ID (required) |
| `--query <text>` | string | yes | Search query (required) |
| `--dense-similarity-top-k <n>` | number | no | Dense retrieval top K |
| `--sparse-similarity-top-k <n>` | number | no | Sparse retrieval top K |
| `--rerank` | switch | no | Enable reranking |
| `--rerank-top-n <n>` | number | no | Rerank top N results |
| `--rerank-model <name>` | string | no | Rerank model, e.g. qwen3-rerank-hybrid |
| `--rerank-mode <mode>` | string | no | Rerank mode: qa, similar, or custom |
| `--rerank-instruct <text>` | string | no | Custom rerank instruction, when mode=custom |
| `--top-k <n>` | number | no | Number of results (deprecated, use --rerank-top-n) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- --rerank-model requires the target knowledge base to already have a rerank model configured; otherwise every value is rejected.
#### Examples
```bash
bl knowledge retrieve --index-id idx_xxx --query "How to use Alibaba Cloud Bailian"
```
```bash
bl knowledge retrieve --index-id idx_xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
```
### `bl knowledge search`
| Field | Value |
| ------------------ | ------------------------------------------------------------ |
| **Name** | `knowledge search` |
| **Description** | Search a Bailian knowledge base (RAG semantic retrieval) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge search --query <text> --agent-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `--query <text>` | string | yes | Search query text (required, cannot be empty) |
| `--agent-id <id>` | string | yes | Retrieval service ID (find in console knowledge retrieval page) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--agent-version <version>` | string | no | Service version to call: beta (draft for debugging) or a published number; default is the latest published version |
| `--image <url>` | array | no | Image URL for multimodal retrieval (repeatable) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Retrieval scope and strategy (multi-index weighting, routing, reranking, etc.) are driven by the agent_id service config. Only query and agent_id are required.
- Auth: uses DashScope API Key (Bearer token). Get yours from the console API Key page.
- `--workspace-id` can be set via BAILIAN_WORKSPACE_ID env or `kscli config set workspace_id <id>`.
- `--agent-version beta` calls the draft config for debugging before it is deployed.
#### Examples
```bash
bl knowledge search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
bl knowledge search --api-key $DASHSCOPE_API_KEY --query "test search" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
```
### `bl knowledge service copy`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `knowledge service copy` |
| **Description** | Copy a service into a new draft (name gets a copy\_ prefix) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service copy --agent-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--agent-id <id>` | string | yes | Source service (agent) ID to copy |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- The copy starts as a beta draft; test it with --agent-version beta, then deploy to publish.
- Requires the knowledge-base create permission in the workspace.
#### Examples
```bash
bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx
```
### `bl knowledge service create`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------- |
| **Name** | `knowledge service create` |
| **Description** | Create a retrieval / Q&A service (initial status: draft, version: beta) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service create --name <text> --scene <chat\|search> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `--name <text>` | string | yes | Service name (up to 200 chars, unique per scene in the workspace) |
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval) |
| `--description <text>` | string | no | What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars) |
| `--index-id <id>` | string | no | Bind this knowledge base; other settings use server defaults |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Without an explicit configuration the server applies its default agent settings.
- The draft (beta) version can be tested via --agent-version beta on search/chat before deploying.
- Requires the knowledge-base create permission in the workspace.
#### Examples
```bash
bl knowledge service create --name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx
```
```bash
bl knowledge service create --name my-search --scene search --index-id idx-xxx
```
### `bl knowledge service delete`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Name** | `knowledge service delete` |
| **Description** | Delete a retrieval / Q&A service (soft delete, idempotent) |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service delete --agent-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This deletes the service and makes its agent ID unavailable for search and chat calls. The operation cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--agent-id <id>` | string | yes | Service (agent) ID |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Deletion cannot be undone; the agent_id becomes unusable for search and chat calls.
- Idempotent — deleting an already-deleted service does not fail.
- Requires the knowledge-base delete permission in the workspace.
#### Examples
```bash
bl knowledge service delete --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge service delete --agent-id aid-xxx --yes
```
### `bl knowledge service deploy`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `knowledge service deploy` |
| **Description** | Publish the beta draft of a service as a new version |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service deploy --agent-id <id> [flags]` |
| **Risk** | `high` |
| **Risk message** | This publishes the current draft as a new version and changes the behavior seen by live callers. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ----------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--agent-id <id>` | string | yes | Service (agent) ID |
| `--version-desc <text>` | string | no | Description for the newly published version |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- The version number auto-increments; status becomes deployed.
- Publishing affects live callers — the confirmation prompt guards against accidents.
- Requires the knowledge-base modify permission in the workspace.
#### Examples
```bash
bl knowledge service deploy --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
# Only after explicit user confirmation:
bl knowledge service deploy --agent-id aid-xxx --version-desc 'tuned rerank params' --yes
```
### `bl knowledge service get`
| Field | Value |
| ------------------ | ---------------------------------------------------------------- |
| **Name** | `knowledge service get` |
| **Description** | Show service (agent) details including per-version configuration |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service get --agent-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `--agent-id <id>` | string | yes | Service (agent) ID |
| `--agent-version <version>` | string | no | Specific version to inspect (beta or a published number); omit for all versions |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Without --agent-version all versions are returned (beta draft plus published numbers).
- The version value is passed through as-is; the valid set is server-side state.
#### Examples
```bash
bl knowledge service get --agent-id aid-xxx --workspace-id ws-xxx
```
```bash
bl knowledge service get --agent-id aid-xxx --agent-version beta
```
### `bl knowledge service list`
| Field | Value |
| ------------------ | ---------------------------------------------------------- |
| **Name** | `knowledge service list` |
| **Description** | List retrieval / Q&A services (agents) in the workspace |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service list --scene <chat\|search> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval) |
| `--status <status>` | string | no | Filter by status: draft, deployed (includes edited) or deleted |
| `--name <text>` | string | no | Filter by service name (fuzzy match) |
| `--agent-id <id>` | string | no | Filter by exact agent ID |
| `--index-id <id>` | string | no | Filter by exact linked knowledge base (pipeline) ID |
| `--page-number <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size per request |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- A scene (chat or search) is required — run once per scene to see both.
- Use the returned agent_id with the search or chat commands, or with service management commands.
#### Examples
```bash
bl knowledge service list --scene chat --workspace-id ws-xxx
```
```bash
bl knowledge service list --scene search --status deployed
```
### `bl knowledge service update`
| Field | Value |
| ------------------ | ------------------------------------------------------- |
| **Name** | `knowledge service update` |
| **Description** | Update service name, description or draft configuration |
| **Authentication** | API Key |
| **Usage** | `bl knowledge service update --agent-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--agent-id <id>` | string | yes | Service (agent) ID |
| `--name <text>` | string | no | New service name (up to 200 chars) |
| `--description <text>` | string | no | New service description (up to 1000 chars) |
| `--agent-version <version>` | string | no | Target version (default: beta draft). Published versions only accept --version-desc |
| `--version-desc <text>` | string | no | Version description |
| `--policy <policy>` | string | no | Agent policy: turbo (fast) or agentic (multi-turn) |
| `--model <name>` | string | no | Generation model code (must be in the platform allowlist) |
| `--temperature <n>` | number | no | Sampling temperature, range 0-2 |
| `--max-llm-calls <n>` | number | no | Max LLM calls per request, range 1-30 |
| `--enable-session-file <bool>` | string | no | Enable session files: true or false |
| `--enable-refusal <bool>` | string | no | Enable refusal answers: true or false |
| `--enable-anti-leak <bool>` | string | no | Enable anti prompt-leak: true or false |
| `--enable-rich-text <bool>` | string | no | Enable rich text output: true or false |
| `--enable-citation <bool>` | string | no | Enable citations: true or false |
| `--config-file <path>` | string | no | JSON file replacing the whole agent_config (for nested settings like kb_search_configs); mutually exclusive with scalar config flags |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Configuration changes only apply to the beta draft; published versions accept --version-desc only.
- To change the configuration of a published version, first update the beta draft (this command without --agent-version or with --agent-version beta), then run service deploy to publish a new version.
- Scalar config flags merge into the current draft config (read-merge-write); --config-file replaces the whole config and is mutually exclusive with them.
- After updating the draft, verify with --agent-version beta on search/chat, then deploy.
- Requires the knowledge-base modify permission in the workspace.
#### Examples
```bash
bl knowledge service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
```
```bash
bl knowledge service update --agent-id aid-xxx --config-file ./agent-config.json
```
```bash
bl knowledge service update --agent-id aid-xxx --agent-version 1 --version-desc 'first stable release'
```
### `bl knowledge stats`
| Field | Value |
| ------------------ | --------------------------------------------------- |
| **Name** | `knowledge stats` |
| **Description** | Show knowledge base storage and QPS monitoring data |
| **Authentication** | API Key |
| **Usage** | `bl knowledge stats --index-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--start <time>` | string | no | Range start: Unix seconds or ISO date, must be in the past (default: 24 hours ago) |
| `--end <time>` | string | no | Range end: Unix seconds or ISO date, must be in the past (default: now) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Defaults to the last 24 hours when --start/--end are omitted.
- Timestamps are normalized to epoch seconds as required by the server.
- Future timestamps are rejected for --start and clamped to now for --end, since the monitor API only returns past data.
#### Examples
```bash
bl knowledge stats --index-id idx-xxx --workspace-id ws-xxx
```
```bash
bl knowledge stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
```
### `bl knowledge update`
| Field | Value |
| ------------------ | ----------------------------------------------------------- |
| **Name** | `knowledge update` |
| **Description** | Update knowledge base name, description or rerank threshold |
| **Authentication** | API Key |
| **Usage** | `bl knowledge update --index-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------------- | ------ | -------- | --------------------------------------------------------------------- |
| `--index-id <id>` | string | yes | Knowledge base ID |
| `--name <text>` | string | no | New knowledge base name (1-20 chars) |
| `--description <text>` | string | no | New knowledge base description |
| `--rerank-min-score <score>` | number | no | Rerank minimum score threshold, range 0-1 (chunks below are filtered) |
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Indexing settings (embedding model, chunk size, etc.) are immutable — recreate the knowledge base to change them.
#### Examples
```bash
bl knowledge update --index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx
```
```bash
bl knowledge update --index-id idx-xxx --rerank-min-score 0.3
```
reference/mcp.md
# `bl mcp` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| -------------- | -------------- | ----------------------------------------------------- |
| `bl mcp call` | API Key | Call a tool on an MCP server (tools/call) |
| `bl mcp list` | Console | List MCP servers activated under your Bailian account |
| `bl mcp tools` | API Key | List tools exposed by an MCP server (tools/list) |
## Command details
### `bl mcp call`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------------- |
| **Name** | `mcp call` |
| **Description** | Call a tool on an MCP server (tools/call) |
| **Authentication** | API Key |
| **Usage** | `bl mcp call --target <server.tool> [--arg k=v ...] [--json '{...}'] [--url <url>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `--target <server.tool>` | string | yes | Server code and tool name joined by a dot, e.g. market-cmapi00073529.SmartStockSelection |
| `--arg <kv>` | array | no | Tool argument (repeatable). Values parsed as JSON if possible, else string. |
| `--json <obj>` | string | no | Full arguments object as JSON; merged with --arg (arg wins). |
| `--query <text>` | string | no | Shortcut for --arg query=<text> (mirrors many DashScope MCP tools). |
| `--url <url>` | string | no | Override the MCP endpoint URL (non-Bailian). Tries Streamable HTTP first, then classic SSE on the same URL. |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl mcp call --target market-cmapi00073529.SmartStockSelection --query "Screen consumer stocks with ROE > 15%"
```
```bash
bl mcp call --target market-cmapi00073529.FinQuery --json '{"q":"Guizhou Maotai","limit":5}'
```
```bash
bl mcp call --target market-cmapi00073529.SmartFundSelection --arg riskLevel=R3 --arg minScale=10
```
### `bl mcp list`
| Field | Value |
| ------------------ | ----------------------------------------------------- |
| **Name** | `mcp list` |
| **Description** | List MCP servers activated under your Bailian account |
| **Authentication** | Console |
| **Usage** | `bl mcp list [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--name <text>` | string | no | Filter by server name (substring match) |
| `--type <type>` | string | no | Server type: OFFICIAL \| PRIVATE (default: OFFICIAL) |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 30) |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl mcp list
```
```bash
bl mcp list --name finance
```
```bash
bl mcp list --output json
```
### `bl mcp tools`
| Field | Value |
| ------------------ | ------------------------------------------------ |
| **Name** | `mcp tools` |
| **Description** | List tools exposed by an MCP server (tools/list) |
| **Authentication** | API Key |
| **Usage** | `bl mcp tools --server <code> [--url <url>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `--server <code>` | string | yes | Server code from `mcp list` (e.g. market-cmapi00073529) |
| `--url <url>` | string | no | Override the MCP endpoint URL (non-Bailian). Tries Streamable HTTP first, then classic SSE on the same URL. |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl mcp tools --server market-cmapi00073529
```
```bash
bl mcp tools --server market-cmapi00073529 --output json
```
```bash
bl mcp tools --server my-server --url https://example.com/mcp
```
reference/memory.md
# `bl memory` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| -------------------------- | -------------- | ------------------------------------------------- |
| `bl memory add` | API Key | Add memory from messages or custom content |
| `bl memory delete` | API Key | Delete a memory node |
| `bl memory list` | API Key | List memory nodes for a user |
| `bl memory profile create` | API Key | Create a user profile schema for memory profiling |
| `bl memory profile get` | API Key | Get user profile by schema ID and user ID |
| `bl memory search` | API Key | Search memory nodes by query or messages |
| `bl memory update` | API Key | Update a memory node content |
## Command details
### `bl memory add`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------------- |
| **Name** | `memory add` |
| **Description** | Add memory from messages or custom content |
| **Authentication** | API Key |
| **Usage** | `bl memory add --user-id <id> [--messages <json>] [--content <text>] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | ---------------------------------------------------------- |
| `--user-id <id>` | string | yes | User ID (required) |
| `--messages <json>` | string | no | Messages JSON array: [{"role":"user","content":"..."},...] |
| `--content <text>` | string | no | Custom content text to memorize |
| `--profile-schema <id>` | string | no | Profile schema ID for user profiling |
| `--memory-library-id <id>` | string | no | Memory library ID (isolate memory space) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory add --user-id user1 --content "The user likes Python programming"
```
```bash
bl memory add --user-id user1 --messages '[{"role":"user","content":"I like traveling"}]'
```
```bash
bl memory add --user-id user1 --content "Lives in Beijing" --profile-schema schema_xxx
```
### `bl memory delete`
| Field | Value |
| ------------------ | ------------------------------------------------ |
| **Name** | `memory delete` |
| **Description** | Delete a memory node |
| **Authentication** | API Key |
| **Usage** | `bl memory delete --node-id <id> --user-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | --------------------------------------- |
| `--node-id <id>` | string | yes | Memory node ID (required) |
| `--user-id <id>` | string | yes | User ID (required) |
| `--memory-library-id <id>` | string | no | Memory library ID (non-default library) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory delete --node-id node_xxx --user-id user1
```
### `bl memory list`
| Field | Value |
| ------------------ | --------------------------------------- |
| **Name** | `memory list` |
| **Description** | List memory nodes for a user |
| **Authentication** | API Key |
| **Usage** | `bl memory list --user-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | ------------------------------ |
| `--user-id <id>` | string | yes | User ID (required) |
| `--page-size <n>` | number | no | Results per page (default: 10) |
| `--page <n>` | number | no | Page number (default: 1) |
| `--memory-library-id <id>` | string | no | Memory library ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory list --user-id user1
```
```bash
bl memory list --user-id user1 --page-size 20 --page 2
```
### `bl memory profile create`
| Field | Value |
| ------------------ | -------------------------------------------------------------------- |
| **Name** | `memory profile create` |
| **Description** | Create a user profile schema for memory profiling |
| **Authentication** | API Key |
| **Usage** | `bl memory profile create --name <name> --attributes <json> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ----------------------------------------------------------- |
| `--name <name>` | string | yes | Schema name (required) |
| `--description <text>` | string | no | Schema description |
| `--attributes <json>` | string | yes | Attributes JSON array: [{"name":"age","description":"age"}] |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory profile create --name "user_basic" --attributes '[{"name":"age","description":"age"},{"name":"hobby","description":"hobby"}]'
```
### `bl memory profile get`
| Field | Value |
| ------------------ | ------------------------------------------------------- |
| **Name** | `memory profile get` |
| **Description** | Get user profile by schema ID and user ID |
| **Authentication** | API Key |
| **Usage** | `bl memory profile get --schema-id <id> --user-id <id>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------- |
| `--schema-id <id>` | string | yes | Profile schema ID (required) |
| `--user-id <id>` | string | yes | User ID (required) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory profile get --schema-id schema_xxx --user-id user1
```
### `bl memory search`
| Field | Value |
| ------------------ | ---------------------------------------------------------- |
| **Name** | `memory search` |
| **Description** | Search memory nodes by query or messages |
| **Authentication** | API Key |
| **Usage** | `bl memory search --user-id <id> [--query <text>] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | -------------------------------------------- |
| `--user-id <id>` | string | yes | User ID (required) |
| `--query <text>` | string | no | Search query text |
| `--messages <json>` | string | no | Messages JSON array for context-based search |
| `--top-k <n>` | number | no | Number of results to return (default: 10) |
| `--memory-library-id <id>` | string | no | Memory library ID |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory search --user-id user1 --query "programming preferences"
```
```bash
bl memory search --user-id user1 --messages '[{"role":"user","content":"recommend a book"}]' --top-k 5
```
### `bl memory update`
| Field | Value |
| ------------------ | ----------------------------------------------------------------- |
| **Name** | `memory update` |
| **Description** | Update a memory node content |
| **Authentication** | API Key |
| **Usage** | `bl memory update --node-id <id> --user-id <id> --content <text>` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | ------------------------------------------ |
| `--node-id <id>` | string | yes | Memory node ID (required) |
| `--user-id <id>` | string | yes | User ID (required) |
| `--content <text>` | string | yes | New content for the memory node (required) |
| `--memory-library-id <id>` | string | no | Memory library ID (non-default library) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl memory update --node-id node_xxx --user-id user1 --content "updated memory content"
```
reference/model.md
# `bl model` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| --------------- | -------------- | ---------------------------------------------------------------------------------- |
| `bl model list` | No Auth | Browse model families or show detailed model info in the Bailian model marketplace |
## Command details
### `bl model list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `model list` |
| **Description** | Browse model families or show detailed model info in the Bailian model marketplace |
| **Authentication** | No Auth |
| **Usage** | `bl model list [--model <model>] [--page <n>] [--page-size <n>] [--provider <p>] [--capability <c>] [--feature <f>] [--enrich]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `--model <model>` | string | no | Show full details of a specific model family (switches to detail mode) |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 10) |
| `--provider <p>` | array | no | Filter by provider (repeatable, e.g. --provider alibaba --provider deepseek) |
| `--capability <c>` | array | no | Filter by capability code (TG, Reasoning, VU, IG, VG, TTS, ASR, …) |
| `--feature <f>` | array | no | Filter by feature (function-calling, web-search, structured-outputs, …) |
| `--context-window <w>` | array | no | Filter by context window range bucket |
| `--enrich` | switch | no | Also fetch input parameter schema (predictConfig) for trunk models (detail mode only) |
#### Notes
- Both the catalog and --enrich parameter-schema endpoints are public — no console login needed.
#### Examples
```bash
bl model list
```
```bash
bl model list --provider alibaba
```
```bash
bl model list --capability TG --capability Reasoning
```
```bash
bl model list --model qwen-max
```
```bash
bl model list --model qwen-max --enrich --output json
```
```bash
bl model list --feature function-calling --output json
```
reference/permission.md
# `bl permission` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------------- | -------------- | ------------------------------------------------------------------------ |
| `bl permission grant` | API Key | Grant model permissions (inference / finetune / deploy) |
| `bl permission list` | API Key | List model permissions (inference / fine-tune / deploy) in the workspace |
| `bl permission revoke` | API Key | Revoke model permissions (inference / finetune / deploy) |
## Command details
### `bl permission grant`
| Field | Value |
| ------------------ | -------------------------------------------------------------------- |
| **Name** | `permission grant` |
| **Description** | Grant model permissions (inference / finetune / deploy) |
| **Authentication** | API Key |
| **Usage** | `bl permission grant --model <models> [--action <actions>] \| --all` |
#### Flags
| Flag | Type | Required | Description |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `--model <models>` | string | no | Model ID(s), comma-separated (max 20) |
| `--action <actions>` | string | no | Permission action(s), comma-separated: inference, finetune, deploy (default: inference) |
| `--all` | switch | no | One-key grant inference for all models in the workspace (including future ones) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Grants apply to the business workspace your API key belongs to.
- --all maps to the server one-key switch (access_all_entities: OPEN) and only covers inference.
- Actions you omit keep their current grants (server-side tri-state patch).
#### Examples
```bash
bl permission grant --model qwen-plus
```
```bash
bl permission grant --model qwen-plus,qwen3-max --action inference,finetune
```
```bash
bl permission grant --all
```
```bash
bl permission grant --model qwen-plus --dry-run --output json
```
### `bl permission list`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| **Name** | `permission list` |
| **Description** | List model permissions (inference / fine-tune / deploy) in the workspace |
| **Authentication** | API Key |
| **Usage** | `bl permission list [--scope <scope>] [--model <model>] [--name <name>] [--page <n>] [--page-size <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------------ | ------ | -------- | --------------------------------------------------------------------- |
| `--scope <authorized\|authorizable>` | string | no | Authorization scope: authorizable (default, full catalog), authorized |
| `--model <model>` | string | no | Model ID (exact match) |
| `--name <name>` | string | no | Fuzzy search by model name or ID |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 20) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Default scope is `authorizable` (the full grantable catalog); use `--scope authorized` to see only models already granted.
- Output defaults to JSON; pass `--output text` for a table. Permission values are tri-state: true / false / null (never set).
- Values mirror the server's grant records as-is for the workspace bound to your API key. A model reporting false/null can still be callable (access may come from other channels); see the Model Studio authorization docs for the exact semantics.
#### Examples
```bash
bl permission list
```
```bash
bl permission list --model qwen-plus
```
```bash
bl permission list --scope authorized
```
```bash
bl permission list --name qwen --page-size 50
```
```bash
bl permission list --output text
```
### `bl permission revoke`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `permission revoke` |
| **Description** | Revoke model permissions (inference / finetune / deploy) |
| **Authentication** | API Key |
| **Usage** | `bl permission revoke --model <models> [--action <actions>] \| --all [flags]` |
| **Risk** | `high` |
| **Risk message** | This revokes model permissions and may interrupt inference, fine-tuning, or deployment workloads. With --all, it also clears all historical inference grants. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| -------------------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `--model <models>` | string | no | Model ID(s), comma-separated (max 20) |
| `--action <actions>` | string | no | Permission action(s), comma-separated: inference, finetune, deploy (default: inference) |
| `--all` | switch | no | Close one-key authorization and clear ALL historical inference grants |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Grants apply to the business workspace your API key belongs to.
- All revoke operations require --yes; use --dry-run to preview the request without confirmation.
- --all maps to the server one-key switch (access_all_entities: CLOSE): it clears every historical inference grant and cannot be undone, so it requires --yes.
- Actions you omit keep their current grants (server-side tri-state patch).
#### Examples
```bash
# Only after explicit user confirmation:
bl permission revoke --model qwen-plus --yes
```
```bash
# Only after explicit user confirmation:
bl permission revoke --model qwen-plus,qwen3-max --action inference,finetune --yes
```
```bash
# Only after explicit user confirmation:
bl permission revoke --all --yes
```
```bash
bl permission revoke --model qwen-plus --dry-run --output json
```
reference/pipeline.md
# `bl pipeline` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------------- | -------------- | ------------------------------------------------ |
| `bl pipeline run` | No Auth | Run a pipeline workflow definition |
| `bl pipeline validate` | No Auth | Validate a pipeline definition without executing |
## Command details
### `bl pipeline run`
| Field | Value |
| ------------------ | --------------------------------------- |
| **Name** | `pipeline run` |
| **Description** | Run a pipeline workflow definition |
| **Authentication** | No Auth |
| **Usage** | `bl pipeline run --file <path> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| -------------------------- | ------ | -------- | ------------------------------------ |
| `--file <path>` | string | yes | Pipeline definition file (YAML/JSON) |
| `--input <json>` | string | no | Runtime input as inline JSON |
| `--input-file <path>` | string | no | Runtime input from a JSON file |
| `--concurrency <n>` | number | no | Max parallel steps (default: 1) |
| `--events <jsonl>` | string | no | Emit lifecycle events: jsonl |
| `--step-timeout <seconds>` | number | no | Default step timeout in seconds |
#### Examples
```bash
bl pipeline run --file workflow.yaml --input '{"brief":"hello"}'
```
```bash
bl pipeline run --file workflow.json --input-file inputs.json --concurrency 3
```
```bash
bl pipeline run --file workflow.yaml --dry-run
```
```bash
bl pipeline run --file workflow.json --events jsonl
```
```bash
bl pipeline run --file workflow.yaml --output json
```
### `bl pipeline validate`
| Field | Value |
| ------------------ | ------------------------------------------------ |
| **Name** | `pipeline validate` |
| **Description** | Validate a pipeline definition without executing |
| **Authentication** | No Auth |
| **Usage** | `bl pipeline validate --file <path>` |
#### Flags
| Flag | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------ |
| `--file <path>` | string | yes | Pipeline definition file (YAML/JSON) |
#### Examples
```bash
bl pipeline validate --file workflow.yaml
```
```bash
bl pipeline validate --file workflow.json --output json
```
reference/plugin.md
# `bl plugin` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------- | -------------- | ------------------------------------------------------ |
| `bl plugin install` | No Auth | Install or upgrade an allowlisted Command Pack |
| `bl plugin link` | No Auth | Link an allowlisted local Command Pack for development |
| `bl plugin list` | No Auth | List installed Command Packs and their load status |
| `bl plugin remove` | No Auth | Remove an installed Command Pack |
## Command details
### `bl plugin install`
| Field | Value |
| ------------------ | ---------------------------------------------- |
| **Name** | `plugin install` |
| **Description** | Install or upgrade an allowlisted Command Pack |
| **Authentication** | No Auth |
| **Usage** | `bl plugin install --package <name[@version]>` |
#### Flags
| Flag | Type | Required | Description |
| ---------------------------- | ------ | -------- | ------------------------------------------------------------ |
| `--package <name[@version]>` | string | yes | Allowlisted Command Pack package and optional version or tag |
#### Examples
```bash
bl plugin install --package @ali/bailian-plugin-agent
```
```bash
bl plugin install --package @ali/bailian-plugin-agent@beta
```
### `bl plugin link`
| Field | Value |
| ------------------ | ------------------------------------------------------ |
| **Name** | `plugin link` |
| **Description** | Link an allowlisted local Command Pack for development |
| **Authentication** | No Auth |
| **Usage** | `bl plugin link --path <directory>` |
#### Flags
| Flag | Type | Required | Description |
| -------------------- | ------ | -------- | ------------------------------------ |
| `--path <directory>` | string | yes | Local Command Pack package directory |
#### Examples
```bash
bl plugin link --path ../bailian-plugin-agent
```
### `bl plugin list`
| Field | Value |
| ------------------ | -------------------------------------------------- |
| **Name** | `plugin list` |
| **Description** | List installed Command Packs and their load status |
| **Authentication** | No Auth |
| **Usage** | `bl plugin list` |
#### Flags
_No command-specific flags._
#### Examples
```bash
bl plugin list
```
```bash
bl plugin list --output json
```
### `bl plugin remove`
| Field | Value |
| ------------------ | ----------------------------------- |
| **Name** | `plugin remove` |
| **Description** | Remove an installed Command Pack |
| **Authentication** | No Auth |
| **Usage** | `bl plugin remove --name <package>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------- |
| `--name <package>` | string | yes | Allowlisted Command Pack package name |
#### Examples
```bash
bl plugin remove --name @ali/bailian-plugin-agent
```
reference/quota.md
# `bl quota` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------ | -------------- | ------------------------------------------------------------- |
| `bl quota check` | Console | Check current usage against rate limits |
| `bl quota delete` | API Key | Clear all custom rate limits (QPM/TPM) for a model |
| `bl quota history` | Console | View quota change history |
| `bl quota list` | API Key | View model rate limits (QPM/TPM, account and workspace level) |
| `bl quota update` | API Key | Update model rate limits (QPM/TPM) |
## Command details
### `bl quota check`
| Field | Value |
| ------------------ | ------------------------------------------ |
| **Name** | `quota check` |
| **Description** | Check current usage against rate limits |
| **Authentication** | Console |
| **Usage** | `bl quota check [--model <model>] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--model <model>` | string | no | Model name(s), comma-separated |
| `--period <minutes>` | string | no | Query usage for the last N minutes (default: 2) |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl quota check
```
```bash
bl quota check --model qwen3.6-plus
```
```bash
bl quota check --period 5
```
```bash
bl quota check --model qwen3.6-plus,qwen-turbo
```
```bash
bl quota check --output json
```
### `bl quota delete`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Name** | `quota delete` |
| **Description** | Clear all custom rate limits (QPM/TPM) for a model |
| **Authentication** | API Key |
| **Usage** | `bl quota delete --model <model>` |
| **Risk** | `high` |
| **Risk message** | This permanently clears all custom QPM/TPM rate limits for the specified model and cannot be undone. |
> **Agent safety:** Never add `--yes` automatically. On `type="requires_confirmation"`, stop and ask for explicit user confirmation of the same action and scope.
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------- |
| `--model <model>` | string | yes | Model name (required) |
| `--yes` | switch | no | Confirm this high-risk operation |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl quota delete --model qwen-plus
```
```bash
bl quota delete --model qwen-plus --dry-run --output json
```
```bash
# Only after explicit user confirmation:
bl quota delete --model qwen-plus --yes
```
### `bl quota history`
| Field | Value |
| ------------------ | -------------------------- |
| **Name** | `quota history` |
| **Description** | View quota change history |
| **Authentication** | Console |
| **Usage** | `bl quota history [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--page <n>` | string | no | Page number (default: 1) |
| `--page-size <n>` | string | no | Page size (default: 10) |
| `--model <model>` | string | no | Filter by model name |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl quota history
```
```bash
bl quota history --page 2
```
```bash
bl quota history --page-size 20
```
```bash
bl quota history --model qwen-turbo
```
```bash
bl quota history --output json
```
### `bl quota list`
| Field | Value |
| ------------------ | -------------------------------------------------------------------------------- |
| **Name** | `quota list` |
| **Description** | View model rate limits (QPM/TPM, account and workspace level) |
| **Authentication** | API Key |
| **Usage** | `bl quota list [--model <model>] [--name <name>] [--page <n>] [--page-size <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------------------- |
| `--model <model>` | string | no | Model name(s), comma-separated (exact match) |
| `--name <name>` | string | no | Fuzzy search by model name |
| `--page <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Results per page (default: 20) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Usage-vs-limit pressure checks live in `quota check` (console auth).
#### Examples
```bash
bl quota list
```
```bash
bl quota list --model qwen3-max
```
```bash
bl quota list --model qwen3-max,qwen-plus
```
```bash
bl quota list --name qwen --page-size 50
```
```bash
bl quota list --output json
```
### `bl quota update`
| Field | Value |
| ------------------ | --------------------------------------------------------- |
| **Name** | `quota update` |
| **Description** | Update model rate limits (QPM/TPM) |
| **Authentication** | API Key |
| **Usage** | `bl quota update --model <model> [--rpm <n>] [--tpm <n>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | ----------------------------- |
| `--model <model>` | string | yes | Model name (required) |
| `--rpm <n>` | number | no | Max requests per minute (QPM) |
| `--tpm <n>` | number | no | Max tokens per minute (TPM) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Notes
- Fields you omit keep their current values (server-side OVERLAY merge). Clear all custom limits with the "quota delete" command instead.
- Setting TPM without an existing QPM limit is rejected server-side — pass --rpm first or together.
#### Examples
```bash
bl quota update --model qwen-plus --rpm 60 --tpm 100000
```
```bash
bl quota update --model qwen3-max --tpm 500000
```
```bash
bl quota update --model qwen-plus --rpm 60 --output json
```
reference/search.md
# `bl search` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
> **Agent routing (mandatory):** Before running any `bl search *` command, Read skill `bailian-web-search` if installed and follow its identity-based routing (Token Plan → model-native web search; default → MCP; eligible MCP failures → fall back once). Do **not** call `bl search web` directly from this reference alone — Token Plan keys cannot authorize Bailian MCP search. If that skill is missing, run `bl skill init` or fall back to `bl search web --help` / `bl text chat --help` after checking `bl config show --output json`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| --------------- | -------------- | ---------------------------------------------------- |
| `bl search web` | API Key | Search the web using DashScope MCP WebSearch service |
## Command details
### `bl search web`
| Field | Value |
| ------------------ | ---------------------------------------------------- |
| **Name** | `search web` |
| **Description** | Search the web using DashScope MCP WebSearch service |
| **Authentication** | API Key |
| **Usage** | `bl search web --query <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------ | ------ | -------- | -------------------------------------- |
| `--query <text>` | string | no | Search query text |
| `--count <n>` | number | no | Number of search results (default: 10) |
| `--list-tools` | switch | no | List available MCP tools and exit |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl search web --query "Alibaba Cloud Bailian latest features"
```
```bash
bl search web --query "TypeScript 5.9 new features" --count 5
```
```bash
bl search web --query "Today's news"
```
```bash
bl search web --list-tools
```
reference/skill.md
# `bl skill` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ----------------- | -------------- | ----------------------------------------------------------------------- |
| `bl skill add` | No Auth | Install skills from the Bailian skill registry into local agents |
| `bl skill init` | No Auth | Install all bailian-\* skills (one-shot bootstrap for new environments) |
| `bl skill list` | No Auth | List registry skills and diff against local installs |
| `bl skill remove` | No Auth | Remove locally installed skills (registry is untouched) |
| `bl skill update` | No Auth | Update installed skills to the latest registry versions |
## Command details
### `bl skill add`
| Field | Value |
| ------------------ | ---------------------------------------------------------------- |
| **Name** | `skill add` |
| **Description** | Install skills from the Bailian skill registry into local agents |
| **Authentication** | No Auth |
| **Usage** | `bl skill add --all \| --name <name,...>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | -------------------------------------- |
| `--all` | switch | no | Install all skills from the registry |
| `--name <name,...>` | string | no | Comma-separated skill names to install |
#### Examples
```bash
bl skill add --all
```
```bash
bl skill add --name spark-video,bailian-model-recommend
```
### `bl skill init`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------- |
| **Name** | `skill init` |
| **Description** | Install all bailian-\* skills (one-shot bootstrap for new environments) |
| **Authentication** | No Auth |
| **Usage** | `bl skill init` |
#### Flags
_No command-specific flags._
#### Notes
- Fetches the registry index and installs every skill whose name starts with `bailian-`.
- Equivalent to: `bl skill add --all` (filtered to `bailian-*` skills).
#### Examples
```bash
bl skill init
```
### `bl skill list`
| Field | Value |
| ------------------ | ---------------------------------------------------- |
| **Name** | `skill list` |
| **Description** | List registry skills and diff against local installs |
| **Authentication** | No Auth |
| **Usage** | `bl skill list` |
#### Flags
_No command-specific flags._
#### Notes
- STATUS: installed | outdated | not-installed | missing (lock has it, dir deleted) | untracked (dir exists, not managed)
#### Examples
```bash
bl skill list
```
```bash
bl skill list --output json
```
### `bl skill remove`
| Field | Value |
| ------------------ | ------------------------------------------------------- |
| **Name** | `skill remove` |
| **Description** | Remove locally installed skills (registry is untouched) |
| **Authentication** | No Auth |
| **Usage** | `bl skill remove --name <all\|name,...>` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | ---------------------------------------------------- |
| `--name <all\|name,...>` | string | yes | Skills to remove: all or comma-separated skill names |
#### Examples
```bash
bl skill remove --name spark-video
```
```bash
bl skill remove --name all
```
### `bl skill update`
| Field | Value |
| ------------------ | ------------------------------------------------------- |
| **Name** | `skill update` |
| **Description** | Update installed skills to the latest registry versions |
| **Authentication** | No Auth |
| **Usage** | `bl skill update [--all] [--name <name,...>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `--all` | switch | no | Update all installed skills (default when neither --all nor --name is given) |
| `--name <name,...>` | string | no | Comma-separated skill names to update (must be already installed) |
#### Examples
```bash
bl skill update
```
```bash
bl skill update --all
```
```bash
bl skill update --name spark-video
```
reference/text.md
# `bl text` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| -------------- | -------------- | -------------------------------------------------------- |
| `bl text chat` | API Key | Send a text model request (OpenAI compatible, DashScope) |
## Command details
### `bl text chat`
| Field | Value |
| ------------------ | -------------------------------------------------------- |
| **Name** | `text chat` |
| **Description** | Send a text model request (OpenAI compatible, DashScope) |
| **Authentication** | API Key |
| **Usage** | `bl text chat --message <text> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `--api <chat\|responses>` | string | no | API to call (default: chat) |
| `--model <model>` | string | no | Model ID (default: qwen3.8-max) |
| `--message <text>` | array | no | Message text (repeatable, prefix role: to set role); or use --messages-file |
| `--messages-file <path>` | string | no | JSON file with messages array (use - for stdin) |
| `--system <text>` | string | no | System prompt |
| `--max-tokens <n>` | number | no | Maximum tokens to generate (default: 4096) |
| `--temperature <n>` | number | no | Sampling temperature (0.0, 2.0] |
| `--top-p <n>` | number | no | Nucleus sampling threshold |
| `--stream` | switch | no | Stream response tokens (default: on in TTY) |
| `--tool <json-or-path>` | array | no | Tool definition as JSON or file path (repeatable) |
| `--enable-thinking` | switch | no | Enable thinking/reasoning mode (for qwen3/qwq models) |
| `--thinking-budget <n>` | number | no | Max tokens for thinking (default: 4096) |
| `--api-key <key>` | string | no | API key |
| `--base-url <url>` | string | no | API base URL |
#### Examples
```bash
bl text chat --message "What is Qwen?"
```
```bash
bl text chat --api responses --model qwen3.8-max --tool '{"type":"web_search"}' --message "Search for recent Alibaba Cloud news"
```
```bash
bl text chat --model qwen-max --system "You are a coding assistant." --message "Write fizzbuzz in Python"
```
```bash
bl text chat --message "Hello" --message "assistant:Hi!" --message "How are you?"
```
```bash
bl text chat --messages-file - --stream
```
```bash
bl text chat --message "Hello" --output json
```
```bash
bl text chat --model qwq-plus --message "Solve 1+1" --enable-thinking
```
reference/token-plan.md
# `bl token-plan` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------------------- | -------------- | ----------------------------------------- |
| `bl token-plan add-member` | AK/SK | Add a member to a Token Plan organization |
| `bl token-plan assign-seats` | AK/SK | Batch assign Token Plan seats to members |
| `bl token-plan create-key` | AK/SK | Create a Token Plan API key for a seat |
| `bl token-plan list-seats` | AK/SK | List Token Plan subscription seat details |
## Command details
### `bl token-plan add-member`
| Field | Value |
| ------------------ | ---------------------------------------------------------------------- |
| **Name** | `token-plan add-member` |
| **Description** | Add a member to a Token Plan organization |
| **Authentication** | AK/SK |
| **Usage** | `bl token-plan add-member --account-name <name> --org-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `--account-name <name>` | string | yes | Member display name |
| `--org-id <id>` | string | yes | Organization ID |
| `--org-role-code <code>` | string | no | Organization role: ORG_ADMIN or ORG_MEMBER (default: ORG_MEMBER) |
| `--spec-type <type>` | string | no | Seat tier to assign on creation: standard, pro, or max |
| `--caller-uac-account-id <id>` | string | no | Caller UAC account ID |
| `--namespace-id <id>` | string | no | Product namespace ID (Token Plan default: namespace-1) |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
#### Examples
```bash
bl token-plan add-member --account-name dev_user --org-id org_123
```
```bash
bl token-plan add-member --account-name admin_user --org-id org_123 --org-role-code ORG_ADMIN
```
```bash
bl token-plan add-member --account-name member1 --org-id org_123 --spec-type standard
```
### `bl token-plan assign-seats`
| Field | Value |
| ------------------ | --------------------------------------------------------------------------------------------- |
| **Name** | `token-plan assign-seats` |
| **Description** | Batch assign Token Plan seats to members |
| **Authentication** | AK/SK |
| **Usage** | `bl token-plan assign-seats --workspace-id <id> --seat-type <type> --account-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID, config: workspace_id) |
| `--seat-type <type>` | string | yes | Seat tier: standard, pro, or max |
| `--account-id <id>` | array | no | Target member account ID (repeatable) |
| `--caller-uac-account-id <id>` | string | no | Caller UAC account ID |
| `--namespace-id <id>` | string | no | Product namespace ID (Token Plan default: namespace-1) |
| `--locale <locale>` | string | no | Language: zh-CN or en-US |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
#### Examples
```bash
bl token-plan assign-seats --workspace-id ws_456 --seat-type standard --account-id acc_123
```
```bash
bl token-plan assign-seats --workspace-id ws_456 --seat-type pro --account-id acc_1 --account-id acc_2
```
### `bl token-plan create-key`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------ |
| **Name** | `token-plan create-key` |
| **Description** | Create a Token Plan API key for a seat |
| **Authentication** | AK/SK |
| **Usage** | `bl token-plan create-key --account-id <id> --workspace-id <id> [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ---------------------------------------------------------------------- |
| `--account-id <id>` | string | yes | Target member account ID |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID, config: workspace_id) |
| `--description <text>` | string | no | API key description |
| `--caller-uac-account-id <id>` | string | no | Caller UAC account ID |
| `--namespace-id <id>` | string | no | Product namespace ID (Token Plan default: namespace-1) |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
#### Examples
```bash
bl token-plan create-key --account-id acc_123 --workspace-id ws_456
```
```bash
bl token-plan create-key --account-id acc_123 --workspace-id ws_456 --description 'Dev key'
```
### `bl token-plan list-seats`
| Field | Value |
| ------------------ | ----------------------------------------- |
| **Name** | `token-plan list-seats` |
| **Description** | List Token Plan subscription seat details |
| **Authentication** | AK/SK |
| **Usage** | `bl token-plan list-seats [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | --------------------------------------------------------------------------------- |
| `--page-no <n>` | number | no | Page number (default: 1) |
| `--page-size <n>` | number | no | Page size (default: 10) |
| `--caller-uac-account-id <id>` | string | no | Caller UAC account ID |
| `--namespace-id <id>` | string | no | Product namespace ID (Token Plan default: namespace-1) |
| `--status <status>` | array | no | Seat status filter (repeatable): CREATING, NORMAL, LIMIT, RELEASE, STOP, REFUNDED |
| `--status-list-str <json>` | string | no | StatusList as JSON string, e.g. '["NORMAL"]' |
| `--seat-id <id>` | string | no | Filter by seat ID |
| `--seat-type <type>` | string | no | Seat tier: standard, pro, or max |
| `--query-assigned <bool>` | string | no | Filter by assignment: true=assigned, false=unassigned |
| `--access-key-id <key>` | string | no | Alibaba Cloud Access Key ID (env: ALIBABA_CLOUD_ACCESS_KEY_ID) |
| `--access-key-secret <key>` | string | no | Alibaba Cloud Access Key Secret (env: ALIBABA_CLOUD_ACCESS_KEY_SECRET) |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (env: ALIBABA_CLOUD_SECURITY_TOKEN) |
#### Examples
```bash
bl token-plan list-seats
```
```bash
bl token-plan list-seats --page-size 20 --status NORMAL
```
```bash
bl token-plan list-seats --query-assigned true --seat-type standard
```
reference/update.md
# `bl update` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ----------- | -------------- | --------------------------------------------------- |
| `bl update` | No Auth | Update the CLI to the latest or a specified version |
## Command details
### `bl update`
| Field | Value |
| ------------------ | --------------------------------------------------- |
| **Name** | `update` |
| **Description** | Update the CLI to the latest or a specified version |
| **Authentication** | No Auth |
| **Usage** | `bl update [--to <version>]` |
#### Flags
| Flag | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------ |
| `--to <version>` | string | no | Install this exact version instead of the latest |
#### Examples
```bash
bl update
```
```bash
bl update --to 0.1.14
```
reference/usage.md
# `bl usage` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `bl usage coding-plan` | Console | Show Coding Plan quota usage |
| `bl usage free` | Console | Query free-tier quota for models (all models if --model is omitted) |
| `bl usage freetier` | Console | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable |
| `bl usage stats` | Console | Query model usage statistics |
| `bl usage summary` | Console | Show a unified usage summary: free-tier quota and recent usage overview |
| `bl usage token-plan` | Console | Show Token Plan quota usage |
## Command details
### `bl usage coding-plan`
| Field | Value |
| ------------------ | ------------------------------ |
| **Name** | `usage coding-plan` |
| **Description** | Show Coding Plan quota usage |
| **Authentication** | Console |
| **Usage** | `bl usage coding-plan [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage coding-plan
```
```bash
bl usage coding-plan --output json
```
### `bl usage free`
| Field | Value |
| ------------------ | ------------------------------------------------------------------- |
| **Name** | `usage free` |
| **Description** | Query free-tier quota for models (all models if --model is omitted) |
| **Authentication** | Console |
| **Usage** | `bl usage free [--model <model>[,model2,...]] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------------------------------------- |
| `--model <model>` | string | no | Model name(s) to query, comma-separated for multiple; omit for all models |
| `--expiring <days>` | string | no | Only show quotas expiring within N days |
| `--sort <remaining\|expires>` | string | no | Sort by: remaining (ascending), expires (ascending) |
| `--all` | switch | no | Show all models instead of the top rows |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage free
```
```bash
bl usage free --model qwen3-max
```
```bash
bl usage free --model qwen3-max,qwen-turbo
```
```bash
bl usage free --expiring 30
```
```bash
bl usage free --sort remaining
```
```bash
bl usage free --all
```
```bash
bl usage free --model qwen-turbo --output json
```
```bash
bl usage free --model qwen3-max --console-region cn-beijing
```
### `bl usage freetier`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------ |
| **Name** | `usage freetier` |
| **Description** | Enable or disable auto-stop for free-tier models. Enables by default; use --off to disable |
| **Authentication** | Console |
| **Usage** | `bl usage freetier <--model <model>[,model2,...] \| --all> [--off] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--model <model>` | string | no | Model name(s), comma-separated for multiple |
| `--all` | switch | no | Apply to all free-tier models |
| `--on` | switch | no | Enable auto-stop (default behavior) |
| `--off` | switch | no | Disable auto-stop |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage freetier --model qwen3-max
```
```bash
bl usage freetier --model qwen3-max,qwen-turbo
```
```bash
bl usage freetier --all
```
```bash
bl usage freetier --on --model qwen3-max
```
```bash
bl usage freetier --off --model qwen3-max
```
```bash
bl usage freetier --off --all
```
### `bl usage stats`
| Field | Value |
| ------------------ | ---------------------------------------------------------- |
| **Name** | `usage stats` |
| **Description** | Query model usage statistics |
| **Authentication** | Console |
| **Usage** | `bl usage stats [--model <model>] [--days <days>] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--model <model>` | string | no | Model name(s), comma-separated; omit for overview |
| `--days <days>` | string | no | Number of days (default: 7) |
| `--type <type>` | string | no | Model type: Text, Vision, Multimodal, Audio, Embedding |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage stats
```
```bash
bl usage stats --days 30
```
```bash
bl usage stats --model qwen-turbo
```
```bash
bl usage stats --model qwen-turbo --days 7
```
```bash
bl usage stats --model qwen3.6-plus,deepseek-v4-pro
```
```bash
bl usage stats --type Text --days 14
```
```bash
bl usage stats --output json
```
### `bl usage summary`
| Field | Value |
| ------------------ | ----------------------------------------------------------------------- |
| **Name** | `usage summary` |
| **Description** | Show a unified usage summary: free-tier quota and recent usage overview |
| **Authentication** | Console |
| **Usage** | `bl usage summary [--days <days>] [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--days <days>` | string | no | Number of days for the usage overview (default: 7) |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage summary
```
```bash
bl usage summary --days 30
```
```bash
bl usage summary --output json
```
### `bl usage token-plan`
| Field | Value |
| ------------------ | ----------------------------- |
| **Name** | `usage token-plan` |
| **Description** | Show Token Plan quota usage |
| **Authentication** | Console |
| **Usage** | `bl usage token-plan [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl usage token-plan
```
```bash
bl usage token-plan --output json
```
reference/workspace.md
# `bl workspace` commands
> Auto-generated from `packages/cli/src/commands.ts`. Do not edit by hand.
> Regenerate: `pnpm --filter bailian-cli run generate:reference`.
Index: [index.md](index.md)
## Commands in this group
| Command | Authentication | Description |
| ------------------- | -------------- | ----------------------------------------------------------- |
| `bl workspace init` | No Auth | Initialize Bailian workspace and activate postpaid services |
| `bl workspace list` | Console | List all workspaces |
## Command details
### `bl workspace init`
| Field | Value |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Name** | `workspace init` |
| **Description** | Initialize Bailian workspace and activate postpaid services |
| **Authentication** | No Auth |
| **Usage** | `bl workspace init --access-key-id <id> --access-key-secret <secret> [--security-token <token>]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | ------------------------------------------- |
| `--access-key-id <id>` | string | no | Alibaba Cloud Access Key ID |
| `--access-key-secret <secret>` | string | no | Alibaba Cloud Access Key Secret |
| `--security-token <token>` | string | no | Alibaba Cloud STS Security Token (optional) |
#### Examples
```bash
bl workspace init --access-key-id LTAIxxxxx --access-key-secret xxxxx
```
### `bl workspace list`
| Field | Value |
| ------------------ | --------------------------- |
| **Name** | `workspace list` |
| **Description** | List all workspaces |
| **Authentication** | Console |
| **Usage** | `bl workspace list [flags]` |
#### Flags
| Flag | Type | Required | Description |
| ------------------------------ | ------ | -------- | -------------------------------------------------------- |
| `--list <n>` | string | no | Limit number of results |
| `--console-region <region>` | string | no | Console gateway region (e.g. cn-beijing, ap-southeast-1) |
| `--console-site <site>` | string | no | Console site: domestic, international |
| `--console-switch-agent <uid>` | number | no | Switch agent UID for delegated access |
| `--workspace-id <id>` | string | no | Workspace ID (env: BAILIAN_WORKSPACE_ID) |
#### Examples
```bash
bl workspace list
```
```bash
bl workspace list --list 5
```
```bash
bl workspace list --output json
```
SKILL.md
---
name: bailian-cli
metadata:
version: "1.21.0"
requires:
bins: ["bl"]
description: >-
阿里云百炼 / Aliyun Bailian / DashScope 资源管理与 `bl` CLI hub：
应用调用（bl app）、应用记忆、知识库检索、模型目录/模型列表、用量/额度/配额、免费额度、
工作空间、MCP 市场、pipeline、文件上传、console API、登录鉴权与配置、
Agent skill 安装/列表/更新/卸载（bl skill add|list|update|remove，百炼 skill registry）。
用户点名百炼 / DashScope / `bl`，或继续既有 `bl` 工作流时直接使用。
共享协议（consent / 版本预检 / 鉴权 / 错误上报）在 bailian-protocol；官方安装 `bl skill init`。
家族路由：生图/生视频/配音/语音合成/转写 → bailian-gen；精调/微调/训练/数据集 → bailian-finetune；
agents.yaml 托管 Agent → bailian-managed-agent；联网搜索的模型路由（Token Plan 自带搜索 vs MCP 搜索 + 兜底）→ bailian-web-search。
不要用于普通问答、编程、写作、翻译、摘要、泛搜索，或图片理解等宿主自己能做的任务（普通问答、编程、写作、翻译、摘要、泛搜索不触发）。
未命名用量/额度问题：先问用户使用哪个产品，再运行 `bl usage` / `bl quota` 查询。
---
# Aliyun Model Studio CLI (`bl`)
**CRITICAL — Before executing, MUST read the shared protocol in [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md): Provider selection and consent, Version & updates (pre-flight checklist), Setup & auth, and CLI errors: report an issue. If that protocol file is missing, stop and run `bl skill init`; do not guess auth/consent.**
> **Family hub** — This skill owns Bailian resource commands and the hub `reference/` (apps, knowledge, usage, auth, config, …).
> Shared protocol → [`../bailian-protocol/SKILL.md`](../bailian-protocol/SKILL.md) (install the full family with `bl skill init`).
> Soft hand-offs by skill name (Read if installed; else `bl … --help` / prompt `bl skill init`): `bailian-gen` (media) · `bailian-finetune` (training) · `bailian-managed-agent` (agents.yaml IaC) · `bailian-web-search` (web search routing).
> Do not invoke it for ordinary reasoning, coding, writing, translation, summarization, generic research, or image understanding the host agent can complete directly.
>
> **Install (supported):** `bl skill init`
## Command reference (authoritative)
**Hub-owned commands, flags, usage strings, and examples are documented in:**
- [`reference/index.md`](reference/index.md) — hub quick index, global flags, links by group
- [`reference/<group>.md`](reference/) — per hub top-level command (e.g. [`reference/app.md`](reference/app.md))
Domain skills own their own generated reference trees (soft hand-off — do not require them for hub work):
- `bailian-gen` → `image` / `video` / `speech` / `omni` / `vision` (fallback: `bl image\|video\|speech\|omni\|vision --help`)
- `bailian-finetune` → `dataset` / `finetune` / `deploy` (fallback: `bl dataset\|finetune\|deploy --help`)
- `bailian-managed-agent` → `managed-agent` (fallback: `bl managed-agent --help`)
- `bailian-web-search` → web search **routing** (hub still owns `reference/search.md` flags; **must** route via this skill before `bl search web`)
Auto-generated from the CLI source at build time (`pnpm --filter bailian-cli run generate:reference`). Before running an unfamiliar command:
1. Open the owning skill's `reference/index.md` (if that skill is installed) → **Quick index** (or **By group**) to locate the command.
2. Open the matching `reference/<group>.md` for **Usage**, **Flags**, and **Examples**.
3. Run `bl <command> --help` for the same information in the terminal.
Do not guess flags — use the reference files or `--help`.
---
## When to use which command
Use this table only after the decision table in [`bailian-protocol`](../bailian-protocol/SKILL.md#provider-selection-and-consent) has routed the request to `bl` (class 4, or class 2 after the user picks Bailian). Hub-owned intents only — for media / fine-tune / agents.yaml, soft hand-off to the domain skill.
| User intent | Command | Notes |
| ------------------------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------- |
| Explicit Bailian model chat / text execution | `bl text chat` | Default `qwen3.8-max` |
| Bailian agent / workflow | `bl app call` | Needs `--app-id` |
| Find app by name | `bl app list` then `bl app call` | Console auth |
| Bailian app memory CRUD (not host-agent memory) | `bl memory *` | [`reference/memory.md`](reference/memory.md) |
| Bailian knowledge base RAG | `bl knowledge search` / `chat` | API key + agent/workspace IDs |
| Upload a file as a step of a Bailian workflow | `bl file upload` | When you need `oss://` URL explicitly; not for generic hosting |
| Bailian model selection / recommendation | `bl advisor recommend` | Intent → candidate recall → LLM ranking |
| Bailian model catalog / pricing / params | `bl model list` | Console auth; `--model <family>` for detail, `--enrich` for input params |
| Install / list / update / remove registry skills | `bl skill add` / `list` / `update` / `remove` | Bailian skill registry; see [`reference/skill.md`](reference/skill.md) |
| Bailian MCP marketplace discovery / call | `bl mcp list` / `tools` / `call` | — |
| Bailian pipeline workflow (a step in a bl flow) | `bl pipeline run` / `validate` | JSON/YAML workflow definitions |
| Bailian rate limits / quota | `bl quota list` / `check` / `request` | Console auth; class 2 — ask which product first if unnamed |
| Bailian free tier / usage stats | `bl usage free` / `stats` / `freetier` | Console auth; class 2 — ask which product first if unnamed |
| Bailian Token Plan quota usage | `bl usage token-plan` | Console auth; class 2 — ask which product first if unnamed |
| Bailian Coding Plan quota usage | `bl usage coding-plan` | Console auth; class 2 — ask which product first if unnamed |
| Console API (advanced) | `bl console call` | Console auth |
| Bailian workspace listing | `bl workspace list` | Console auth |
| Switch CLI Help / Quick Start language | `bl config set --key language --value zh-CN` | Use `en-US` to switch back; follows the active config profile |
| Image / video / speech / omni / vision | → skill `bailian-gen` | Fallback: `bl image\|video\|speech\|omni\|vision --help` |
| Dataset / fine-tune / deploy | → skill `bailian-finetune` | Fallback: `bl dataset\|finetune\|deploy --help` |
| agents.yaml IaC / managed-agent sessions | → skill `bailian-managed-agent` | Fallback: `bl managed-agent --help`; `apply`/`destroy` also require `plan` |
| Web search (model-aware routing) | → skill `bailian-web-search` | Token Plan vs MCP path + fallback; fallback: `bl search web --help` |
Flags, usage, and examples: see hub [`reference/`](reference/index.md) or `bl <command> --help` — do not guess flags. Domain command details live in the owning skill's `reference/`.
---
## Quick examples
```bash
bl text chat --message "Write a poem about spring in Chinese"
bl app list --output json
bl app call --app-id <code> --prompt "Hello"
bl usage stats
bl model list --model qwen
```
More examples per command: see `reference/<group>.md` (e.g. [`reference/text.md`](reference/text.md), [`reference/app.md`](reference/app.md)).
---
## Agent workflows
### Find and call an app
1. `bl app list --name <keyword> --output json`
2. Pick `code` (app ID); handle `user_prompt_params` via `--biz-params '{"key":"value"}'`
3. `bl app call --app-id <code> --prompt "..."`
### Command metadata for agents
Use the owning skill's [`reference/index.md`](reference/index.md) (or sibling skill reference trees), the matching `reference/<group>.md`,
and `bl <command> --help` as the command schema surface. Do not call removed
schema-export commands.
---
## Routing reminders
- Image/video/audio generation or editing → skill `bailian-gen` (class 3 consent from `bailian-protocol`). Fine-tuning / datasets / deployments → `bailian-finetune`. agents.yaml IaC → `bailian-managed-agent`. Soft hand-off: Read sibling skill if installed; else `bl … --help` or prompt `bl skill init`. Image understanding the host agent can do → host-first; use `bl vision` / `bl omni` only when the user names a Bailian model or the media (video/audio files) exceeds host capability.
- Web search inside a Bailian workflow → skill `bailian-web-search` (model-aware routing: Token Plan → model-native search; default → `bl search web`; MCP failure → fall back once). Generic web research the host can do stays host-first — do not bounce it through `bl`.
- Answer ordinary reasoning, coding, writing, translation, summarization, and generic research with the host agent's native capabilities; do not bounce them through `bl text chat` or `bl search web`.
- Usage / quota / credits questions that do not name a product → ask which product (Bailian or another AI service) first; run `bl usage` / `bl quota` only after the user picks Bailian or Bailian context is already established.
- "Remember this" and memory requests default to the host agent's own memory; `bl memory *` is only for Bailian app memory resources.
- `bl file upload` and `bl pipeline run` are steps inside a Bailian workflow; do not use them to capture generic "upload this file" or "run a pipeline" requests.
- For `risk: high` commands or `requires_confirmation`, follow the shared protocol; never add `--yes` automatically.
- `bl managed-agent apply` / `destroy` have an additional domain rule: run `plan` first and show the diff before asking for confirmation.
- When a matched `bl` command accepts a file URL, pass local paths directly; never require the user to host the file first.
- Console login → always `--console-site domestic|international`; see [`../bailian-protocol/assets/setup.md`](../bailian-protocol/assets/setup.md#console-site-selection).