SuperPlane CLI

Use the SuperPlane CLI to connect to your organization and manage workflows from your terminal.

AI agents

For agent-first usage of the CLI (auth, canvases, secrets, runs), use the SuperPlane skills repository and install the superplane-cli skill: npx skills add superplanehq/skills --skill superplane-cli.

Installation

Download the latest binary for your operating system and architecture:

curl -L https://install.superplane.com/superplane-cli-darwin-arm64 -o superplane
chmod +x superplane
sudo mv superplane /usr/local/bin/superplane

Or download a specific version:

curl -L https://install.superplane.com/v0.1.6/superplane-cli-darwin-arm64 -o superplane
chmod +x superplane
sudo mv superplane /usr/local/bin/superplane

Authentication

The SuperPlane CLI uses API tokens for authentication. You can use:

• Service account token (recommended for scripts and integrations): see Service Accounts.
• Personal token (tied to your user): go to Profile > API token in the SuperPlane UI.

Connect

Connect to a SuperPlane organization:

superplane connect <SUPERPLANE_URL> <API_TOKEN>

Show your identity for the current context:

superplane whoami

Multiple organizations

You can connect to multiple SuperPlane organizations at the same. Each connection will become a CLI context. You can list contexts and switch interactively:

superplane contexts

Switch directly with a context selector:

superplane contexts <SUPERPLANE_URL>/<ORGANIZATION_NAME>

Output formats

All commands support --output (or -o) to choose the response format.

Possible values are:

• text (default)
• json
• yaml

Examples:

superplane canvases list --output text
superplane canvases list -o json
superplane canvases get <canvas_name_or_id> -o yaml

Managing canvases

Create a canvas

superplane canvases create <canvas_name>

You can also create from a file:

superplane canvases create --file my_canvas.yaml

Describe a canvas

superplane canvases get <canvas_name_or_id>

List canvases

superplane canvases list

Set active canvas

Since you’re mostly working on a single canvas at a time, you can set the active canvas with:

superplane canvases active <canvas_id>

This allows you to not have to specify --canvas-id on commands that require it.

Update a canvas

Export the existing canvas, edit it, then apply your changes:

superplane canvases get <canvas_name> > my_canvas.yaml
# update your YAML to reflect the changes you want to make
superplane canvases update -f my_canvas.yaml

superplane canvases update applies auto layout by default. Use explicit auto-layout flags only when you need to control scope or seed nodes.

Check whether versioning is enabled

Check the canvas metadata directly:

superplane canvases get <canvas_name_or_id> -o json | jq '.metadata.versioningEnabled'

Expected values:

• true: effective versioning enabled for this canvas. Use superplane canvases update --draft -f ..., then create a change request.
• false: effective versioning disabled for this canvas. Use superplane canvases update -f ... (no --draft), and do not use change-request commands.

Quick behavior-based check:

• If superplane canvases update --draft ... returns --draft cannot be used when effective canvas versioning is disabled, versioning is disabled for this canvas.
• If superplane canvases update ... (without --draft) returns effective canvas versioning is enabled for this canvas; use --draft, versioning is enabled for this canvas.
• If superplane canvases change-requests create ... returns effective canvas versioning is disabled for this canvas, versioning is disabled for this canvas.

Canvas versioning (drafts and change requests)

Canvas update behavior depends on effective canvas mode:

• Organization-level versioning ON forces effective versioning ON for all canvases.

• Organization-level versioning OFF allows each canvas to toggle versioning independently.

• If canvas versioning is enabled, superplane canvases update must use --draft.

• If canvas versioning is disabled, do not use --draft; updates apply directly and change requests are not available.

Draft workflow (versioning enabled):

# Write changes to your draft version
superplane canvases update --draft -f my_canvas.yaml

# Create a change request from your current draft version
superplane canvases change-requests create <canvas_name_or_id>

You can include optional metadata when creating the change request:

superplane canvases change-requests create <canvas_name_or_id> \
  --title "Add incident routing path" \
  --description "Introduces PagerDuty fallback and Slack notification branch."

If you already set an active canvas with superplane canvases active <canvas_id>, you can omit <canvas_name_or_id> in superplane canvases change-requests create.

Change request review actions

When versioning is enabled, use canvases change-requests to review and publish:

# List requests for a canvas (or active canvas)
superplane canvases change-requests list <canvas_name_or_id>

# Create a change request
superplane canvases change-requests create <canvas_name_or_id> \
  --title "Add incident routing path" \
  --description "Introduces PagerDuty fallback and Slack notification branch."

# Review actions
superplane canvases change-requests approve <change-request-id> <canvas_name_or_id>
superplane canvases change-requests unapprove <change-request-id> <canvas_name_or_id>
superplane canvases change-requests reject <change-request-id> <canvas_name_or_id>
superplane canvases change-requests reopen <change-request-id> <canvas_name_or_id>
superplane canvases change-requests publish <change-request-id> <canvas_name_or_id>

Useful filters:

# Open requests only
superplane canvases change-requests list <canvas_name_or_id> --status open

# Conflicted requests only
superplane canvases change-requests list <canvas_name_or_id> --status conflicted

# Requests created by you
superplane canvases change-requests list <canvas_name_or_id> --mine

Resolve conflicted change requests

If two change requests edit overlapping nodes differently, one or both can become conflicted. Conflicted requests cannot be approved or published until resolved.

Use a resolved canvas YAML and apply it to the change request:

superplane canvases change-requests resolve <change-request-id> <canvas_name_or_id> \
  --file resolved_canvas.yaml

Optional auto-layout can be applied during resolve:

superplane canvases change-requests resolve <change-request-id> <canvas_name_or_id> \
  --file resolved_canvas.yaml \
  --auto-layout horizontal

Canvas YAML shape (minimal working example)

When updating canvases via YAML, component nodes and edges must use the API field names.

This example connects a schedule trigger to an http component that sends a keepalive request every minute:

apiVersion: v1
kind: Canvas
metadata:
  id: <canvas_id>
  name: Store app
spec:
  edges:
    - sourceId: schedule-schedule-w3mak1
      targetId: http-keepalive-ping
      channel: default
  nodes:
    - id: schedule-schedule-w3mak1
      name: schedule
      type: TYPE_TRIGGER
      trigger:
        name: schedule
      paused: false
      position:
        x: 144
        y: 0
      configuration:
        type: minutes
        minutesInterval: 1
        customName: Keepalive {{ now() }}
    - id: http-keepalive-ping
      name: http
      type: TYPE_COMPONENT
      component:
        name: http
      paused: false
      position:
        x: 456
        y: 0
      configuration:
        method: GET
        url: https://store-app-c6nr.examplepaas.com/
        customName: PaaS keepalive

Notes:

• For component nodes, type must be TYPE_COMPONENT and component.name is required.
• For trigger nodes, use type: TYPE_TRIGGER and trigger.name.
• Edge fields are sourceId, targetId, and optional channel.
• Use superplane index components to find component keys (for example, http, if, noop).
• Positioning guideline for agents:
  • Keep downstream nodes on the same row by default (y unchanged).
  • Use x = upstream.x + 480 as the default spacing for new connected nodes.
  • Avoid changing positions of existing nodes unless explicitly requested.
  • If overlap still appears in UI, apply a small horizontal nudge (x +/- 80..120) before changing y.

Discovery index

Use index to discover available integration definitions, triggers, and components.

superplane index integrations

Describe one integration definition:

superplane index integrations --name <integration_name>

List core components:

superplane index components

List components from an integration definition:

superplane index components --from <integration_name>

Describe one component:

superplane index components --name <component_name>

List triggers from an integration definition:

superplane index triggers --from <integration_name>

Describe one trigger:

superplane index triggers --name <trigger_name>

Managing integrations

List connected integrations:

superplane integrations list

Get details for one connected integration:

superplane integrations get <connected_integration_id>

List resources available from a connected integration:

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

You can pass additional query parameters when needed:

superplane integrations list-resources \
  --id <connected_integration_id> \
  --type <resource_type> \
  --parameters key=value,key2=value2

Managing secrets

List secrets:

superplane secrets list

Create a secret from a file:

superplane secrets create --file my_secret.yaml

Update a secret from a file:

superplane secrets update --file my_secret.yaml

Delete a secret:

superplane secrets delete <secret_name_or_id>

Runtime operations

List root events:

superplane events list --canvas-id <canvas_id>

List executions for a root event:

superplane events list-executions --canvas-id <canvas_id> --event-id <event_id>

List node executions:

superplane executions list --canvas-id <canvas_id> --node-id <node_id>

Cancel a node execution:

superplane executions cancel --canvas-id <canvas_id> --execution-id <execution_id>

List queue items for a node:

superplane queue list --canvas-id <canvas_id> --node-id <node_id>

Delete a queue item:

superplane queue delete --canvas-id <canvas_id> --node-id <node_id> --item-id <item_id>

Updating SuperPlane

To upgrade to the latest version, download the latest binary and replace the existing one:

curl -L https://install.superplane.com/superplane-cli-darwin-arm64 -o superplane
chmod +x superplane
sudo mv superplane /usr/local/bin/superplane

Replace darwin-arm64 with your operating system and architecture (e.g., linux-amd64, darwin-amd64).