Use when working with the SuperPlane CLI to discover integrations, actions, and triggers, build or troubleshoot apps and canvases, manage secrets, and monitor executions. Covers authentication, list/get commands, interpreting configuration schemas, wiring channels between nodes, resolving integration binding issues, and inspecting runs. Triggers on "superplane", "app", "canvas", "workflow", "CLI", "connect", "integration is required", "execution".
Use when working with the SuperPlane CLI to discover integrations, actions, and triggers, build or troubleshoot apps and canvases, manage secrets, and monitor executions. Covers authentication, list/get commands, interpreting configuration schemas, wiring channels between nodes, resolving integration binding issues, and inspecting runs. Triggers on "superplane", "app", "canvas", "workflow", "CLI", "connect", "integration is required", "execution".
SuperPlane CLI
Operate a SuperPlane instance through the superplane CLI.
Quick Reference
Task
Command
Connect to org
superplane connect <URL> <TOKEN>
Who am I
superplane whoami
Set active app
superplane apps active [app-id]
List/switch contexts
superplane contexts
List apps
superplane apps list
Generate starter YAML
superplane apps canvas init
Generate from template
superplane apps canvas init --template <name>
List canvas templates
superplane apps canvas init --list-templates
Create app
superplane apps create <name> then export, edit, and apply via staging or canvas update --message
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, action names, integration IDs, and config schemas that documentation cannot reliably substitute.
Only after confirming the binary exists should you verify the session:
superplane whoami
Interpret failures carefully:
command not found from whoami still means the CLI is missing.
Authentication, DNS, timeout, or connection errors mean the CLI exists but the current session cannot reach SuperPlane yet. In that case, tell the user the CLI is installed but the session/network/auth is not working, and ask them to connect or allow network access as needed.
Core Workflow
1. Authenticate
Create a service account in the SuperPlane UI, then:
App versions are immutable commits on the main branch. To iterate before committing, use the staging area (like a git working tree). To apply in one step, pass --message on a direct canvas or console write.
Stage, then commit (preferred for iterative edits):
canvas get and console get read the live (committed) app only.
--message is required on canvas update and console set; without it, use staging update and staging commit instead.
staging update maps each --file to a repository path by basename only (canvas.yaml, console.yaml, README.md, etc.).
canvas.yaml staged via staging update must include metadata.id matching the target app.
Reuse staged paths from staging status or agent [Staging Status] context when continuing work.
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 actions # all action types
Narrow to one provider:
superplane index triggers --from github
superplane index actions --from github
Inspect required config fields and payload shapes:
superplane index triggers --name github.onPush
superplane index actions --name semaphore.runWorkflow
List runtime options for integration-resource fields (e.g., repos, projects):
Use superplane integrations list first to find valid integration IDs.
3. Build a Canvas Incrementally
Generate a starter YAML, then create and iterate:
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"
If you create an app from canvas YAML, apps create --canvas-file already sends the full canvas payload. Do not assume a second update is required just to apply the graph:
superplane apps create --canvas-file canvas.yaml
Workflow rules:
superplane apps create --canvas-file canvas.yaml accepts the same resource-style Canvas YAML described in the spec (apiVersion, kind, metadata, spec).
On superplane apps create, canvas layout flags are prefixed with canvas-: --canvas-auto-layout, --canvas-auto-layout-scope, and repeated --canvas-auto-layout-node.
Run a follow-up superplane apps canvas update ... only when you are intentionally changing the canvas after create, for example to apply additional edits from a file that includes metadata.id, or to run auto-layout with different flags than the defaults used on create.
Use apps staging update + apps staging commit for iterative edits, or canvas update / console set with --message to commit directly.
