SuperPlane CLI
Operate a SuperPlane instance through the
superplane
CLI.
Quick Reference
Task
Command
Connect to org
superplane connect
superplane whoami 2. Discover What Exists Run these first to understand what's available: 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: superplane index triggers --from github superplane index components --from github Inspect required config fields and payload shapes: superplane index triggers --name github.onPush superplane index components --name semaphore.runWorkflow List runtime options for integration-resource fields (e.g., repos, projects): superplane integrations list-resources --id < integration-id
--type < type
--parameters key1 = value1,key2 = value2 Use superplane integrations list first to find valid integration IDs. 3. Build a Canvas Incrementally Create a blank canvas, then iterate: superplane canvases create my-canvas
sandbox mode:
superplane canvases update my-canvas --auto-layout horizontal
versioning mode:
superplane canvases update my-canvas --draft --auto-layout horizontal superplane canvases publish my-canvas --title "Initial publish" superplane canvases get my-canvas
canvas.yaml
edit canvas.yaml
sandbox mode:
superplane canvases update --file canvas.yaml --auto-layout horizontal
versioning mode:
superplane canvases update my-canvas --draft --file canvas.yaml --auto-layout horizontal superplane canvases publish my-canvas --title "Update canvas" If you create a canvas from YAML, apply the same rule: superplane canvases create --file canvas.yaml
preferred immediately after create (does not require metadata.id in local YAML):
superplane canvases update < name-or-id
[ --draft ] --auto-layout horizontal
use --file only when your local YAML includes metadata.id:
superplane canvases update --file canvas.yaml --auto-layout horizontal Mode rules: Sandbox mode enabled : superplane canvases update ... updates live directly. Sandbox mode disabled (versioning enabled) : superplane canvases update ... must include --draft ; then run superplane canvases publish ... to apply live. Live updates without draft/version are blocked when sandbox mode is disabled. See Canvas YAML Spec for the full format. Auto Layout via CLI Use canvases update with auto-layout flags: Default agent behavior: Always include --auto-layout horizontal on superplane canvases update . Do not wait for the user to explicitly ask for auto layout. In versioning mode, include --draft on update and follow with superplane canvases publish ... .
connected component around one seed node (recommended default for existing canvases)
superplane canvases update < name-or-id
[ --draft ] \ --auto-layout horizontal \ --auto-layout-scope connected-component \ --auto-layout-node < node-id
exact node set only (best when the user selected nodes)
superplane canvases update < name-or-id
[ --draft ] \ --auto-layout horizontal \ --auto-layout-scope exact-set \ --auto-layout-node < node-a
\ --auto-layout-node < node-b
full canvas (use sparingly; see policy below)
superplane canvases update < name-or-id
[ --draft ] --auto-layout horizontal Rules and behavior: --auto-layout is required when using --auto-layout-scope or --auto-layout-node . --draft is required when versioning is enabled (sandbox disabled). Supported algorithm: horizontal . Supported scopes: full-canvas , connected-component , exact-set . Default scope behavior: If no seed nodes are provided: behaves like full-canvas . If seed nodes are provided and scope omitted: behaves like connected-component . Recommended policy for agents: Prefer connected-component for existing/disconnected canvases. Prefer exact-set when the user selected specific nodes. Use full-canvas only when creating from scratch, when the graph is one connected component, or when the user explicitly asks for full-canvas layout. Scope selection default: If a changed/selected node ID is known, use connected-component + --auto-layout-node . If a set of changed node IDs is known, use exact-set + repeated --auto-layout-node . If no node IDs are available, use full-canvas . Positioning is anchor-preserving: the laid-out region keeps its top-left anchor relative to current canvas coordinates to avoid large jumps. 4. Manage Secrets superplane secrets create --file secret.yaml superplane secrets list superplane secrets update --file secret.yaml superplane secrets delete < name_or_id
- Monitor Runs superplane events list --canvas-id < id
superplane events list-executions --canvas-id < id
--event-id < eid
- Troubleshooting Checklist Run after every canvas update: 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) Resolving "integration is required" When a field type is integration-resource (like repository or project ), the node needs a connected integration instance. superplane integrations list — confirm the provider is connected superplane integrations get
— inspect the connection Add integration.id to the node in the canvas YAML superplane integrations list-resources --id --type — find valid resource values superplane canvases update [--draft] --file canvas.yaml — apply the fix If --draft was used: superplane canvases publish --title "Fix integration binding" superplane canvases get — verify errors are cleared When to Use Other Skills Need Use Skill Design a canvas from requirements superplane-canvas-builder Debug a failed execution 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 References Canvas YAML Spec — Full YAML format with examples