superplane-cli

SuperPlane CLI

通过 superplane CLI 操作 SuperPlane 实例。

快速参考

任务	命令
连接到组织	superplane connect <URL> <TOKEN>
我是谁	superplane whoami
设置活动应用	superplane apps active [app-id]
列出/切换上下文	superplane contexts
列出应用	superplane apps list
生成入门 YAML	superplane apps canvas init
根据模板生成	superplane apps canvas init --template <name>
列出画布模板	superplane apps canvas init --list-templates
创建应用	superplane apps create <name>，然后导出、编辑，并通过暂存或 canvas update --message 应用
根据画布 YAML 创建应用	superplane apps create --canvas-file canvas.yaml
使用布局标志创建应用	superplane apps create --canvas-file canvas.yaml --canvas-auto-layout horizontal
暂存状态	superplane apps staging status [name-or-id]
暂存文件	superplane apps staging update --file canvas.yaml [--file console.yaml ...]
提交暂存更改	superplane apps staging commit --message "..."
导出画布	superplane apps canvas get <name-or-id> -o yaml
更新画布（直接提交）	superplane apps canvas update -f canvas.yaml --message "..."
自动布局整个画布	superplane apps canvas update -f canvas.yaml --message "..." --auto-layout horizontal
自动布局已连接的子图	superplane apps canvas update -f canvas.yaml --message "..." --auto-layout horizontal --auto-layout-scope connected-component --auto-layout-node <node-id>
导出控制台	superplane apps console get <name-or-id> -o yaml > console.yaml
更新控制台（直接提交）	superplane apps console set -f console.yaml --message "..."
列出应用文件	superplane apps files tree <name-or-id>
显示应用文件	superplane apps files show <path> <name-or-id>
列出可用提供方	superplane index integrations
描述提供方	superplane index integrations --name github
列出已连接的集成	superplane integrations list
检查已连接的集成	superplane integrations get <id>
列出集成资源	superplane integrations list-resources --id <id> --type <type>
列出操作	superplane index actions
列出来自提供方的操作	superplane index actions --from github
描述操作	superplane index actions --name semaphore.runWorkflow
列出触发器	superplane index triggers
列出来自提供方的触发器	superplane index triggers --from github
描述触发器	superplane index triggers --name github.onPush
列出密钥	superplane secrets list
创建密钥	superplane secrets create --file secret.yaml
列出运行	superplane runs list --app-id <id>
描述运行	superplane runs describe <run-id> --app-id <id>
列出节点执行	superplane executions list --app-id <id> --node-id <nid>
取消执行	superplane executions cancel --app-id <id> --execution-id <eid>

验证 CLI 是否已安装

执行任何 CLI 操作前，请确认 CLI 二进制文件可用，且无需网络访问：

command -v superplane

如果没有输出路径，则表示未安装 CLI。请停止并告知用户：

未安装 SuperPlane CLI。请从 https://docs.superplane.com/installation/cli 安装，然后重新运行此任务。

不要代替用户安装 CLI。不要继续根据文档猜测——CLI 会提供准确的触发器名称、操作名称、集成 ID 和配置架构，文档无法可靠地替代这些信息。

只有确认二进制文件存在后，才应验证会话：

superplane whoami

仔细判断失败原因：

• whoami 返回 command not found，仍表示 CLI 缺失。
• 身份验证、DNS、超时或连接错误表示 CLI 存在，但当前会话尚无法连接 SuperPlane。此时请告知用户 CLI 已安装，但会话、网络或身份验证未正常工作，并根据需要请求用户连接或允许网络访问。

核心工作流

1. 身份验证

在 SuperPlane UI 中创建服务账户，然后：

superplane connect https://superplane.example.com <API_TOKEN>
superplane whoami

1b. 暂存与提交

应用版本是主分支上的不可变提交。提交前如需迭代，请使用暂存区（类似 Git 工作树）。若要一步完成，可在直接写入画布或控制台时传入 --message。

先暂存，再提交（迭代编辑时优先使用）：

superplane apps staging status [name-or-id]

superplane apps staging update \
  --file canvas.yaml \
  --file console.yaml \
  --file README.md

superplane apps staging commit --message "Commit message"

直接提交（在一条命令中暂存并提交）：

superplane apps canvas update -f canvas.yaml --message "Commit message"
superplane apps console set -f console.yaml --message "Commit message"

规则：

• canvas get 和 console get 只读取应用的当前线上版本（已提交版本）。
• canvas update 和 console set 必须指定 --message；如果不指定，请改用 staging update 和 staging commit。
• staging update 仅根据基名将每个 --file 映射到仓库路径（例如 canvas.yaml、console.yaml、README.md 等）。
• 通过 staging update 暂存的 canvas.yaml 必须包含与目标应用匹配的 metadata.id。
• 继续工作时，请复用 staging status 或 Agent [Staging Status] 上下文中的已暂存路径。

2. 了解现有内容

首先运行以下命令，了解可用内容：

superplane index integrations          # available providers
superplane integrations list           # connected instances in this org
superplane index triggers              # all trigger types
superplane index actions            # all action types

缩小范围，仅查看一个提供方：

superplane index triggers --from github
superplane index actions --from github

查看必需的配置字段和有效负载格式：

superplane index triggers --name github.onPush
superplane index actions --name semaphore.runWorkflow

列出 integration-resource 字段的运行时选项（例如仓库、项目）：

superplane integrations list-resources --id <integration-id> --type <type> --parameters key1=value1,key2=value2

先使用 superplane integrations list 查找有效的集成 ID。

3. 逐步构建画布

生成起始 YAML，然后创建并迭代：

superplane apps canvas init --output-file canvas.yaml
# or start from a template:
superplane apps canvas init --template health-check-monitor --output-file canvas.yaml
# edit canvas.yaml, then create:
superplane apps create --canvas-file canvas.yaml
# or create a blank canvas and iterate:
superplane apps create my-canvas
superplane apps canvas get my-canvas -o yaml > canvas.yaml
# edit canvas.yaml (ensure metadata.id is set)
superplane apps staging update --file canvas.yaml
superplane apps staging commit --message "Initial canvas"
# or commit directly:
superplane apps canvas update -f canvas.yaml --message "Initial canvas"

如果根据画布 YAML 创建应用，apps create --canvas-file 已会发送完整的画布有效负载。不要以为只为应用图表就需要再执行一次更新：

superplane apps create --canvas-file canvas.yaml

工作流规则：

• superplane apps create --canvas-file canvas.yaml 接受规范中描述的相同资源样式 Canvas YAML（apiVersion、kind、metadata、spec）。
• 在 superplane apps create 中，画布布局标志以 canvas- 为前缀：--canvas-auto-layout、--canvas-auto-layout-scope 和可重复使用的 --canvas-auto-layout-node。
• 只有在有意于创建后更改画布时，才运行后续的 superplane apps canvas update ...，例如应用包含 metadata.id 的文件中的其他编辑，或使用与创建时默认值不同的标志执行自动布局。
• 迭代编辑时，请使用 apps staging update 和 apps staging commit；如需直接提交，请使用带有 --message 的 canvas update / console set。

完整格式请参阅 Canvas YAML 规范。

通过 CLI 使用 Console YAML

使用 superplane apps console 读取和替换应用的 Console：面板及网格布局。

命令：

# With an explicit app name or id
superplane apps console get <name-or-id>
superplane apps console get <name-or-id> -o yaml > console.yaml
superplane apps console set -f console.yaml --message "Update console"
superplane apps console set <name-or-id> -f console.yaml --message "Update console"
superplane apps console set <name-or-id> -f - --message "Update console" < console.yaml

# Stage console changes without committing immediately
superplane apps staging update --file console.yaml
superplane apps staging commit --message "Update console"

# With the active app from `superplane apps active`
superplane apps console get
superplane apps console set -f console.yaml --message "Update console"

行为：

• get 读取当前已提交的 Console。
• set --message 替换面板和布局，并立即提交。
• 若要暂存 Console 编辑而不提交，请使用 staging update --file console.yaml，然后运行 staging commit。
• Console 导入会替换全部内容：YAML 将替换所有面板和布局条目。
• 导出用于编辑或导入的文件时，请使用 -o yaml。

请参阅 Console YAML 规范，了解稳定的 YAML 外层结构、布局字段，以及当前 Widget 详情的位置。

通过 CLI 自动布局

使用带自动布局标志的 apps canvas update：

Agent 的默认行为：

• 如果未提供自动布局标志，运行 superplane apps canvas update 时默认应用自动布局。
• 需要明确控制范围或种子节点时，请使用 --auto-layout 标志。
• 直接运行 canvas update 命令时，请附带 --message，或使用 staging update + staging commit。

# connected component around one seed node (recommended default for existing canvases)
superplane apps canvas update \
  -f canvas.yaml \
  --message "Re-layout canvas" \
  --auto-layout horizontal \
  --auto-layout-scope connected-component \
  --auto-layout-node <node-id>

# full canvas (use sparingly; see policy below)
superplane apps canvas update -f canvas.yaml --message "Re-layout canvas" --auto-layout horizontal

规则和行为：

• 使用 --auto-layout-scope 或 --auto-layout-node 时，必须指定 --auto-layout。
• 直接运行 canvas update 命令时，必须指定 --message。
• 支持的算法：horizontal。
• 支持的范围：full-canvas、connected-component。
• 默认范围行为：
  • 未提供种子节点时：表现为 full-canvas。
  • 提供了种子节点但未指定范围时：表现为 connected-component。
• 对 Agent 的推荐策略：
  • 对已有画布或不连通的画布，优先使用 connected-component。
  • 仅在从头创建、图只有一个连通分量，或用户明确要求完整画布布局时，使用 full-canvas。
• 范围选择的默认规则：
  • 如果已知发生变更或选中的节点 ID，请使用 connected-component + --auto-layout-node。
  • 如果已知一组发生变更的节点 ID，请使用 connected-component + 重复指定 --auto-layout-node。
  • 如果没有可用的节点 ID，请使用 full-canvas。
• 定位会保留锚点：布局区域会相对于当前画布坐标保留左上角锚点，以避免大幅跳动。

4. 管理密钥

superplane secrets create --file secret.yaml
superplane secrets list
superplane secrets update --file secret.yaml
superplane secrets delete <name_or_id>

5. 监控运行

superplane runs list --app-id <id>
superplane runs describe <run-id> --app-id <id>

6. 故障排查清单

每次画布更新后运行：

superplane apps canvas get <name>

检查：

• 所有必需的 configuration 字段均已填写
• 边使用了正确的输出通道
• 没有节点遗留 errorMessage（尤其是 "integration is required"）
• 没有关于名称重复的 warningMessage
• 表达式引用了现有节点名称（区分大小写）

解决“integration is required”问题

当字段类型为 integration-resource（例如 repository 或 project）时，节点需要连接一个集成实例。

1. superplane integrations list — 确认提供方已连接
2. superplane integrations get <id> — 检查连接
3. 在画布 YAML 的节点中添加 integration.id
4. superplane integrations list-resources --id <id> --type <type> — 查找有效的资源值
5. superplane apps canvas update -f canvas.yaml --message "Fix integration" — 应用修复（或使用 staging update + staging commit）
6. superplane apps canvas get <name-or-id> — 验证错误已清除

何时使用其他技能

需求	使用技能
根据需求设计画布	superplane-app-builder
调试执行失败	superplane-monitor

文档

对于能够获取 URL 的 Agent，完整的 SuperPlane 文档提供了便于大模型使用的格式：

• 精简索引：https://docs.superplane.com/llms.txt
• 完整内容：https://docs.superplane.com/llms-full.txt

参考资料

• Canvas YAML 规范 — 完整 YAML 格式及示例
• Console YAML 规范 — 稳定的 Console YAML 外层结构和布局格式