diff --git a/docs/agents/telemetry-change.md b/docs/agents/telemetry-change.md index e916c794..9a923a36 100644 --- a/docs/agents/telemetry-change.md +++ b/docs/agents/telemetry-change.md @@ -125,7 +125,7 @@ source-config 只用于百炼 / DashScope API 侧消费,不发送到通用网 底层 Node tracker 还会附加公共设备字段:OS 类型/版本、Node 应用名与版本、平台,以及内置的 `device_id`(本机网卡 MAC 的 MD5,保持不变)。稳定匿名 install id 写入 AEM 的 `uid`:来自 `~/.bailian/telemetry-uid`,首次远端上报时生成随机 UUID v4,以 0600 权限原子发布;生成失败时不上报 `uid`。遥测关闭时不生成该文件。本地 `telemetry.jsonl` 每行附带同名 `uid`。注意:这不是账号用户 ID,只是上报到 AEM `uid` 字段的匿名标识;与 Tracker 内置 `device_id` 无关。 -`ensureUid` 无锁(对齐 qwen-code `InstallationManager`):稳态只读;缺失或损坏时同目录 temp 写满后 `rename` 发布(内容原子替换;并发首次创建时后写覆盖先写,磁盘最终为一个 UUID)。失败则省略 `uid`,不阻塞业务退出。 +`ensureUid` 无锁:稳态只读;缺失或损坏时同目录 temp 写满后 `rename` 发布(内容原子替换;并发首次创建时后写覆盖先写,磁盘最终为一个 UUID)。失败则省略 `uid`,不阻塞业务退出。 从 2.8.2 起,每条命令事件通过 `commandPrefix` 显式记录调用入口,三种入口仍共用 `pid=bailian-cli-node`: diff --git a/packages/cli/tests/e2e/registry.smoke.e2e.test.ts b/packages/cli/tests/e2e/registry.smoke.e2e.test.ts index aa297ac0..1cd4cbaf 100644 --- a/packages/cli/tests/e2e/registry.smoke.e2e.test.ts +++ b/packages/cli/tests/e2e/registry.smoke.e2e.test.ts @@ -98,7 +98,7 @@ describe("e2e: bl registry smoke", () => { expect(stderr).toMatch(/--console-region /); expect(stderr).toMatch(/--model /); expect(stderr).toMatch(/--period /); - expect(stderr).toMatch(/--output /); + expect(stderr).toMatch(/--output /); expect(stderr).not.toMatch(/API region \(default: cn-beijing\)/); }); diff --git a/packages/commands/src/commands/auth/login-api-key.ts b/packages/commands/src/commands/auth/login-api-key.ts index 0ec0582d..81f9b2e4 100644 --- a/packages/commands/src/commands/auth/login-api-key.ts +++ b/packages/commands/src/commands/auth/login-api-key.ts @@ -51,7 +51,6 @@ export interface ApiKeyValidationResult { kind: ApiKeyEndpointKind; } -const API_KEY_VALIDATION_TIMEOUT_SECONDS = 5; const ORDINARY_WORKSPACE_REGIONS = [ "cn-beijing", "ap-southeast-1", @@ -197,7 +196,7 @@ export async function validateApiKey( await requestJson(deps, { url: candidate.modelsUrl, headers: { Authorization: `Bearer ${key}` }, - timeout: Math.min(deps.settings.timeout, API_KEY_VALIDATION_TIMEOUT_SECONDS), + timeout: deps.settings.timeout, }); return { candidate }; } catch (error) { diff --git a/packages/commands/src/commands/usage/free.ts b/packages/commands/src/commands/usage/free.ts index 31796b52..7320b68b 100644 --- a/packages/commands/src/commands/usage/free.ts +++ b/packages/commands/src/commands/usage/free.ts @@ -96,7 +96,11 @@ export default defineCommand({ }; if (settings.dryRun) { - ctx.output.result({ api: FREE_TIER_API, data: requestData }); + ctx.output.result({ + api: FREE_TIER_API, + data: requestData, + ...(!modelFlag ? { scope: "all", models_resolved: false } : {}), + }); return; } diff --git a/packages/commands/src/commands/usage/freetier.ts b/packages/commands/src/commands/usage/freetier.ts index 82ff3c13..0228149b 100644 --- a/packages/commands/src/commands/usage/freetier.ts +++ b/packages/commands/src/commands/usage/freetier.ts @@ -120,9 +120,11 @@ export default defineCommand({ : "BatchActivateFreeTierOnlyRequest"; if (settings.dryRun) { + const unresolvedAll = Boolean(flags.all) && !modelFlag; ctx.output.result({ api, data: { [requestKey]: { models } }, + ...(unresolvedAll ? { scope: "all", models_resolved: false } : {}), }); return; } diff --git a/packages/commands/tests/auth-api-key.test.ts b/packages/commands/tests/auth-api-key.test.ts index fd855185..0e0ead09 100644 --- a/packages/commands/tests/auth-api-key.test.ts +++ b/packages/commands/tests/auth-api-key.test.ts @@ -1,6 +1,6 @@ import { httpTransport } from "bailian-cli-core"; import { BailianError, ExitCode, type Identity, type Settings } from "bailian-cli-core"; -import { expect, test } from "vite-plus/test"; +import { expect, test, vi } from "vite-plus/test"; import { apiKeyValidationCandidates, validateApiKey, @@ -334,3 +334,45 @@ test("同一优先级的 HTTP 错误保持候选顺序", async () => { httpTransport.fetch = originalFetch; } }); + +test("API Key 校验超时跟随 settings.timeout,不再被 5 秒硬顶截断", async () => { + const originalFetch = httpTransport.fetch; + httpTransport.fetch = async (_input, init) => { + const signal = init?.signal; + return await new Promise((_resolve, reject) => { + if (signal?.aborted) { + reject(signal.reason ?? new Error("aborted")); + return; + } + signal?.addEventListener( + "abort", + () => { + reject(signal.reason ?? new Error("aborted")); + }, + { once: true }, + ); + }); + }; + + vi.useFakeTimers({ toFake: ["setTimeout"] }); + try { + const pending = validateApiKey( + { identity, settings: { ...settings, timeout: 60 } }, + "sk-placeholder", + { explicitBaseUrl: "https://ws-explicit.ap-southeast-1.maas.aliyuncs.com" }, + ).then( + () => "resolved" as const, + () => "rejected" as const, + ); + + // 旧硬顶是 5 秒:若仍封顶,这里应已结束;跟随 settings.timeout=60 时仍应挂起 + await vi.advanceTimersByTimeAsync(5_000); + expect(await Promise.race([pending, Promise.resolve("pending")])).toBe("pending"); + + await vi.advanceTimersByTimeAsync(55_000); + expect(await pending).toBe("rejected"); + } finally { + vi.useRealTimers(); + httpTransport.fetch = originalFetch; + } +}); diff --git a/packages/commands/tests/e2e/command-help.test.ts b/packages/commands/tests/e2e/command-help.test.ts index e15de97f..cf8c9aff 100644 --- a/packages/commands/tests/e2e/command-help.test.ts +++ b/packages/commands/tests/e2e/command-help.test.ts @@ -8,7 +8,7 @@ test("captureCommandHelp 用 topic 最小路由渲染真实命令帮助", async expect(helpOutput).toContain("Usage: bl quota list"); expect(helpOutput).toContain("--model "); expect(helpOutput).toContain("--name "); - expect(helpOutput).toContain("--output "); + expect(helpOutput).toContain("--output "); }); test("runCommandHelp 保持 commands E2E 的 stderr 与 exitCode 断言接口", async () => { diff --git a/packages/commands/tests/e2e/usage-free.e2e.test.ts b/packages/commands/tests/e2e/usage-free.e2e.test.ts index 46f14658..efcd0da2 100644 --- a/packages/commands/tests/e2e/usage-free.e2e.test.ts +++ b/packages/commands/tests/e2e/usage-free.e2e.test.ts @@ -4,6 +4,7 @@ import { isConsoleAuthFailure, parseStdoutJson, runCommandHelp, + runCommandInProcess, runConsoleCommandE2e, } from "./helpers.ts"; import { USAGE_ROUTES } from "./topic-routes.ts"; @@ -22,6 +23,27 @@ describe("e2e: usage free", () => { expect(stderr).toContain("bl usage free --model qwen3-max"); expect(stderr).toContain("bl usage free --model qwen3-max,qwen-turbo"); }); + + test("usage free --dry-run 无 --model 标注全量范围未解析", async () => { + const { stdout, stderr, exitCode } = await runCommandInProcess(USAGE_ROUTES, [ + "usage", + "free", + "--dry-run", + "--output", + "json", + ]); + expect(exitCode, stderr).toBe(0); + const data = parseStdoutJson<{ + api: string; + scope: string; + models_resolved: boolean; + data: { queryFreeTierQuotaRequest: { models: string[] } }; + }>(stdout); + expect(data.api).toContain("queryFreeTierQuota"); + expect(data.scope).toBe("all"); + expect(data.models_resolved).toBe(false); + expect(data.data.queryFreeTierQuotaRequest.models).toEqual([]); + }); }); describe.skipIf(!isConsoleE2EReady())("e2e: usage free(Console)", () => { diff --git a/packages/commands/tests/e2e/usage-freetier.e2e.test.ts b/packages/commands/tests/e2e/usage-freetier.e2e.test.ts index e88916b2..31fcffb2 100644 --- a/packages/commands/tests/e2e/usage-freetier.e2e.test.ts +++ b/packages/commands/tests/e2e/usage-freetier.e2e.test.ts @@ -92,4 +92,26 @@ describe("e2e: usage freetier", () => { expect(data.api).toBe("zeldaEasy.bailian-commerce.freeTrial.batchDeactivateFreeTierOnly"); expect(data.data.BatchDeactivateFreeTierOnlyRequest.models).toEqual(["qwen-plus"]); }); + + test("usage freetier --all --dry-run 标注全量范围未解析,不把空列表当执行计划", async () => { + const { stdout, stderr, exitCode } = await runCommandInProcess(USAGE_ROUTES, [ + "usage", + "freetier", + "--all", + "--dry-run", + "--output", + "json", + ]); + expect(exitCode, stderr).toBe(0); + const data = parseStdoutJson<{ + api: string; + scope: string; + models_resolved: boolean; + data: { BatchActivateFreeTierOnlyRequest: { models: string[] } }; + }>(stdout); + expect(data.api).toBe("zeldaEasy.bailian-commerce.freeTrial.batchActivateFreeTierOnly"); + expect(data.scope).toBe("all"); + expect(data.models_resolved).toBe(false); + expect(data.data.BatchActivateFreeTierOnlyRequest.models).toEqual([]); + }); }); diff --git a/packages/commands/tests/output/usage-output.test.ts b/packages/commands/tests/output/usage-output.test.ts index 6161dbb6..d9c47fda 100644 --- a/packages/commands/tests/output/usage-output.test.ts +++ b/packages/commands/tests/output/usage-output.test.ts @@ -400,6 +400,51 @@ test.each(cases)("$name dry-run is one JSON result without API calls", async (sc expect(calls).toEqual([]); expect(openCalls).toEqual([]); }); + +test.each(["text", "json"] as const)( + "auto-stop --all dry-run marks unresolved full scope in %s", + async (format) => { + const result = await invoke( + { ...cases[1]!, flags: { all: true } }, + { format, quiet: true, dryRun: true }, + ); + expect(result.exitCode, result.stderr).toBe(0); + expect(result.strayOut + result.strayErr).toBe(""); + expect(calls).toEqual([]); + const preview = { + api: "zeldaEasy.bailian-commerce.freeTrial.batchActivateFreeTierOnly", + scope: "all", + models_resolved: false, + data: { BatchActivateFreeTierOnlyRequest: { models: [] } }, + }; + if (format === "json") expect(JSON.parse(result.stdout)).toMatchObject(preview); + else { + expect(result.stdout).toContain("scope: all"); + expect(result.stdout).toContain("models_resolved: false"); + } + }, +); + +test.each(["text", "json"] as const)( + "usage free dry-run without --model marks unresolved full scope in %s", + async (format) => { + const result = await invoke({ ...cases[0]!, flags: {} }, { format, quiet: true, dryRun: true }); + expect(result.exitCode, result.stderr).toBe(0); + expect(result.strayOut + result.strayErr).toBe(""); + expect(calls).toEqual([]); + const preview = { + api: "zeldaEasy.bailian-commerce.freeTrial.queryFreeTierQuota", + scope: "all", + models_resolved: false, + data: { queryFreeTierQuotaRequest: { models: [] } }, + }; + if (format === "json") expect(JSON.parse(result.stdout)).toMatchObject(preview); + else { + expect(result.stdout).toContain("scope: all"); + expect(result.stdout).toContain("models_resolved: false"); + } + }, +); test.each(cases)("$name failure is one structured error", async (scenario) => { failure = true; const result = await invoke(scenario, { format: "json", quiet: true }); diff --git a/packages/core/src/types/command.ts b/packages/core/src/types/command.ts index 6902a058..845b82ea 100644 --- a/packages/core/src/types/command.ts +++ b/packages/core/src/types/command.ts @@ -80,7 +80,8 @@ export const GLOBAL_FLAGS = { }, output: { type: "string", - valueHint: "", + valueHint: "", + choices: ["text", "json"] as const, description: { "en-US": "Output format: text, json", "zh-CN": "输出格式:text、json" }, }, timeout: { diff --git a/packages/runtime/src/create-cli.ts b/packages/runtime/src/create-cli.ts index 9397dead..99ee94ca 100644 --- a/packages/runtime/src/create-cli.ts +++ b/packages/runtime/src/create-cli.ts @@ -83,19 +83,34 @@ function presentationFlags(argv: string[]): Partial { for (let index = 0; index < argv.length; index++) { const argument = argv[index]!; if (argument === "--") break; - if (argument === "--quiet") flags.quiet = true; - else if (argument === "--verbose") flags.verbose = true; - else - for (const key of ["output", "config"] as const) { - if (argument.startsWith(`--${key}=`)) flags[key] = argument.slice(key.length + 3); - else if (argument === `--${key}`) { - const value = argv[index + 1]; - if (value !== undefined && !value.startsWith("--")) { - flags[key] = value; - index++; - } + if (argument === "--quiet") { + flags.quiet = true; + continue; + } + if (argument === "--verbose") { + flags.verbose = true; + continue; + } + + for (const key of ["output", "config"] as const) { + let value: string | undefined; + if (argument.startsWith(`--${key}=`)) value = argument.slice(key.length + 3); + else if (argument === `--${key}`) { + const next = argv[index + 1]; + if (next !== undefined && !next.startsWith("--")) { + value = next; + index++; } + } else continue; + + if (value === undefined) continue; + if (key === "config") { + flags.config = value; + continue; } + // Only accept legal formats here; illegal values are rejected by parseFlags. + if (value === "text" || value === "json") flags.output = value; + } } return flags; } diff --git a/packages/runtime/tests/args.test.ts b/packages/runtime/tests/args.test.ts index b96a834e..fbf19c3e 100644 --- a/packages/runtime/tests/args.test.ts +++ b/packages/runtime/tests/args.test.ts @@ -267,6 +267,21 @@ test("parseFlags validates number flags", () => { ); }); +test("parseFlags rejects illegal --output values", () => { + expect(() => parseFlags(["--prompt", "x", "--output", "yaml"], OPTS)).toThrowError( + expect.objectContaining({ + name: "UsageError", + exitCode: ExitCode.USAGE, + message: expect.stringContaining("Flag --output must be one of: text, json"), + }), + ); +}); + +test("parseFlags accepts legal --output values", () => { + expect(parseFlags(["--prompt", "x", "--output", "json"], OPTS).output).toBe("json"); + expect(parseFlags(["--prompt", "x", "--output", "text"], OPTS).output).toBe("text"); +}); + test("parseFlags throws UsageError when a required flag is missing", () => { expect(() => parseFlags(["--model", "qwen-image-2.0"], OPTS)).toThrowError( expect.objectContaining({ diff --git a/packages/runtime/tests/runtime-output.e2e.test.ts b/packages/runtime/tests/runtime-output.e2e.test.ts index 34ca765d..5b110f14 100644 --- a/packages/runtime/tests/runtime-output.e2e.test.ts +++ b/packages/runtime/tests/runtime-output.e2e.test.ts @@ -120,6 +120,13 @@ test.each( expect(diagnostics(result.stderr)[0].error.code).toBe(2); }); +test("illegal --output value is a usage error instead of silent text fallback", async () => { + const result = await invoke(["probe", "--output", "yaml"]); + expect(result.exitCode).toBe(2); + expect(result.stdout).toBe(""); + expect(result.stderr).toContain("Flag --output must be one of: text, json"); +}); + test("corrupt configuration preserves defaults with a structured warning", async () => { const result = await invoke(["probe", "--output", "json"], { corrupt: true, diff --git a/skills/bailian-cli/reference/index.md b/skills/bailian-cli/reference/index.md index d78c7e4d..7acbd63b 100644 --- a/skills/bailian-cli/reference/index.md +++ b/skills/bailian-cli/reference/index.md @@ -159,17 +159,17 @@ Use this index for the skill-scoped quick index and global flags. Available on every command (in addition to command-specific flags): -| Flag | Type | Required | Description | -| --------------------- | ------ | -------- | --------------------------------------------------------- | -| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | -| `--output ` | string | no | Output format: text, json | -| `--timeout ` | 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 ` | string | no | Use a config profile for this command | -| `--help` | switch | no | Show help | -| `--version` | switch | no | Print version | +| Flag | Type | Required | Description | +| ----------------------- | ------ | -------- | --------------------------------------------------------- | +| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | +| `--output ` | string | no | Output format: text, json | +| `--timeout ` | 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 ` | string | no | Use a config profile for this command | +| `--help` | switch | no | Show help | +| `--version` | switch | no | Print version | ## Model auth flags diff --git a/skills/bailian-finetune/reference/index.md b/skills/bailian-finetune/reference/index.md index 61959088..0e94c76d 100644 --- a/skills/bailian-finetune/reference/index.md +++ b/skills/bailian-finetune/reference/index.md @@ -77,17 +77,17 @@ Use this index for the skill-scoped quick index and global flags. Available on every command (in addition to command-specific flags): -| Flag | Type | Required | Description | -| --------------------- | ------ | -------- | --------------------------------------------------------- | -| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | -| `--output ` | string | no | Output format: text, json | -| `--timeout ` | 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 ` | string | no | Use a config profile for this command | -| `--help` | switch | no | Show help | -| `--version` | switch | no | Print version | +| Flag | Type | Required | Description | +| ----------------------- | ------ | -------- | --------------------------------------------------------- | +| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | +| `--output ` | string | no | Output format: text, json | +| `--timeout ` | 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 ` | string | no | Use a config profile for this command | +| `--help` | switch | no | Show help | +| `--version` | switch | no | Print version | ## Model auth flags diff --git a/skills/bailian-gen/reference/index.md b/skills/bailian-gen/reference/index.md index 21c0d26d..62cab27f 100644 --- a/skills/bailian-gen/reference/index.md +++ b/skills/bailian-gen/reference/index.md @@ -42,17 +42,17 @@ Use this index for the skill-scoped quick index and global flags. Available on every command (in addition to command-specific flags): -| Flag | Type | Required | Description | -| --------------------- | ------ | -------- | --------------------------------------------------------- | -| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | -| `--output ` | string | no | Output format: text, json | -| `--timeout ` | 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 ` | string | no | Use a config profile for this command | -| `--help` | switch | no | Show help | -| `--version` | switch | no | Print version | +| Flag | Type | Required | Description | +| ----------------------- | ------ | -------- | --------------------------------------------------------- | +| `--introspect` | switch | no | Print the machine-readable command schema (JSON) and exit | +| `--output ` | string | no | Output format: text, json | +| `--timeout ` | 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 ` | string | no | Use a config profile for this command | +| `--help` | switch | no | Show help | +| `--version` | switch | no | Print version | ## Model auth flags diff --git a/skills/bailian-knowledge/reference/knowledge.md b/skills/bailian-knowledge/reference/knowledge.md index ae3f622c..4f93c498 100644 --- a/skills/bailian-knowledge/reference/knowledge.md +++ b/skills/bailian-knowledge/reference/knowledge.md @@ -19,23 +19,23 @@ bl knowledge category add --name [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | ------------------------------------------------------------------ | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --collection-id | string | — | Create under this collection (defaults to the platform collection) | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | yes | Category name (1-20 chars) | -| --output | string | — | Output format: text, json | -| --parent-id | string | — | Create as a sub-category of this category | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | ------------------------------------------------------------------ | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --collection-id | string | — | Create under this collection (defaults to the platform collection) | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | yes | Category name (1-20 chars) | +| --output | string | — | Output format: text, json | +| --parent-id | string | — | Create as a sub-category of this category | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -70,22 +70,22 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --category-id | string | yes | Category ID to delete | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --category-id | string | yes | Category ID to delete | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -114,25 +114,25 @@ bl knowledge category list [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | --------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --collection-id | string | — | Filter by exact collection ID | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --max-result | number | — | Items per page (default: 20) | -| --name | string | — | Filter by category name (exact match, unlike the knowledge base list) | -| --next-token | string | — | Cursor for the next page (from previous output) | -| --output | string | — | Output format: text, json | -| --parent-id | string | — | List sub-categories of this exact parent category | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --collection-id | string | — | Filter by exact collection ID | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --max-result | number | — | Items per page (default: 20) | +| --name | string | — | Filter by category name (exact match, unlike the knowledge base list) | +| --next-token | string | — | Cursor for the next page (from previous output) | +| --output | string | — | Output format: text, json | +| --parent-id | string | — | List sub-categories of this exact parent category | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -181,7 +181,7 @@ bl knowledge chat --message --agent-id [flags] | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | | --message | array | — | Message text (repeatable). Supports role:content prefix to set role (e.g. user:hello), defaults to user. Follows OpenAI message format | | --messages-file | string | — | Complete messages JSON array, including tool history (excludes --message/--image) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --quiet | switch | — | Suppress non-essential output | | --request-id | string | — | Business request ID | | --session-file-id | array | — | Session file ID (repeatable, up to 10; requires service file preprocessing) | @@ -243,7 +243,7 @@ bl knowledge chunk add --index-id (--content | --field ) [flags | --image-url | array | — | Chunk image URL (repeatable, up to 10; document-type) | | --index-id | string | yes | Knowledge base ID | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | | --title | string | — | Chunk title, up to 50 chars (document-type) | @@ -296,23 +296,23 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --chunk-id | array | yes | Chunk ID to delete (repeatable; batches of 10 are sent automatically) | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --chunk-id | array | yes | Chunk ID to delete (repeatable; batches of 10 are sent automatically) | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -341,24 +341,24 @@ bl knowledge chunk list --index-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --doc-id | string | — | Only show chunks belonging to this document | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --page-number | number | — | Page number (default: 1) | -| --page-size | number | — | Page size per request | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --doc-id | string | — | Only show chunks belonging to this document | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --page-number | number | — | Page number (default: 1) | +| --page-size | number | — | Page size per request | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -404,7 +404,7 @@ bl knowledge chunk update --index-id --chunk-id --doc-id [flags] | --include | switch | — | Include this chunk in retrieval (default) | | --index-id | string | yes | Knowledge base ID | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | | --title | string | — | Chunk title, 0-50 chars (empty string clears it; omit to keep unchanged) | @@ -443,25 +443,25 @@ bl knowledge collection create --name --description [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | ----------------------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --description | string | yes | What this collection holds and what it is for — tells collections apart in the list | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | yes | Collection name | -| --oss-bucket | string | — | OSS bucket name (required with --store-type custom) | -| --oss-region | string | — | OSS region id (required with --store-type custom) | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --store-type | string | — | Storage: platform (managed) or custom (your own OSS bucket) | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | ----------------------------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --description | string | yes | What this collection holds and what it is for — tells collections apart in the list | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | yes | Collection name | +| --oss-bucket | string | — | OSS bucket name (required with --store-type custom) | +| --oss-region | string | — | OSS region id (required with --store-type custom) | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --store-type | string | — | Storage: platform (managed) or custom (your own OSS bucket) | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -494,22 +494,22 @@ bl knowledge collection get (--collection-id | --name ) [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --collection-id | string | — | Collection ID; alternative to --name | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | — | Collection name; alternative to --collection-id | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --collection-id | string | — | Collection ID; alternative to --name | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | — | Collection name; alternative to --collection-id | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Examples @@ -551,7 +551,7 @@ bl knowledge create --name --description (--doc-id | --catego | --knowledge-type | string | — | Knowledge type: document or multimedia | | --multimodal-embedding-model | string | — | Multimodal embedding model (multimedia/visual scene: alias of --embedding-model) | | --name | string | yes | Knowledge base name (1-20 chars, unique in workspace) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --poll-interval | number | — | Polling interval when waiting (default: 5) | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | @@ -604,22 +604,22 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -656,23 +656,23 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --doc-id | array | yes | Document ID to delete (repeatable) | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --doc-id | array | yes | Document ID to delete (repeatable) | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -721,7 +721,7 @@ bl knowledge doc import --index-id (--doc-id ... | --category-id < | --help | switch | — | Show help | | --index-id | string | yes | Existing knowledge base ID | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --overlap-size | number | — | Document overlap size, 0-1024 characters | | --poll-interval | number | — | Polling interval (default: 5 seconds) | | --quiet | switch | — | Suppress non-essential output | @@ -770,7 +770,7 @@ bl knowledge doc import-oss --bucket --region --oss-key [flags | --help | switch | — | Show help | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | | --oss-key | array | yes | OSS object key to import (repeatable, 1-10 per call) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --overwrite | switch | — | Overwrite files previously imported from the same OSS keys | | --parser | string | — | File parser (e.g. AUTO_SELECT or DOCMIND_LLM_VERSION_MEDIA) | | --parser-config-file | string | — | JSON object containing parser configuration | @@ -813,24 +813,24 @@ bl knowledge doc list --index-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --details | switch | — | Include file-level chunk configuration (page size up to 10) | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --page-number | number | — | Page number (default: 1) | -| --page-size | number | — | Page size per request | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --details | switch | — | Include file-level chunk configuration (page size up to 10) | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --page-number | number | — | Page number (default: 1) | +| --page-size | number | — | Page size per request | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -871,7 +871,7 @@ bl knowledge doc status --index-id --job-id [flags] | --index-id | string | yes | Knowledge base ID | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | | --job-id | string | yes | Import job ID (ingestionId returned by import commands) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --page-number | number | — | Page number (default: 1) | | --page-size | number | — | Page size per request | | --poll-interval | number | — | Polling interval when waiting (default: 5) | @@ -933,7 +933,7 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit | --help | switch | — | Show help | | --index-id | string | yes | Target knowledge base ID | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --poll-interval | number | — | Polling interval (default: 5 seconds) | | --quiet | switch | — | Suppress non-essential output | | --state-file | string | — | Checkpoint path (default: /.bailian/sync/.json, keyed by knowledge base ID) | @@ -977,23 +977,23 @@ bl knowledge doc tag --doc-id --tag [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --doc-id | array | yes | Data-center file ID to tag (repeatable, 1-20 per call) | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --mode | string | — | Update mode: append (default) or overwrite | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --tag | array | yes | Tag applied to every --doc-id (repeatable, each up to 32 chars) | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --doc-id | array | yes | Data-center file ID to tag (repeatable, 1-20 per call) | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --mode | string | — | Update mode: append (default) or overwrite | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --tag | array | yes | Tag applied to every --doc-id (repeatable, each up to 32 chars) | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1036,7 +1036,7 @@ bl knowledge doc upload --file [flags] | --help | switch | — | Show help | | --index-id | string | — | Import into this knowledge base after registration (one job for all files) | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --parser | string | — | File parser (e.g. AUTO_SELECT or DOCMIND_LLM_VERSION_MEDIA) | | --parser-config-file | string | — | JSON object containing parser configuration | | --poll-interval | number | — | Polling interval when waiting (default: 5) | @@ -1097,22 +1097,22 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --file-id | string | yes | Data-center file ID to delete | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --file-id | string | yes | Data-center file ID to delete | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -1143,21 +1143,21 @@ bl knowledge file get --file-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --file-id | string | yes | Data-center file ID | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --file-id | string | yes | Data-center file ID | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Examples @@ -1178,25 +1178,25 @@ bl knowledge file list --category-id [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | ---------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --category-id | string | yes | Category to list (find ids via the category list command); exact match | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --file-id | array | — | Filter by exact file ID (repeatable) | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --max-result | number | — | Items per page | -| --name | string | — | Filter by exact file name without its extension (a.md → pass a) | -| --next-token | string | — | Cursor for the next page (from previous output) | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | ---------------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --category-id | string | yes | Category to list (find ids via the category list command); exact match | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --file-id | array | — | Filter by exact file ID (repeatable) | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --max-result | number | — | Items per page | +| --name | string | — | Filter by exact file name without its extension (a.md → pass a) | +| --next-token | string | — | Cursor for the next page (from previous output) | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1229,21 +1229,21 @@ bl knowledge info --index-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | yes | Knowledge base ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | yes | Knowledge base ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1286,7 +1286,7 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit | --help | switch | — | Show help | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | | --name | string | — | Knowledge base name (1-20 characters; default: cli-demo) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --poll-interval | number | — | Polling interval (default: 5 seconds) | | --quiet | switch | — | Suppress non-essential output | | --state-file | string | — | Recovery checkpoint (default: ~/.bailian/knowledge/init/.json, keyed by workspace and name) | @@ -1331,23 +1331,23 @@ bl knowledge list [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | — | Filter by knowledge base name (fuzzy match, 1-20 chars) | -| --output | string | — | Output format: text, json | -| --page-number | number | — | Page number (default: 1) | -| --page-size | number | — | Page size per request | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | — | Filter by knowledge base name (fuzzy match, 1-20 chars) | +| --output | string | — | Output format: text, json | +| --page-number | number | — | Page number (default: 1) | +| --page-size | number | — | Page size per request | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1392,7 +1392,7 @@ bl knowledge search --agent-id (--query | --image ) [flags] | --image | array | — | Image URL for multimodal retrieval (repeatable) | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | | --kb-search-configs-file | string | — | JSON array of knowledge IDs and online search_filters | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --query | string | — | Search text (or provide --image) | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | @@ -1433,21 +1433,21 @@ bl knowledge service copy --agent-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --agent-id | string | yes | Source service (agent) ID to copy | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --agent-id | string | yes | Source service (agent) ID to copy | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1474,25 +1474,25 @@ bl knowledge service create --name --scene [flags] ### Flags -| Flag | Type | Required | Description | -| -------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --config-file | string | — | Complete agent_config JSON file (excludes --index-id) | -| --description | string | — | What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars) | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | — | Bind this knowledge base; other settings use server defaults | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | yes | Service name (up to 200 chars, unique per scene in the workspace) | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --scene | string | yes | Service scene: chat (Q&A) or search (retrieval) | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --config-file | string | — | Complete agent_config JSON file (excludes --index-id) | +| --description | string | — | What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars) | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | — | Bind this knowledge base; other settings use server defaults | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | yes | Service name (up to 200 chars, unique per scene in the workspace) | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --scene | string | yes | Service scene: chat (Q&A) or search (retrieval) | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1533,22 +1533,22 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --agent-id | string | yes | Service (agent) ID | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | -| --quiet | switch | — | Suppress non-essential output | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | -| --yes | switch | — | Confirm this high-risk operation | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --agent-id | string | yes | Service (agent) ID | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --output | string | — | Output format: text, json | +| --quiet | switch | — | Suppress non-essential output | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| --yes | switch | — | Confirm this high-risk operation | ### Notes @@ -1596,7 +1596,7 @@ Use `--yes` only after the user has confirmed this operation and its scope. Exit | --dry-run | switch | — | Dry run mode | | --help | switch | — | Show help | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | | --verbose | switch | — | Print HTTP request/response details | @@ -1646,7 +1646,7 @@ bl knowledge service get --agent-id [flags] | --dry-run | switch | — | Dry run mode | | --help | switch | — | Show help | | --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --quiet | switch | — | Suppress non-essential output | | --timeout | number | — | Request timeout | | --verbose | switch | — | Print HTTP request/response details | @@ -1682,27 +1682,27 @@ bl knowledge service list --scene [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | --------------------------------------------------------------- | -| --agent-id | string | — | Filter by exact agent ID | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --help | switch | — | Show help | -| --index-id | string | — | Filter by exact linked knowledge base (pipeline) ID | -| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | -| --name | string | — | Filter by service name (fuzzy match) | -| --output | string | — | Output format: text, json | -| --page-number | number | — | Page number (default: 1) | -| --page-size | number | — | Page size per request | -| --quiet | switch | — | Suppress non-essential output | -| --scene | string | yes | Service scene: chat (Q&A) or search (retrieval) | -| --status | string | — | Filter by status: draft, deployed (includes edited) or deleted | -| --timeout | number | — | Request timeout | -| --verbose | switch | — | Print HTTP request/response details | -| --version | switch | — | Print version | -| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | +| Flag | Type | Required | Description | +| --------------------- | ------ | -------- | --------------------------------------------------------------- | +| --agent-id | string | — | Filter by exact agent ID | +| --api-key | string | — | API key | +| --base-url | string | — | API base URL | +| --config | string | — | Use a config profile for this command | +| --dry-run | switch | — | Dry run mode | +| --help | switch | — | Show help | +| --index-id | string | — | Filter by exact linked knowledge base (pipeline) ID | +| --introspect | switch | — | Print the machine-readable command schema (JSON) and exit | +| --name | string | — | Filter by service name (fuzzy match) | +| --output | string | — | Output format: text, json | +| --page-number | number | — | Page number (default: 1) | +| --page-size | number | — | Page size per request | +| --quiet | switch | — | Suppress non-essential output | +| --scene | string | yes | Service scene: chat (Q&A) or search (retrieval) | +| --status | string | — | Filter by status: draft, deployed (includes edited) or deleted | +| --timeout | number | — | Request timeout | +| --verbose | switch | — | Print HTTP request/response details | +| --version | switch | — | Print version | +| --workspace-id | string | — | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) | ### Notes @@ -1753,7 +1753,7 @@ bl knowledge service update --agent-id [flags] | --max-llm-calls | number | — | Max LLM calls per request, range 1-30 | | --model | string | — | Generation model code (must be in the platform allowlist) | | --name | string | — | New service name (up to 200 chars) | -| --output | string | — | Output format: text, json | +| --output | string | — | Output format: text, json | | --policy | string | — | Agent policy: turbo (fast) or agentic (multi-turn) | | --quiet | switch | — | Suppress non-essential output | | --temperature | number | — | Sampling temperature, range 0-2 | @@ -1804,23 +1804,23 @@ bl knowledge stats --index-id [flags] ### Flags -| Flag | Type | Required | Description | -| ------------------- | ------ | -------- | ---------------------------------------------------------------------------------- | -| --api-key | string | — | API key | -| --base-url | string | — | API base URL | -| --config | string | — | Use a config profile for this command | -| --dry-run | switch | — | Dry run mode | -| --end