三、安装客户端
macOS / Linux：
curl https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh | sudo sh
Windows：
curl.exe -fsSL https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.bat -o install.bat && install.bat
四、卸载客户端
macOS / Linux：
curl https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh | sudo sh -s — –uninstall
Windows：
curl.exe -fsSL https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.bat -o install.bat && install.bat –uninstall
五、升级客户端
macOS / Linux：
curl https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.sh | sudo sh -s — –upgrade
Windows：
curl.exe -fsSL https://wedata3-platform-bundle-cq-1257305158.cos.ap-chongqing.myqcloud.com/bundle_sh/install.bat -o install.bat && install.bat –upgrade
六、查看版本
databuddy -vdatabuddy –version
八、登录
databuddy auth logindatabuddy auth login –host "<workspace-url>"
| 参数 | 说明 | 是否必填 |
| –host | 目标 Workspace 地址 | 否（使用默认 Profile 中的地址） |
<workspace-url> 为 DataBuddy 控制台中目标 Workspace 的完整地址，登录控制台并进入目标 Workspace 后，从浏览器地址栏复制即可，形如 https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>。其中 o 为 Workspace ID，r 为地域 ID，均由控制台自动生成，无需手动拼接。
注意：<workspace-url> 必须用双引号包裹。使用单引号会导致 URL 解析失败，不加引号会导致身份验证失败。地址中必须包含 o= 参数，否则提示 workspace id is empty, 'o' param not found in URL。
直接执行 databuddy auth login 时，终端会依次提示输入配置名称（直接回车沿用当前配置）与 Workspace 地址。登录成功后终端显示 Verification Success，登录状态保留 7 天。
九、使用密钥登录
适用于 CI/CD 流水线等非交互式场景。编辑 ~/.databuddycfg 配置文件：
[default]host = https://databuddy.cloud.tencent.com/workbench?o=<workspace_id>&r=<region_id>secret_id = <your_secret_id>secret_key = <your_secret_key>project_id = <project_id>user_name = <user_name>user_id = <user_id>region = ap-singaporeis_intl = false
注意：密钥文件包含敏感信息，请确保文件权限设置为 600（仅当前用户可读写）。
十、查看认证信息
databuddy auth describedatabuddy auth describe -p <profile_name>databuddy auth describe –host <sub_account>databuddy auth describe –sensitive
| 参数 | 说明 |
| -p | 查看指定 Profile 的认证信息 |
| –host | 查看指定子账号对应的 Profile 信息 |
| –sensitive | 输出敏感信息（secret_id 和 secret_key）；未指定时显示为 ****** |
十二、通用参数
以下参数适用于大部分 databuddy bundle 子命令：
| 参数 | 说明 |
| -t, –target <string> | 指定目标 Target（如 dev / staging / prod） |
| -p, –profile <string> | 指定使用的 Profile |
| –var "<key>=<value>" | 覆盖 Bundle 变量（支持 validate / deploy / summary / destroy） |
| –help | 查看命令帮助 |
十三、初始化 Bundle
databuddy bundle init
交互式引导创建 Bundle 项目模板。系统依次引导：
1. 选择模板
系统展示内置模板列表，支持上下键选择或输入模板名称：
| 模板 | 说明 | 适用人群 |
| SQL | SQL 加工任务项目骨架，含示例 SQL 文件和工作流配置 | 数据开发工程师，写 SQL 做 ETL |
| Notebook | Notebook 任务项目骨架，含示例 ipynb 文件 | 用 Python 做复杂数据处理 |
| Minimal | 最小骨架，仅含 databuddy.yml 和空目录结构 | 想完全自定义的高级用户 |
2. 配置项目
选择模板后，系统依次询问项目名称和计算资源。[] 中为默认值，直接按回车将使用默认配置。Compute 需要手动输入计算资源名称。
3. 完成创建
生成的目录结构示例（SQL 模板）：
yiwu_etl/├── databuddy.yml├── src/│ └── sql_example.sql├── resources/│ └── workflow/│ └── sql_example.yml└── README.md
注意：说明：
注意：init 生成的项目无需修改配置即可直接执行 databuddy bundle deploy。调度默认为每天 0 点执行（UTC+8），计算资源和运行账号已在初始化时配置完成。
十四、拉取资源（generate）
databuddy bundle generate workflow –existing-workflow-id <workflow_id>
将 DataBuddy 中已有的工作流配置拉取到本地 Bundle。workflow 为资源类型，–existing-workflow-id 指定要拉取的工作流 ID。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
十五、绑定资源（bind）
databuddy bundle deployment bind workflow <resource_key> <workflow_id>
将线上已有的工作流与本地 Bundle 中的资源定义绑定。<resource_key> 为本地资源标识，<workflow_id> 为线上工作流 ID。绑定后执行 deploy 可将本地配置同步到该工作流。
<resource_key> 取自本地 resources/workflow/*.yml 中 resources → workflows 下的键名。以下配置中的 <resource_key> 即为 workflow_a：
resources: workflows: workflow_a: # 该键名即 <resource_key> name: workflow_a
<workflow_id> 可在 DataBuddy 控制台的 数据工程 > Workflow 中打开目标工作流，从详情页地址栏或工作流属性中获取。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
十六、解除绑定（unbind）
databuddy bundle deployment unbind workflow <resource_key>
解除本地资源定义与线上工作流的绑定关系。<resource_key> 为本地资源标识。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
十七、验证 Bundle（validate）
databuddy bundle validate
校验 Bundle 配置的语法正确性和资源引用完整性。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
| –var | 覆盖 Bundle 变量（详见这篇「变量覆盖（–var）」） |
十八、部署 Bundle（deploy）
databuddy bundle deploydatabuddy bundle deploy -t devdatabuddy bundle deploy -t prod -p admin_profiledatabuddy bundle deploy –var="database=prod_ods"
将 Bundle 中定义的资源部署到目标环境。部署过程依次执行：配置校验 → 文件上传 → 资源部署。如果校验发现 Warning，系统会暂停并询问是否继续。若某个资源部署失败，后续资源仍会继续，最终统一展示失败项。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
| –var | 覆盖 Bundle 变量（详见这篇「变量覆盖（–var）」） |
十九、运行（run）
databuddy bundle run workflow <resource_key> -t devdatabuddy bundle run workflow <resource_key> –params="key1=value1" –params="key2=value2"
触发指定工作流的一次性运行。<resource_key> 为要运行的工作流资源标识。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
| –params | 指定运行时参数值，格式为 key=value，支持多次使用 |
20、销毁（destroy）
databuddy bundle destroydatabuddy bundle destroy -t dev
删除目标环境中由该 Bundle 部署的所有资源（工作流 + Studio 文件）。本地 Bundle 文件不受影响。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
| –var | 覆盖 Bundle 变量 |
注意：警告：
注意：destroy 操作不可逆。执行前系统会列出待删除资源并要求确认。
21、查看摘要（summary）
databuddy bundle summarydatabuddy bundle summary -t devdatabuddy bundle summary –var="database=prod_ods"
展示当前 Bundle 的部署状态和资源信息。
| Flag | 说明 |
| -t, –target | 指定目标 Target |
| -p, –profile | 指定 Profile |
| –var | 覆盖 Bundle 变量 |
22、查看帮助
databuddy bundle –help
23、变量覆盖（–var）
在命令行中使用 –var 参数可覆盖 databuddy.yml 中定义的变量值，无需修改配置文件。
24、基本语法
databuddy bundle <command> –var="<key>=<value>" –var="<key>=<value>"databuddy bundle <command> –var="<key>=<value>,<key>=<value>"
25、支持的命令
| 命令 | 示例 |
| validate | databuddy bundle validate –var="database=prod_ods" |
| deploy | databuddy bundle deploy –var="database=prod_ods" |
| summary | databuddy bundle summary –var="database=prod_ods" |
| destroy | databuddy bundle destroy –var="database=prod_ods" |
26、传参方式
# 单个变量databuddy bundle deploy –var="database=prod_ods"# 多个变量（重复使用 –var）databuddy bundle deploy –var="database=prod_ods" –var="engine=presto"# 多个变量（逗号分隔）databuddy bundle deploy –var="database=prod_ods,engine=presto"
27、优先级
变量值的优先级从高到低：
1. 命令行 –var 指定的值（最高）
2. resources/ 中资源配置里的变量值
3. databuddy.yml → targets → 当前 Target 中定义的变量值
4. databuddy.yml → variables 中定义的全局默认值（最低）
28、命令速查表
| 命令 | 用途 |
| databuddy -v | 查看 CLI 版本 |
| databuddy auth login | 登录认证 |
| databuddy auth describe | 查看认证配置 |
| databuddy bundle init | 初始化 Bundle 项目（支持模板选择） |
| databuddy bundle generate workflow –existing-workflow-id <id> | 拉取工作流到本地 |
| databuddy bundle deployment bind workflow <key> <id> | 绑定工作流 |
| databuddy bundle deployment unbind workflow <key> | 解绑工作流 |
| databuddy bundle validate -t <target> | 验证 Bundle 配置 |
| databuddy bundle deploy -t <target> | 部署 Bundle |
| databuddy bundle deploy –var="key=value" | 部署时覆盖变量 |
| databuddy bundle run workflow <key> -t <target> | 运行工作流 |
| databuddy bundle run workflow <key> –params="key=value" | 带参数运行工作流 |
| databuddy bundle destroy -t <target> | 销毁部署 |
| databuddy bundle summary -t <target> | 查看部署摘要 |
| databuddy bundle –help | 查看帮助 |
29、相关文档
·CI/CD 概述
·Bundle 包定义
·使用 Bundle 开发
·Git 联动开发