Managing Apps

An app is the primary 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-id <draft_id> -f ....
• false: effective versioning disabled for this app. Use superplane apps canvas update -f ... (no --draft-id).

Quick behavior-based check:

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

App versioning (drafts)

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-id.

• If app versioning is disabled, do not use --draft-id; updates apply directly.

Draft workflow (versioning enabled):

# List available drafts
superplane apps drafts list <app_name_or_id>

# Write changes to a specific draft version
superplane apps canvas update --draft-id <draft_id> -f my_canvas.yaml

If you already set an active app with superplane apps active <app_id>, you can omit <app_name_or_id> in superplane apps drafts list.

Draft lifecycle actions

When versioning is enabled, use apps drafts to manage your drafts:

# List drafts for an app (or active app)
superplane apps drafts list <app_name_or_id>

# Create a new draft
superplane apps drafts create <app_name_or_id> --name "Add incident routing path"

# Delete a draft
superplane apps drafts delete <draft_id> <app_name_or_id>

Repository-backed staging

When versioning is enabled, edits to canvas.yaml and console.yaml are written to a staging layer on your draft. These staged changes must be committed before they become part of the draft version.

# Stage changes to canvas.yaml
superplane apps canvas update --draft-id <draft_id> -f my_canvas.yaml

You can view a visual diff of staged changes and commit or discard them using the SuperPlane UI or API.

Publish a draft

Once your draft is ready and all changes are committed, you can publish it to make it the live version using the SuperPlane UI or API.

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-id <draft_id> -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-id <draft_id>

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

Managing app memory

List memory records stored by an app:

superplane apps memory list <app_name_or_id>

Filter memory records by a specific namespace:

superplane apps memory list <app_name_or_id> --namespace "my-namespace"

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

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.