dibbla

Dibbla CLI

dibbla CLI 可用于搭建项目，并在 Dibbla 平台上管理应用、数据库、密钥和工作流。已部署的应用可通过 https://<alias>.dibbla.com 访问。

前置条件

如果 CLI 尚未位于用户的 PATH 中，请先安装 CLI：

平台	命令
macOS（Homebrew）	brew install dibbla-agents/tap/dibbla
macOS / Linux（Shell 安装程序）	curl -fsSL https://install.dibbla.com/install.sh | sh
Windows（PowerShell）	powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://install.dibbla.com/install.ps1 | iex"
验证	dibbla --version

Shell 安装程序会将二进制文件放入 ~/.local/bin，并在需要时调整 PATH。任务文件中可通过同一安装程序 URL 进行自更新。

部署需要在传给 dibbla deploy 的目录根目录下有一个 Dockerfile。CLI 不会自动检测语言或生成 Dockerfile——如果缺少该文件，后端会拒绝构建，并输出日志。dibbla-agents/dibbla-public-templates 中的所有内置模板都附带可用的 Dockerfile，可供复制（通常采用多阶段构建：Node → JS 构建 → Go → 二进制文件 → 小型运行时镜像，EXPOSE 80）。

命令一览

类别	命令
运行	run [path|url]、run --preview、run --env KEY=VAL、run --env-file <file>、run --work-dir <dir>、run --format plain|gh
模板	template list [--refresh] [-v]、template install <id> [<dir>] [--force]
技能	skills list、skills install <id>（--user、--force、--no-agents）——将 AI Agent 指引安装到 .claude/skills/ + AGENTS.md + GEMINI.md
设置	init（交互式设置向导：更新 → 登录 → 安装 dibbla 技能）、update [--check] [--version vX.Y.Z]（自更新；如果二进制由 brew/apt/rpm/scoop/choco 管理，则交由相应工具处理）、uninstall [--dry-run] [--keep-config] [--keep-skills] [--skill-only]（脚本安装时会移除二进制、钥匙串凭据、~/.config/dibbla/、~/.dibbla/，以及所有记录的安装根目录中的技能文件；通过包管理器安装时只显示原生卸载命令，不会操作二进制）
登录	login [api_url]、login --browser、login --api-key <token>、login --api-url <url>、login --write-env、login --no-keychain、logout
反馈	feedback <message>、feedback list、feedback delete <id>
部署	deploy [path] -m "<msg>" [--alias name] [--update] [--require-login] [--access-policy] [--google-scopes] [--target-env <env>] [--profile <p>] —— 从目录部署；-m 会作为 VCS 提交说明。--target-env / --profile / --no-public 仅在部署根目录存在 dibbla.yaml 时生效
清单	manifest validate [path] —— 对 dibbla.yaml 进行本地架构检查（无需网络）
预览	preview [path] [--target-env <env>] [--profile <p>] [--no-public] —— 由服务端权威执行的试运行；完整的环境感知解析 + 配额检查，不构建、不应用
应用	apps list、apps update <alias>、apps delete <alias>、apps restart <alias> --service <name>（按服务滚动重启）
日志	logs <app>（最近 15m）、logs <app> --since 24h、logs <app> -f（持续跟踪）、logs <app> -n 200（查看末尾日志）、logs <app> --grep <regex>、logs <app> --json —— 来自 Loki 的运行时日志；logs <app> --service <name> 仅筛选一个服务；当 Loki 不可用时，logs <app> --service <name> --pod-stream 会通过 K8s API 流式传输 Pod 日志
数据库	db list、db create、db delete、db dump、db restore、db connect
密钥	secrets list、secrets set、secrets get、secrets delete（全局；部署范围使用 -d <alias>；按服务使用 -d <alias> --service <name>）
管理	admin reconcile —— 在 deploy-api 实例上强制执行一次孤立资源扫描（需通过 DIBBLA_ADMIN_TOKEN 授权）
工作流	workflows list、get、create、update、delete、validate、execute [--async|--follow]、url、api-docs、logs <runId> [-f]
运行记录	wf runs list [--workflow <name>] [--limit <N>]、wf runs output <runId> —— 列出过往运行记录，并获取已完成运行的 api_response 负载
节点	nodes add <wf>、nodes remove <wf> <id>
边	edges add <wf> "<edge>"、edges remove、edges list
输入	inputs set <wf> <node> <input> <value>
工具	tools add <wf> <agent> <tool>、tools remove
修订版本	revisions list <wf>、revisions create、revisions restore
函数	functions list、functions get <server> <name>

Agent 指南

交互式提示： 以下命令会提示确认，在非交互模式下运行时会阻塞。作为 Agent 运行这些命令时，务必传入 --yes（或 -y）：

• dibbla apps delete <alias> --yes
• dibbla db delete <name> --yes
• dibbla secrets delete <name> --yes
• dibbla workflows delete <name> --yes
• dibbla nodes remove <wf> <id> --yes
• dibbla feedback delete <id> --yes 首次部署应用：

1. 检查应用是否已存在：dibbla apps list
2. 如果应用不存在，请在部署命令中包含所有必需的环境变量进行部署——此时还没有可供附加这些变量的应用：

   dibbla deploy . --alias my-app -m "feat: initial deploy" \
     -e DATABASE_URL=postgres://... -e API_KEY=secret -e NODE_ENV=production
   

3. 如果应用已存在，请使用 --update 进行零停机滚动更新：

   dibbla deploy . --alias my-app -m "fix: resolve 500 on /search" --update
   

   若要更改现有应用的环境变量，请改用 apps update：

   dibbla apps update my-app -e NEW_VAR=value
   

关键规则：

• 每次运行 dibbla deploy 都必须包含 -m "<message>"。 该值会成为应用在 Dibbla 管理的 VCS 历史记录（以及已配置时的 GitHub 镜像）中的 git 提交主题。请像编写 git 提交信息一样处理：使用现在时祈使语气，长度约不超过 72 个字符，说明更改内容和原因，例如 -m "fix: handle null org in /api/me"、-m "feat: add nightly db backup workflow"、-m "chore: bump node to 20.14"。重试或机械式重新部署时，也要明确说明：-m "redeploy: retry after CF 524"。最多 500 个字符。切勿在没有 -m 的情况下运行 dibbla deploy；部署历史为空是错误，不是默认行为。

• --force 会导致停机（拆除并重新部署）。对于现有应用，优先使用 --update。

• --force 和 --update 不能同时使用。

• 通过 deploy -e 或 apps update -e 设置的环境变量会在更新之间保留——只需传递一次。

• 登录保护： 使用 --require-login 要求用户进行身份验证。搭配 --access-policy invite_only 可限制为受邀用户访问，搭配 all_members 可允许组织内所有成员访问。使用 --google-scopes 可请求额外的 Google OAuth 范围（例如 Drive、Calendar）。

• 在脚本中对 db list、db delete、db connect 使用 --quiet / -q，以获得机器可读的输出。

• db create --deployment <alias> 会将数据库及其自动创建的密钥限定到特定部署。限定范围的密钥名称为 DATABASE_URL_<UPPERCASED_UNDERSCORED_NAME>（例如，数据库 my_db 对应 DATABASE_URL_MY_DB），而不是普通的 DATABASE_URL——应用代码必须读取带后缀的环境变量。

• db connect 会通过 Dibbla 数据库代理打印兼容 psql 的连接字符串。脚本中使用 -q：psql $(dibbla db connect mydb -q)。

• 部署时出现 524 ≠ 失败。 dibbla deploy 在后端构建期间会保持单个 HTTP 连接；耗时超过约 100 秒的构建可能会在客户端返回 Cloudflare 524，即使后端构建成功也是如此。等待 2–5 分钟，然后运行 dibbla apps list 检查。不要使用 --force 重试——如果必须重试，请使用 --update。

• 输出模式： 当标准输出是 TTY 时，dibbla deploy 会流式输出类似 buildkit 的实时步骤视图；当标准输出通过管道传输或运行于 CI 中时，则切换为带 ISO 时间戳的日志行（<ts> [info] build step=N/M …）。添加 --quiet 可输出单行成功/失败信息（便于脚本处理），添加 --json 可在标准输出中输出单个结构化对象。构建失败时，非 TTY 模式还会向标准错误写入一行结构化 JSON，格式为 {"event":"deploy.failed","step":"go-build","step_index":N,"step_count":M,"errors":[{file,line,col,message}],"retry_cmd":"…","api_error_code":"BUILD_FAILED"}——编码 Agent 应从标准错误读取此信息，以定位出错文件，而不是从人类可读的构建输出中提取。添加 --verbose-build 可获取完整的服务器构建日志，而非省略前段内容的日志尾部；当解析出的编译诊断信息不足时，可使用此选项。构建失败时退出码为 2；其他错误的退出码为 1。

• .dibblaignore 控制的是 Dibbla 管理的 VCS 历史记录，而不是 Docker 构建所能看到的内容。后端始终会从 VCS 中排除 .env、node_modules/、dist/、*.pem、*.key 等内容，并将每个命中项作为警告报告在 DeployResponse.vcs_filtered 中。在部署根目录的 .dibblaignore 中添加这些路径（或任何生成的／大型构件）可隐藏警告并保持 VCS 干净。单文件和单次提交的大小上限会导致硬性拒绝——提交大型构建构件会使部署因 ErrCodeVCSFiltered 而失败；解决方法是将该路径添加到 .dibblaignore。完整详情见 reference.md → deploy → .dibblaignore。

• 托管 Postgres 使用自签名 TLS 证书。应用客户端（pg、psycopg2、Prisma）需要显式处理 SSL——请参阅 reference.md 中的 “TLS for application database clients”，查看可用代码片段。 设计多服务清单： 在编写 dibbla.yaml 之前，先考虑以下设计问题，并与用户确认方案。在设计阶段跳过这一步，会导致后续改造波及每个使用方服务（环境变量、depends_on、服务发现引用），因此值得提前花 60 秒做好规划。

• 哪些服务只应存在于部分环境中？（例如，开发环境中使用内联 DB 容器，生产环境中使用托管式／外部 DB）→ 在特定环境的服务上设置 profiles: [dev]。请务必提前决定，因为使用方需要按环境设置指向该服务的 URL／主机名。

• 哪些字段会因环境而异？（replicas、image、MONGO_URL、LOG_LEVEL 等）→ 使用按环境配置的字段映射（参见 manifest.md 第 6 节）。这与配置文件不同：配置文件用于切换服务是否存在；按环境配置的字段则用于调整现有服务。

• 生产环境中的数据层将部署在哪里？ 如果使用托管式／外部服务，使用方需要按环境配置 MONGO_URL／DATABASE_URL（default: → 外部值，dev: → ${DIBBLA_SVC_*}），并且内联副本需要设置 profiles: [dev]。这两种机制需要配合使用，参见 manifest.md 第 7 节中的完整示例。

• 用户将如何在本地迭代？ 平台不会在本地运行 dibbla.yaml，也没有 dibbla up。请在旁边创建 docker-compose.yml，将清单镜像到其中，以便快速进行本地开发迭代（参见 examples.md 中的“使用 docker-compose 进行本地迭代”）。两者在细节上有所不同（没有 ${DIBBLA_SVC_*}、没有 NetworkPolicy、没有按环境解析），但整体结构一致。

• 生产环境中的任何公共服务是否涉及敏感信息？（管理界面、调试控制台、邮件捕获工具、内部仪表板）→ 为每个服务设置 auth: 块，并配置 require_login: true 和 access_policy:；或者使用 profiles: [dev] 限制整个服务。未对外部公开的管理界面设置身份验证，是 OWASP 级别的常见严重错误；guardrails.md 中的防护检查会对此进行强制检查。

部署前防护检查： 调用 dibbla deploy 之前，必须完成部署前检查清单并向用户展示检查结果。部署或修复问题前，务必等待用户明确确认；绝不能自行部署。防护检查工作流还会在项目根目录写入 REVIEW.md 文件，平台会读取该文件，并在仪表板中显示审核状态指示器。完整检查清单请参见 guardrails.md。

工作流： 工作流是由函数调用组成的有类型 DAG——节点通过名称引用注册表中的 function，边在数据端口之间传递数据，api 节点与 api_response 节点组合后即可通过 HTTP 调用。请使用精简 YAML 编写（wf get／wf create -f 所使用的格式）；切勿手动编写冗长的 React-Flow JSON。最简结构如下：

name: my_workflow
nodes:
  - {id: api_input,  type: api,          inputs: [question], outputs: [question]}
  - {id: greet,      type: function,     function: handlebars_template,
     server: go-function-server1,        inputs: {script: "Hello {{question}}!"},
     outputs: [error, output]}
  - {id: api_response, type: api_response, linked_to: api_input, inputs: [response]}
edges:
  - api_input.question -> greet.question
  - greet.output -> api_response.response

编写任何非简单工作流之前，先运行 dibbla fn list 查看已有函数，并对类似工作流运行 dibbla wf get <existing> -o yaml 了解结构——真实数据来源是函数注册表，而不是 YAML。选择与变更规模相匹配的迭代流程：小幅调整 → 使用 nodes add／edges add／inputs set／tools add 对 HEAD 进行补丁修改；结构性变更 → wf get … -o yaml → 编辑 → wf update -f。在执行任一流程前，务必先运行 dibbla revisions create <wf>；补丁不会自动创建快照，而 revisions restore 会覆盖 HEAD（它不是检出操作）。完整模型包括节点类型的作用、Agent 与工具的模式、全部 13 种验证器错误及其修复方法、执行和 HTTP 语义，以及三种规范工作流结构（转换、Agent 与工具、多阶段流水线），详见 workflows.md。 容易踩坑的工作流注意事项：

• 创建新 Agent 时选择 reasoning_agent_function — 据观察，reasoning_agent_with_thread 在当前 Claude 模型上可能会静默返回空响应。务必将 agent.error 接到 api_response.error，让静默故障显现出来。
• 生产环境调用方必须使用网关 URL，而不是 wf api-docs 打印的 URL。重写主机名：https://workflow-server.dibbla.net/api/execute/<name>/<urlid>（由 api-docs 显示，仅供内部使用）→ https://api.dibbla.net/api/wf/execute/<name>/<urlid>（网关，接受 Authorization: Bearer ak_<workflow-api-key>）。
• 经过多轮 wf update 后，发布前请重新创建工作流 — 网关 URL 中的 <urlid> 可能会悄然过期（调用会挂起约 5 分钟，且没有错误提示）。执行 wf delete --yes && wf create 可获取新的 id。
• 执行 wf create 时，节点 id 会变成函数名。 不要选择自定义 id；请使用函数名引用工具。
• reasoning_agent_function 的结果缓存有效期为 1 小时。 迭代测试时，请更改输入或使用 *_no_cache 变体。
• 获取工作流时，务必使用带 30–60s 超时的 AbortController 包装请求，并在请求前后记录日志 — Node 的默认 5 分钟超时会让故障看起来像是请求挂起。

运行监控与异步执行：

• dibbla wf execute 默认同步执行 — 会一直阻塞，直到工作流的 api_response 节点触发（服务端超时：30 分钟）。对于长时间运行的 Agent 工作流或即发即忘的批处理，请使用 --async，立即获取 response_metadata，同时运行在后台继续执行。之后可用 wf logs <runId> --follow 跟踪，并用 wf runs output <runId> 获取最终输出。
• dibbla wf execute --follow（-f）是交互式调试的一行命令：以异步方式启动运行，将实时日志跟踪输出到标准输出，然后在服务端发出 run_completed 哨兵后打印 api_response 负载。完成后以状态码 0 退出。
• dibbla wf logs <runId> 适用于任何运行。正在运行的任务会持续流式输出，直到完成；已完成的任务会返回历史日志和哨兵，然后立即退出。持久化策略：WARN/ERROR 和 run_completed 行会被持久化；INFO/DEBUG 仅实时输出 — 安静完成的任务在跟踪时基本只会显示 run completed。如需查看已完成任务的完整记录，请改用 wf runs output <runId>。
• dibbla wf runs list（使用 -w <name> 筛选，使用 -n <N> 分页；服务端上限为 500）可用于查找近期运行的 id，无需从仪表板或数据库复制。
• 短选项 -f 因命令而异： 对于 dibbla logs（应用日志）和 dibbla wf logs，-f 表示 --follow。对于 dibbla wf execute，-f 也表示 --follow — 但 --file 不再有短选项别名，改用 -F。不要对 wf execute 使用 -f payload.json；请使用 --file payload.json 或 -F payload.json。

构建 Go worker（sdk-go）： github.com/dibbla-agents/sdk-go Go SDK 用于让 worker 向平台注册自定义函数和作业。Worker 是一个长期运行的 gRPC 客户端：sdk.New(...) → server.RegisterFunction(...) 和 server.RegisterJob(...) → server.Start()（该方法会无限期阻塞）。外部用户模块只能使用 sdk.NewSimpleFunction[In, Out]，因为高级 Function[In, Out] 处理器签名会暴露 internal/types 和 internal/state — Go 的 internal/ 规则会阻止除 sdk-go 以外的模块导入这些包。JobHost 抽象已移除；作业通过 server.RegisterJob(handler) 直接注册。Worker 连接后，其函数会出现在 dibbla functions list 中，并可通过 (server, function) 配对从工作流 YAML 调用（请参阅 workflows.md，了解调用方的接线方式）。如需了解完整的 SDK 模型 — 服务器选项、函数构建器、JobHandler 接口、JobContext 参数辅助方法、Logger 任务/进度 API、通过 gs.OAuth 实现的 OAuth，以及注意事项 — 请参阅 sdk-go.md。 非 TTY／Agent 式调用：

• 从 Claude Code 的 ! 前缀、Agent shell、带浏览器的 CI 或任何其他非 TTY 环境中运行时，请使用 dibbla login --browser，而不是直接运行 dibbla login。交互流程需要通过 stdin 使用调查选择器；--browser 会跳过此步骤，直接通过 localhost 回调进行基于浏览器的 OAuth。
• 对于真正的无头环境（SSH 会话、云 VM、没有本地浏览器的 CI runner），请使用 dibbla login --api-key <token>，或设置 DIBBLA_API_TOKEN（以及可选的 DIBBLA_API_URL）环境变量——CLI 会在 CI 中自动读取环境变量。
• 云 VM／SSH／Docker（无密钥环）： dibbla login --api-key=<t> --api-url=<url> --write-env --no-keychain 会针对 API 验证令牌，并将 DIBBLA_API_TOKEN + DIBBLA_API_URL 写入 ./.env（必要时修改 .gitignore），且不会接触操作系统密钥环。在未安装 libsecret／gnome-keyring／pass 的全新 Ubuntu／EC2／GCE／Docker 镜像上使用此命令。之后在该目录中运行的每个 dibbla * 命令都会从 .env 读取凭据。需要 CLI ≥ v1.2.4。
• 每个命令都会读取 CWD 中的 .env，包括 login。 将 DIBBLA_API_TOKEN=… 和 DIBBLA_API_URL=https://api.dibbla.net 放入 ./.env，从该目录调用的每个 dibbla 命令都会使用该服务和令牌——无需调用 login。Shell 导出的变量仍优先于 .env（godotenv 不会覆盖变量）。需要 CLI ≥ v1.2.4。
• DIBBLA_AUTH_SERVICE_URL 是 DIBBLA_API_URL 的内部兼容别名，由 steprunner 注入到 dibbla run 启动的子进程中。用户应将 DIBBLA_API_URL 放入 .env；保留 DIBBLA_AUTH_SERVICE_URL 是为了让子进程通过 desktop／steprunner 约定使用的变量名获取相同的服务。

运行任务文件和模板：

• dibbla run <path> 会在本地执行 dibbla-task.yaml 工作流。它可能会检查工具、运行 shell 命令、启动后台开发服务器，以及打开浏览器——任务文件会以用户账户权限作为 shell 执行。
• dibbla run <https-url> 会从网络获取并执行 YAML。这等同于 curl | bash——只运行用户信任来源（例如 github.com/dibbla-agents/*）提供的 YAML。工作目录默认为用户调用命令时所在的 CWD，因此初始化克隆会放在预期目录，而不是临时目录中。
• dibbla template install <id> 是以下命令的便捷写法：mkdir ./<template-path> && cd ./<template-path> && dibbla run <bootstrap-url>。如果目标目录已存在，命令会拒绝执行；传入 --force 可复用该目录。使用 dibbla template list 查看可用 ID。
• 实际运行前，优先使用 dibbla run --preview 或 dibbla template list，以便用户查看将要执行的内容。

将此技能安装到项目中（以便其他 Agent 也能看到）：

• dibbla skills install dibbla 会将技能文件写入 ./.claude/skills/dibbla/，并在项目根目录放置 AGENTS.md 和 GEMINI.md 指引文件。之后，每个主要编码 Agent 都会自动获取这些指引——Claude Code 通过其原生技能路径，Cursor／Opencode／Codex／Copilot／Windsurf／Aider 通过 AGENTS.md（2026 年开放标准），Gemini CLI 通过 GEMINI.md。
• 技能内容嵌入在 CLI 二进制文件中（go:embed），因此无需网络，且技能版本与用户安装的 CLI 版本一致。运行 dibbla --version 查看版本。
• 标志：--user 会将技能安装到 $HOME，以覆盖整台机器，而非仅当前目录；--no-agents 会跳过 AGENTS.md 和 GEMINI.md（仅限 Claude Code）；--force 会覆盖本地修改过的技能文件。.claude/skills/<id>/ 中的未知文件始终会保留。
• AGENTS.md／GEMINI.md 指引块由标记分隔（…），因此重新运行时，标记之外现有的 AGENTS.md 内容会逐字节保留。
• 重复运行是幂等的——如果没有变化，就不会重写任何内容（mtime 不变）。使用 dibbla skills list 查看当前 CLI 附带的技能。

其他资源

• **平台兼容性：**请参阅 platform.md，了解 Dockerfile 契约、端口匹配、运行时环境、托管 Postgres TLS 处理、密钥／环境变量注入、身份验证标头契约（X-User-* 标头和 Google OAuth 范围代理）、上传边界、多服务运行时契约（§ 8.5）以及部署前兼容性检查清单。在 Dibbla 连接的项目中处理 Dockerfile、.dibblaignore、身份验证集成或部署就绪性问题时，请阅读此文档。
• **多服务清单架构：**请参阅 manifest.md，了解完整的 dibbla.yaml 架构——服务、作业、环境感知字段、配置文件、服务发现（DIBBLA_SVC_*）、expose_to／NetworkPolicy、卷、初始化容器、健康检查、多个公共服务、自定义域名、cron、构建时密钥、配额、错误代码以及端到端示例。用户编写或审查清单，或询问“如何在一次部署中同时运行 X 和 Y”时，请阅读此文档。
• **工作流：**请参阅 workflows.md，了解完整的工作流模型——精简 YAML 格式、三种节点类型以及 function 扮演的角色（Agent／工具／脚本／数据获取器）、Agent 和工具的连接模式、全部 13 种验证器错误及其修复方法、边和数据流、函数注册表、三种惯用的编写循环、修订语义、HTTP 执行、规范的工作流结构、预检清单以及易踩的坑。用户提出涉及 dibbla wf／nodes／edges／inputs／tools／revisions／functions 的任何问题时，请阅读此文档。
• **Go SDK：**请参阅 sdk-go.md，了解 Dibbla Go SDK——sdk.New 服务端引导和选项、SimpleFunction 与高级 Function[In, Out]、JobHandler 接口和 server.RegisterJob（旧的 JobHost 已移除）、Logger 任务／进度 API、通过 gs.OAuth 代表用户进行 OAuth、TLS 自动检测、internal/ 导入陷阱以及端到端部署。用户使用 Go 实现 Dibbla 函数或作业时，请阅读此文档。
• **完整命令和标志参考：**请参阅 reference.md，了解用法、参数和所有标志。
• **用法示例：**请参阅 examples.md，获取可复制粘贴的示例和脚本编写模式。
• **部署前防护措施：**请参阅 guardrails.md，了解强制性的部署前安全检查清单（检查 1–4 始终执行；URL 获取任务文件时执行检查 5；多服务清单执行检查 6）。

建议或生成 dibbla 命令时，请参阅参考文档以确保语法准确，并参阅示例了解常见工作流。对于“我的应用是否已准备好用于 Dibbla？”这类问题，请从 platform.md 开始。对于“构建／迭代／调试工作流”这类问题，请从 workflows.md 开始。对于“为平台实现 Go 函数／作业”这类问题，请从 sdk-go.md 开始。