camunda-c8ctl

Camunda c8ctl CLI

安装并使用 c8ctl——Camunda 8.8+ 的轻量级依赖命令行工具，用于连接集群、部署资源和管理流程自动化。c8ctl 是其他 camunda-* 技能（camunda-bpmn、camunda-connectors、camunda-feel、camunda-process-mgmt、camunda-ai-agents）的基础。

前置条件

• Node.js ≥ 22.18.0（原生 TypeScript 支持所需）——在本地安装请参阅 camunda-development

交叉引用

• camunda-bpmn：使用 c8ctl bpmn lint
• camunda-connectors：使用 c8ctl element-template search/info/get-properties/apply
• camunda-feel：使用 c8ctl feel evaluate
• camunda-process-mgmt：使用 c8ctl deploy、c8ctl run、c8ctl watch、c8ctl list pi、c8ctl search inc、c8ctl complete ut、c8ctl resolve inc 等
• camunda-ai-agents：使用 c8ctl element-template search/apply 应用 AI Agent 连接器模板

说明

快速就绪检查（入门）

当用户刚开始使用 c8ctl，且需要在深入配置前确认机器已准备就绪时，请使用此快速检查：

# Required runtime
node --version 2>/dev/null || echo "NOT FOUND"

# Required CLI
c8ctl --version 2>/dev/null || echo "NOT FOUND"

# Required default plugins for camunda-* skills
c8ctl bpmn --help >/dev/null 2>&1 && echo "bpmn: OK" || echo "bpmn: MISSING"
c8ctl element-template --help >/dev/null 2>&1 && echo "element-template: OK" || echo "element-template: MISSING"
c8ctl feel --help >/dev/null 2>&1 && echo "feel: OK" || echo "feel: MISSING"

# Optional: check current active profile
c8ctl which profile 2>/dev/null || echo "no active profile"

# Optional: check whether a local c8run cluster is already running
c8ctl cluster status 2>/dev/null || echo "local cluster: not running"

• Node.js 和 c8ctl 均为必需项。Node 必须为 ≥ 22.18.0。如果缺少任一项（或 Node 版本较旧），请先安装或升级，再继续。
• 如果缺少任何默认插件，说明已安装的 c8ctl 版本早于 3.0.0。升级前请先征得用户确认——不要未经询问就运行安装命令——然后运行 npm install -g @camunda8/cli。
• 缺少配置文件或本地集群并非错误，只表示配置文件或集群仍待设置。

安装

通过 npm 全局安装 c8ctl。其他 camunda-* 技能依赖 bpmn、element-template 和 feel 插件，这些插件要求 c8ctl ≥ 3.0.0：

npm install -g @camunda8/cli

安装后即可使用 c8ctl 和更短的别名 c8。为清晰起见，其他 camunda-* 技能使用 c8ctl 形式。

验证：

c8ctl --version
c8ctl help

验证默认插件

其他 camunda-* 技能依赖随 c8ctl ≥ 3.0.0 附带的三个插件：bpmn、element-template 和 feel。请验证每个插件是否可用：

c8ctl bpmn --help              # camunda-bpmn
c8ctl element-template --help  # camunda-connectors, camunda-ai-agents
c8ctl feel --help              # camunda-feel

如果任何命令以非零状态退出，说明已安装的 c8ctl 版本早于 3.0.0，且缺少这些插件。安装前请先征得用户确认——不要未经询问就运行安装命令——然后运行：

npm install -g @camunda8/cli

选择集群

c8ctl 需要连接一个集群。配置配置文件之前，请询问用户要使用哪个集群：

1. 本地开发集群（c8run）——新项目、实验和本地迭代的推荐默认选项。c8ctl 可以为你下载、启动和管理 c8run。请参阅下文的“本地集群”。
2. Camunda 8 SaaS——托管在 Camunda 云中的集群。用户需提供客户端凭据。
3. 自我管理——用户自行运行的 Camunda 8 集群（Kubernetes、Docker Compose 等）。用户需提供基础 URL，以及（如已启用安全保护）OAuth 凭据。
4. Camunda Modeler 配置文件——如果用户安装了 Camunda Desktop Modeler 并配置了连接，c8ctl 会自动导入这些配置文件。使用 modeler: 前缀引用它们（例如 modeler:Local Dev）。

如果用户尚未决定且正在进行本地开发，建议使用本地 c8run——除了运行 c8ctl cluster start 外，无需任何设置成本。

本地集群（c8ctl cluster）

c8ctl 内置了默认的 cluster 插件，用于封装 c8run。它会为你下载、启动和停止本地 Camunda 8 集群。

启动新的本地集群前，请先快速检查，避免不必要的重启，并尽早发现 Java/运行时问题：

# Is a local cluster already responding?
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/v2/topology

# Is Java available (c8run needs JRE 21+)?
java -version

• 如果拓扑检查返回 200，说明本地集群已在运行；继续执行你的任务即可。
• 如果未安装 Java，或版本过旧，请先安装 JRE/JDK 21+。
• 在某些非交互式 Shell 中，java -version 可以正常运行，但 JAVA_HOME 仍未设置（使用 asdf/mise shim 时很常见）。如果 Java 已安装，但启动失败，请在运行 c8ctl cluster start 前明确设置 JAVA_HOME：

export JAVA_HOME="$(asdf where java 2>/dev/null || mise where java 2>/dev/null)"

示例：

# Start the latest stable release (downloads on first run)
c8ctl cluster start

# Start a specific minor version (rolling release — auto-updates patches)
c8ctl cluster start 8.9

# Start a specific full version
c8ctl cluster start 8.9.0-alpha5

# Use the alpha alias for the latest pre-release
c8ctl cluster start alpha

# Check status (running? what version? connection details?)
c8ctl cluster status

# Verify the cluster is responding after start
c8ctl get topology

# Stream logs
c8ctl cluster logs

# Stop the cluster
c8ctl cluster stop

集群默认运行在 http://localhost:8080。如果未配置配置文件，c8ctl 会回退到 http://localhost:8080/v2，因此大多数命令都可以直接对刚启动的本地集群运行。

完整的 c8ctl 集群命令参考（list、install、list-remote、delete、缓存位置、版本别名）请参阅 references/local-cluster.md。

连接：配置文件

配置文件用于保存集群连接详情。c8ctl 自带的 local 配置文件已指向 http://localhost:8080/v2，因此使用本地 c8run 无需进行设置——只需传入 --profile=local。Camunda Desktop Modeler 配置文件会自动导入，并添加 modeler: 前缀。

对于采用 OAuth 保护的集群（SaaS 或 Self-Managed），配置文件设置是一次性人工任务——有关 add profile 标志和凭据处理方式，请参阅 c8ctl 文档。不要主动运行 add profile；请让用户先配置好配置文件，再使用此技能。

使用已配置的配置文件：

# Switch the active profile
c8ctl use profile prod

# Show the current active profile
c8ctl which profile

# List all profiles (includes Camunda Modeler profiles with `modeler:` prefix)
c8ctl list profiles

# Use a Modeler profile
c8ctl use profile "modeler:Local Dev"

# One-off override for a single command (active profile unchanged)
c8ctl list pi --profile=staging

有关多租户、凭据解析顺序和 Modeler 集成的详情，请参阅 references/profiles.md。

安全：选择正确的集群

默认情况下，c8ctl 会通过当前全局激活的配置文件解析集群连接。这有风险：当前激活的配置文件可能仍指向之前会话中的生产或预发布环境，而涉及集群的命令会静默地对其执行操作。

涉及集群的命令始终要明确传入 --profile=<name>，尤其是会修改数据的命令（deploy、run、cancel、resolve、complete、publish、watch）。只读命令（get、list、search、feel evaluate）风险较低，但遵守同样的规范可以让命令记录可审计，并避免因忘记执行 c8ctl use profile prod 而导致后续命令悄悄指向错误环境。

会话开始时：在执行任何涉及集群的操作前，运行 c8ctl which profile 并与用户确认。如果当前激活的配置文件名称表明它指向共享环境（prod、production、staging、live、以 saas 开头的名称、客户名称），请先征求用户同意——不要假设该配置文件适用于当前工作。

对于新的本地开发项目，请使用 --profile=local，不要沿用之前项目留下的激活配置文件。

c8ctl cluster start/stop/status/logs 不受此影响：这些命令直接操作本地 c8run 进程，不通过配置文件执行。

使用 CLI

c8ctl 有两种命令形式：

• 核心 API 命令遵循 <verb> <resource> 格式——list pi、get inc <key>、complete ut <key>。资源有简短别名（pi = process-instance，pd = process-definition，ut = user-task，inc = incident，msg = message）。
• 插件命令遵循 <plugin> <subcommand> 格式——cluster start、element-template apply、bpmn lint、feel evaluate。插件名称是第一个词元；子命令由插件定义。

快速概览（为简洁起见，示例省略了 --profile=<name>——请按照上面的安全规则明确传入该参数）：

# Inspect the cluster
c8ctl get topology
c8ctl list pd                                  # deployed process definitions
c8ctl list pi                                  # running process instances
c8ctl search inc --state=ACTIVE                # active incidents

# Develop / deploy
c8ctl deploy ./process.bpmn                    # deploy a single resource
c8ctl deploy ./my-project                      # deploy a directory (supports _bb-* and .process-application)
c8ctl run ./order.bpmn --variables='{"orderId":"42"}'   # deploy + start in one step
c8ctl watch                                    # auto-redeploy on file save
c8ctl await pi --id=order-process              # block until completion

# Operate
c8ctl get pi 2251799813685249 --variables      # inspect an instance
c8ctl complete ut 2251799813685250 --variables='{"approved":true}'
c8ctl publish msg payment-received --correlationKey=order-42
c8ctl resolve inc 2251799813685251
c8ctl cancel pi 2251799813685249

完整的动词/资源对应表、插件命令和特定资源标志请参阅 references/command-reference.md。

输出模式（适用于 AI / 脚本）

对于 AI 驱动和脚本化使用，按命令请求 JSON，并结合 --fields 获取稳定的结构化输出：

# Per-command JSON (deterministic, does not mutate session state)
c8ctl list pd --json --fields=key,bpmnProcessId,version,name

# Preview an API request without executing it
c8ctl deploy ./process.bpmn --dry-run

# Pagination / sort (on list and search commands)
c8ctl list pi --limit=50 --sortBy=startDate --desc

优先使用每次调用时指定的 --json 标志，而不是 c8ctl output json——后者会修改 session.json，并影响其他工具和会话。C8CTL_OUTPUT_MODE=json 环境变量也适用于当前 shell，但在大多数 Agent 框架中，shell 状态不会跨独立的工具调用持久保留，因此某一步中的 export 不会延续到下一步。需要结构化输出时，始终在命令本身上指定 --json。

插件

默认插件（cluster、bpmn、feel、element-template）已预加载到 c8ctl 中，无需安装。使用 c8ctl list plugins 查看。有关安装或管理其他插件的信息，请参阅 c8ctl 文档。

不要主动运行 c8ctl load plugin——插件代码会在 c8ctl 运行时中运行，并拥有对当前活动配置的完全访问权限。请让用户自行安装插件。

故障排除

• c8ctl: command not found（或 c8: command not found）——npm 的全局 bin 目录不在 PATH 中。运行 npm config get prefix，并将 <prefix>/bin 添加到 PATH。
• Node.js version too old——c8ctl 需要 Node ≥ 22.18.0 才能支持原生 TypeScript。使用 nvm 或 asdf 升级。
• 本地集群无法启动——检查 c8ctl cluster status 和 c8ctl cluster logs。常见原因：端口 8080 已被占用、未安装 Java（c8run 需要 JRE 21+）、二进制文件下载所需磁盘空间不足。
• c8ctl cluster start 报告“port 8080 in use”，但端口实际空闲（lsof/nc 未显示任何监听项）——限制套接字绑定的沙盒环境（某些编码 Agent 框架、受限容器模式、macOS App Sandbox）会出现此情况。请让用户在主机终端中（沙盒外）直接运行 c8ctl cluster start。
• c8ctl 无法写入其默认数据目录（沙盒 Agent、受限文件系统）——调用 c8ctl 前，设置 C8CTL_DATA_DIR=<writable-path>。
• 连接 SaaS 时出现 OAuth 错误——确认配置文件配置正确。SaaS 的集群 URL 是 Zeebe REST 地址，而不是仪表板 URL。有关 OAuth 标志，请参阅 c8ctl 文档。

参考资料

如需详细参考资料，请阅读 references/ 中的内容：

• local-cluster.md — 完整的 c8ctl cluster 命令参考、版本别名（stable/alpha/rolling）、缓存位置、connector-secrets 引导流程
• profiles.md — 配置文件管理、OAuth 标志、Modeler 集成、租户解析、凭据解析顺序、环境变量
• command-reference.md — 动词/资源矩阵、插件命令格式、资源别名、搜索标志、全局标志、默认插件