superplane-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SuperPlane CLI

Operate a SuperPlane instance through the

superplane

CLI.

通过

superplane

CLI操作SuperPlane实例。

Quick Reference

快速参考

Task	Command
Connect to org	`superplane connect <URL> <TOKEN>`
Who am I	`superplane whoami`
List/switch contexts	`superplane contexts`
List canvases	`superplane canvases list`
Create canvas	`superplane canvases create <name>`
Create canvas from YAML	`superplane canvases create --file canvas.yaml`
Export canvas	`superplane canvases get <name>`
Update canvas	`superplane canvases update --file canvas.yaml`
List available providers	`superplane index integrations`
Describe a provider	`superplane index integrations --name github`
List connected integrations	`superplane integrations list`
Inspect connected integration	`superplane integrations get <id>`
List integration resources	`superplane integrations list-resources --id <id> --type <type>`
List components	`superplane index components`
Components from provider	`superplane index components --from github`
Describe a component	`superplane index components --name semaphore.runWorkflow`
List triggers	`superplane index triggers`
Triggers from provider	`superplane index triggers --from github`
Describe a trigger	`superplane index triggers --name github.onPush`
List secrets	`superplane secrets list`
Create secret	`superplane secrets create --file secret.yaml`
List events	`superplane events list --canvas-id <id>`
Trace event executions	`superplane events list-executions --canvas-id <id> --event-id <eid>`
List node executions	`superplane executions list --canvas-id <id> --node-id <nid>`
Cancel execution	`superplane executions cancel --canvas-id <id> --execution-id <eid>`

任务	命令
连接到组织	`superplane connect <URL> <TOKEN>`
查看当前用户	`superplane whoami`
列出/切换上下文	`superplane contexts`
列出Canvas	`superplane canvases list`
创建Canvas	`superplane canvases create <name>`
从YAML创建Canvas	`superplane canvases create --file canvas.yaml`
导出Canvas	`superplane canvases get <name>`
更新Canvas	`superplane canvases update --file canvas.yaml`
列出可用提供商	`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 components`
列出某提供商的组件	`superplane index components --from github`
描述某一组件	`superplane index components --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 events list --canvas-id <id>`
追踪事件执行记录	`superplane events list-executions --canvas-id <id> --event-id <eid>`
列出节点执行记录	`superplane executions list --canvas-id <id> --node-id <nid>`
取消执行	`superplane executions cancel --canvas-id <id> --execution-id <eid>`

Verify CLI Is Installed

验证CLI是否已安装

Before any CLI operation, confirm the CLI is available:

bash

superplane whoami

If this returns

command not found

, the CLI is not installed. Stop and tell the user:

The SuperPlane CLI is not installed. Install it from https://docs.superplane.com/installation/cli and then re-run this task.

Do not attempt to install the CLI on behalf of the user. Do not continue with doc-based guesswork — the CLI provides exact trigger names, component names, integration IDs, and config schemas that documentation cannot reliably substitute.

进行任何CLI操作前，请确认CLI已可用：

bash

superplane whoami

如果返回

command not found

，说明CLI未安装。请告知用户：

SuperPlane CLI未安装，请从https://docs.superplane.com/installation/cli下载安装后再执行此任务。

请勿尝试代用户安装CLI，也不要仅凭文档猜测操作——CLI提供了文档无法可靠替代的准确触发器名称、组件名称、集成ID和配置schema。

Core Workflow

核心工作流

1. Authenticate

1. 身份验证

Create a service account in the SuperPlane UI, then:

bash

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

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

bash

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

2. Discover What Exists

2. 查看可用资源

Run these first to understand what's available:

bash

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

Narrow to one provider:

bash

superplane index triggers --from github
superplane index components --from github

Inspect required config fields and payload shapes:

bash

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

List runtime options for

integration-resource

fields (e.g., repos, projects):

bash

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

Use

superplane integrations list

first to find valid integration IDs.

先运行以下命令了解当前可用的资源：

bash

superplane index integrations          # 可用提供商
superplane integrations list           # 当前组织已连接的实例
superplane index triggers              # 所有触发器类型
superplane index components            # 所有组件类型

筛选单个提供商的资源：

bash

superplane index triggers --from github
superplane index components --from github

查看必填配置字段和负载结构：

bash

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

列出

integration-resource

字段的运行时选项（如仓库、项目）：

bash

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

请先执行

superplane integrations list

获取有效的集成ID。

3. Build a Canvas Incrementally

3. 逐步构建Canvas

Create a blank canvas, then iterate:

bash

superplane canvases create my-canvas
superplane canvases get my-canvas > canvas.yaml

创建空白Canvas后逐步迭代：

bash

superplane canvases create my-canvas
superplane canvases get my-canvas > canvas.yaml

edit canvas.yaml

编辑canvas.yaml

superplane canvases update --file canvas.yaml


See [Canvas YAML Spec](references/canvas-yaml-spec.md) for the full format.

superplane canvases update --file canvas.yaml


完整格式请参考[Canvas YAML 规范](references/canvas-yaml-spec.md)。

4. Manage Secrets

4. 管理密钥

bash

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

bash

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

5. Monitor Runs

5. 监控运行状态

bash

superplane events list --canvas-id <id>
superplane events list-executions --canvas-id <id> --event-id <eid>

bash

superplane events list --canvas-id <id>
superplane events list-executions --canvas-id <id> --event-id <eid>

6. Troubleshooting Checklist

6. 排查问题清单

Run after every canvas update:

bash

superplane canvases get <name>

Check:

All required
```
configuration
```
fields are present
Edges use the correct output channels
No node
```
errorMessage
```
remains (especially "integration is required")
No
```
warningMessage
```
about duplicate names
Expressions reference existing node names (case-sensitive)

每次更新Canvas后执行：

bash

superplane canvases get <name>

检查以下内容：

所有必填
```
configuration
```
字段已填写
节点间连线使用正确的输出通道
没有节点残留
```
errorMessage
```
（尤其是“integration is required”）
没有关于名称重复的
```
warningMessage
```
表达式引用的节点名称存在且大小写正确

Resolving "integration is required"

解决“integration is required”问题

When a field type is

integration-resource

(like

repository

project

), the node needs a connected integration instance.

```
superplane integrations list
```
— confirm the provider is connected
```
superplane integrations get <id>
```
— inspect the connection
Add
```
integration.id
```
to the node in the canvas YAML

superplane integrations list-resources --id <id> --type <type>

— find valid resource values

superplane canvases update --file canvas.yaml

— apply the fix

```
superplane canvases get <name>
```
— verify errors are cleared

当字段类型为

integration-resource

（如

repository

或

project

）时，节点需要已连接的集成实例。

执行
```
superplane integrations list
```
——确认该提供商已连接
执行
```
superplane integrations get <id>
```
——检查连接状态
在Canvas YAML中为节点添加
```
integration.id
```
字段

执行

superplane integrations list-resources --id <id> --type <type>

——查找有效的资源值

执行

superplane canvases update --file canvas.yaml

——应用修复

执行
```
superplane canvases get <name>
```
——验证错误已清除

When to Use Other Skills

何时使用其他技能

Need	Use Skill
Design a canvas from requirements	superplane-canvas-builder
Debug a failed execution	superplane-monitor

需求	使用对应技能
根据需求设计Canvas	superplane-canvas-builder
排查执行失败问题	superplane-monitor

Documentation

文档资源

For agents that can fetch URLs, the full SuperPlane docs are available in LLM-friendly format:

Compact index: https://docs.superplane.com/llms.txt
Full content: https://docs.superplane.com/llms-full.txt

对于可获取URL的Agent，完整的SuperPlane文档提供了LLM友好格式：

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

References

参考资料

Canvas YAML Spec — Full YAML format with examples

Canvas YAML 规范——包含示例的完整YAML格式说明