全局参数作用于 bcecmd 本身，控制配置、日志、版本、性能剖析与输出格式等行为。它们对所有子命令（bos / bosapi / bosprobe）通用。

位置要求：全局参数必须写在子命令之前。 正确：bcecmd --debug --output json bos ls bos:/mybucket/ 错误：bcecmd bos ls bos:/mybucket/ --debug

参数总览

参数详解

--configure / -c

进入交互式配置向导，依次录入 Access Key、Secret Key、Region、Domain，完成后写入配置文件（默认位于用户 home 目录），随后进程退出。

1# 交互式配置（写入默认 home 目录）
2bcecmd -c
3bcecmd --configure
4
5# 指定配置写入目录
6bcecmd --configure /path/to/confdir

--conf-path

指定配置文件所在目录，覆盖默认的用户 home 目录。适用于多套配置或非默认路径场景，通常与子命令一起使用。

1bcecmd --conf-path /path/to/confdir bos ls bos:/mybucket/

--multiupload-infos-path

指定分片上传（multipart upload）断点续传信息的存放目录。大文件上传中断后，可据此恢复。

1bcecmd --multiupload-infos-path /path/to/mu-infos bos cp ./bigfile bos:/mybucket/

--debug / -d

开启调试日志，日志输出到 stderr，级别为 DEBUG，用于排查请求细节与问题定位。

1bcecmd -d bos ls bos:/mybucket/
2bcecmd --debug bos cp ./file bos:/mybucket/

--version / -v

打印 bcecmd 版本号并立即退出。

1bcecmd -v
2bcecmd --version
3# 输出示例： bcecmd vX.Y.Z from http://bce.baidu.com

--cost

命令执行结束后，额外打印本次命令的总耗时（毫秒），便于性能观察。

1bcecmd --cost bos sync ./localdir bos:/mybucket/dir/
2# 结束时输出： total cost:  1234  ms

--output

设置输出格式，可选 table（默认，人类可读）或 json（结构化，便于脚本解析）。

1# 默认表格输出
2bcecmd bos ls bos:/mybucket/
3
4# JSON 输出
5bcecmd --output json bos ls bos:/mybucket/

要点：

• --output 是全局参数，须放在 bos / bosapi 子命令之前。
• 当 stdout 被重定向（管道、写文件）时，程序自动进入非交互模式（自动 --yes、关闭进度条），配合 --output json 适合脚本集成。
• 成功数据写入 stdout，错误信息写入 stderr，二者分离，便于分别捕获。

组合示例

1# 开启调试 + JSON 输出 + 打印耗时
2bcecmd --debug --output json --cost bos ls bos:/mybucket/ 2>debug_and_err.log
3
4# 使用指定配置目录执行同步
5bcecmd --conf-path /etc/bcecmd bos sync ./data bos:/mybucket/data/

要点：

• 所有全局参数一律置于子命令（bos 等）之前。
• --configure / --version 属于「执行即退出」类参数，不会继续执行后续子命令。
• --debug 日志与 --output json 的结构化错误均写入 stderr；如需分离，可对 stdout / stderr 分别重定向。

各 bos 子命令 JSON 返回字段清单

下表为各子命令在 --output json 模式下写入 stdout 的数据结构（字段名与源码一致）。

已输出结构化数据的命令

ls 列举对象（带 bucket 路径时）：

1{
2  "objects": [
3    { "key": "a.txt", "size": 1024, "lastModified": "2026-07-15T...", "storageClass": "STANDARD" }
4  ],
5  "commonPrefixes": [ /* 子目录（非 --recursive 时） */ ],
6  "prefix": "<列举前缀>",
7  "delimiter": "/",          // --recursive 时为空字符串
8  "isTruncated": false,       // 是否还有下一页
9  "nextMarker": ""            // 下一页的 marker，配合 --marker 翻页
10}

字段说明：

• du 的 totalSize：默认形如 "12345 bytes"；加 --friendly 时形如 "1.5 GiB"。
• du --detail 的每个子目录明细当前不包含在 JSON 输出中，JSON 模式只输出总计（totalObjects / totalSize）。
• sync / cp / mv 的 failed > 0 时，进程以非 0 退出码结束（见第 4 节）。

暂未输出数据 payload 的命令

以下命令在 --output json 模式下不产生结构化数据 payload（仍走文本/静默输出），但结构化错误与分级退出码依旧生效：

• rm（删除对象）
• list-multi（列举未完成分片上传任务）
• revert（版本回退）

若脚本依赖这些命令的结果，请以退出码判断成败，不要期望其 stdout 为 JSON。

结构化错误（JSON 模式）

JSON 模式下所有错误统一输出到 stderr，结构如下：

1{
2  "error": {
3    "code": "NoSuchKey",     // 服务端错误码；无法识别时为 "ClientError"
4    "message": "...",         // 错误描述
5    "operation": "..."        // 可选，出错的操作/错误码上下文
6  }
7}

• 服务端错误（BceServiceError）会带上服务返回的 code（如 NoSuchKey、AccessDenied）。
• 客户端/本地错误统一 code 为 ClientError。
• 建议脚本单独重定向 stderr，例如 2>err.json，与 stdout 的数据分开处理。

分级退出码（Exit Code）

1bcecmd --output json bos ls bos:/mybucket/ >out.json 2>err.json
2ret=$?
3case $ret in
4  0) echo "成功" ;;
5  1) echo "客户端错误"; cat err.json ;;
6  2) echo "服务端错误"; cat err.json ;;
7  *) echo "异常退出，code=$ret" ;;
8esac

bosapi 命令的 JSON 输出

bosapi 系列命令同样适配了 JSON 模式，规律如下：

• get-* 类命令：直接输出服务端返回的对象（如 ACL、lifecycle、logging、versioning、tagging、storage-class 等原始结构）。
• put-* / append-* / delete-* 类命令：输出操作状态，形如 { "status": "success", ... }。
• lifecycle 为空时会正确输出 null，而非报错。

脚本集成建议

1#!/bin/bash
2set -o pipefail
3
4out=$(bcecmd --output json bos ls bos:/mybucket/ 2>/tmp/err.json)
5ret=$?
6if [ $ret -ne 0 ]; then
7    echo "list failed (exit=$ret):" >&2
8    cat /tmp/err.json >&2
9    exit $ret
10fi
11echo "$out" | jq '.objects[].key'

要点：

• 加 --output json，用 jq 等工具解析。
• 数据读 stdout，错误读 stderr。
• 按 $? 区分客户端（1）/服务端（2）错误做不同重试策略。
• 大目录列举用 --max-keys / --marker + nextMarker 翻页。