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, apps, secrets, runs), use the SuperPlane skills repository and install the superplane-cli skill: npx skills add superplanehq/skills --skill superplane-cli.

Installation

Direct download

Get the latest binary for your operating system and architecture:

curl -fsSL https://install.superplane.com/install.sh | sh

Older versions can be found in our GitHub Releases page.

APT (Debian and Ubuntu)

On Debian-based distributions you can install and upgrade the CLI through apt.

Trust the SuperPlane signing key, add the repository, and install:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://s3.amazonaws.com/apt.superplane.com/gpg.key \
  | sudo gpg --dearmor -o /etc/apt/keyrings/superplane.gpg

echo "deb [signed-by=/etc/apt/keyrings/superplane.gpg] https://s3.amazonaws.com/apt.superplane.com stable main" \
  | sudo tee /etc/apt/sources.list.d/superplane.list

sudo apt-get update
sudo apt-get install -y superplane-cli

The repo serves both amd64 and arm64 packages; apt picks the right one automatically.

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 time. 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 apps list --output text
superplane apps list -o json
superplane apps canvas get <app_name_or_id> -o yaml

Managing apps

An app is the unit you manage from the CLI. Each app contains a canvas, console, and files.

Generate a starter canvas YAML

Print a blank canvas YAML skeleton to stdout:

superplane apps canvas init

Start from an existing template:

superplane apps canvas init --template health-check-monitor

List available templates:

superplane apps canvas init --list-templates

Write directly to a file instead of stdout:

superplane apps canvas init --output-file canvas.yaml

Create an app

superplane apps create <app_name>

You can also create an app from a canvas YAML file:

superplane apps create --canvas-file my_canvas.yaml

superplane apps create accepts canvas-specific auto-layout flags when creating from a file:

superplane apps create --canvas-file my_canvas.yaml --canvas-auto-layout horizontal

Describe an app canvas

superplane apps canvas get <app_name_or_id>

List apps

superplane apps list

Delete an app

superplane apps delete <app_name_or_id>

Set active app

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

superplane apps active <app_id>

This allows you to omit the app argument on app-scoped commands. Runtime commands that require an explicit identifier use --app-id. The older --canvas-id flag is still accepted as a deprecated alias.

Update an app canvas

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

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

superplane apps canvas 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 apps canvas get <app_name_or_id> -o json | jq '.metadata.versioningEnabled'

Expected values:

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

Quick behavior-based check:

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

App versioning (drafts and change requests)

Canvas update behavior depends on effective app mode:

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

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

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

• If app 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 apps canvas update --draft -f my_canvas.yaml

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

You can include optional metadata when creating the change request:

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

If you already set an active app with superplane apps active <app_id>, you can omit <app_name_or_id> in superplane apps change-requests create.

Change request review actions

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

# List requests for an app (or active app)
superplane apps change-requests list <app_name_or_id>

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

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

Useful filters:

# Open requests only
superplane apps change-requests list <app_name_or_id> --status open

# Conflicted requests only
superplane apps change-requests list <app_name_or_id> --status conflicted

# Requests created by you
superplane apps change-requests list <app_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 apps change-requests resolve <change-request-id> <app_name_or_id> \
  --file resolved_canvas.yaml

Optional auto-layout can be applied during resolve:

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

Canvas YAML shape (minimal working example)

When updating canvases via YAML, action and trigger nodes must use the API field names.

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

apiVersion: v1
kind: Canvas
metadata:
  id: <app_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
      component: schedule
      paused: false
      position:
        x: 144
        y: 0
      configuration:
        type: minutes
        minutesInterval: 1
        customName: Keepalive {{ now() }}
    - id: http-keepalive-ping
      name: http
      type: TYPE_ACTION
      component: http
      paused: false
      position:
        x: 456
        y: 0
      configuration:
        method: GET
        url: https://store-app-c6nr.examplepaas.com/
        customName: PaaS keepalive

Notes:

• For action nodes, type must be TYPE_ACTION and component is required.
• For trigger nodes, use type: TYPE_TRIGGER and component.
• Edge fields are sourceId, targetId, and optional channel.
• Use superplane index actions to find action 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.

Managing console YAML

The console is part of an app. Use apps console to read or replace its YAML.

# Print the live console
superplane apps console get <app_name_or_id> -o yaml

# Print your draft console
superplane apps console get <app_name_or_id> --draft -o yaml

# Replace the console from a file
superplane apps console set <app_name_or_id> console.yaml

# Replace the draft console when versioning is enabled
superplane apps console set <app_name_or_id> console.yaml --draft

If you already set an active app with superplane apps active <app_id>, omit <app_name_or_id> and pass the file with --file:

superplane apps console set --file console.yaml

Reading app files

Use apps files to inspect the git repository attached to an app.

# List files for an app
superplane apps files tree <app_name_or_id>

# Print one file
superplane apps files show canvas.yaml <app_name_or_id>

If you already set an active app, the app argument is optional.

Discovery index

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

superplane index integrations

Describe one integration definition:

superplane index integrations --name <integration_name>

List core actions:

superplane index actions

List actions from an integration definition:

superplane index actions --from <integration_name>

Describe one action:

superplane index actions --name <action_name>

List triggers from an integration definition:

superplane index triggers --from <integration_name>

Describe one trigger:

superplane index triggers --name <trigger_name>

Download the full registry (integrations, actions, and triggers) to a local JSON file:

superplane index dump

By default the file is written to /tmp/superplane-index.json. Use --file to choose a different path:

superplane index dump --file registry.json

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 --app-id <app_id>

List executions for a root event:

superplane events list-executions --app-id <app_id> --event-id <event_id>

List node executions:

superplane executions list --app-id <app_id> --node-id <node_id>

Cancel a node execution:

superplane executions cancel --app-id <app_id> --execution-id <execution_id>

List queue items for a node:

superplane queue list --app-id <app_id> --node-id <node_id>

Delete a queue item:

superplane queue delete --app-id <app_id> --node-id <node_id> --item-id <item_id>

Updating the CLI

If a newer version is available the CLI prints an upgrade notice after every command. You can update in place with:

superplane upgrade

superplane self-update is an alias for the same command. Self-update is available on macOS and Linux for release-built binaries; dev builds and Windows are not supported.

If you installed via apt, upgrade through the package manager instead:

sudo apt-get update
sudo apt-get install --only-upgrade superplane-cli

First-time install uses install.sh or a manual binary from Installation. To reinstall or pin a version, run install.sh again.