superplane-cli

SuperPlane CLI

superplane CLI を使って SuperPlane インスタンスを操作します。

クイックリファレンス

タスク	コマンド
組織に接続	superplane connect <URL> <TOKEN>
自分の情報を確認	superplane whoami
アクティブなアプリを設定	superplane apps active [app-id]
コンテキストを一覧表示／切り替え	superplane contexts
アプリを一覧表示	superplane apps list
スターター YAML を生成	superplane apps canvas init
テンプレートから生成	superplane apps canvas init --template <name>
キャンバステンプレートを一覧表示	superplane apps canvas init --list-templates
アプリを作成	superplane apps create <name> を実行し、エクスポート、編集して、ステージング経由または canvas update --message で適用します
Canvas YAML からアプリを作成	superplane apps create --canvas-file canvas.yaml
レイアウトフラグを指定してアプリを作成	superplane apps create --canvas-file canvas.yaml --canvas-auto-layout horizontal
ステージングの状態を確認	superplane apps staging status [name-or-id]
ファイルをステージング	superplane apps staging update --file canvas.yaml [--file console.yaml ...]
ステージングした変更をコミット	superplane apps staging commit --message "..."
Canvas をエクスポート	superplane apps canvas get <name-or-id> -o yaml
Canvas を更新（直接コミット）	superplane apps canvas update -f canvas.yaml --message "..."
Canvas 全体を自動レイアウト	superplane apps canvas update -f canvas.yaml --message "..." --auto-layout horizontal
接続されたサブグラフを自動レイアウト	superplane apps canvas update -f canvas.yaml --message "..." --auto-layout horizontal --auto-layout-scope connected-component --auto-layout-node <node-id>
コンソールをエクスポート	superplane apps console get <name-or-id> -o yaml > console.yaml
コンソールを更新（直接コミット）	superplane apps console set -f console.yaml --message "..."
アプリのファイルを一覧表示	superplane apps files tree <name-or-id>
アプリのファイルを表示	superplane apps files show <path> <name-or-id>
利用可能なプロバイダーを一覧表示	superplane index integrations
プロバイダーの詳細を表示	superplane index integrations --name github
接続済みインテグレーションを一覧表示	superplane integrations list
接続済みインテグレーションを確認	superplane integrations get <id>
インテグレーションのリソースを一覧表示	superplane integrations list-resources --id <id> --type <type>
アクションを一覧表示	superplane index actions
プロバイダーのアクションを表示	superplane index actions --from github
アクションの詳細を表示	superplane index actions --name semaphore.runWorkflow
トリガーを一覧表示	superplane index triggers
プロバイダーのトリガーを表示	superplane index triggers --from github
トリガーの詳細を表示	superplane index triggers --name github.onPush
シークレットを一覧表示	superplane secrets list
シークレットを作成	superplane secrets create --file secret.yaml
実行を一覧表示	superplane runs list --app-id <id>
実行の詳細を表示	superplane runs describe <run-id> --app-id <id>
ノードの実行を一覧表示	superplane executions list --app-id <id> --node-id <nid>
実行をキャンセル	superplane executions cancel --app-id <id> --execution-id <eid>

CLI がインストールされていることを確認する

CLI の操作を行う前に、ネットワーク接続なしで CLI バイナリを利用できることを確認してください。

command -v superplane

パスが出力されない場合、CLI はインストールされていません。作業を中止し、ユーザーに次のように伝えてください。

SuperPlane CLI がインストールされていません。https://docs.superplane.com/installation/cli からインストールしてから、この作業を再実行してください。

ユーザーに代わって CLI をインストールしないでください。ドキュメントに基づく推測で作業を続行しないでください。CLI では、ドキュメントで確実に代用できない正確なトリガー名、アクション名、インテグレーション ID、設定スキーマを確認できます。

バイナリが存在することを確認した後にのみ、セッションを確認してください。

superplane whoami

エラーは慎重に判断してください。

• whoami で command not found が出た場合も、CLI が見つからないことを意味します。
• 認証、DNS、タイムアウト、接続に関するエラーは、CLI は存在するものの、現在のセッションからまだ SuperPlane に接続できないことを意味します。その場合は、CLI はインストール済みですが、セッション、ネットワーク、認証が機能していないことをユーザーに伝え、必要に応じて接続するか、ネットワークアクセスを許可するよう依頼してください。

基本的なワークフロー

1. 認証する

SuperPlane UI でサービスアカウントを作成してから、次を実行してください。

superplane connect https://superplane.example.com <API_TOKEN>
superplane whoami

1b. ステージングとコミット

アプリのバージョンは、main ブランチ上の不変のコミットです。コミット前に変更を繰り返す場合は、（git の作業ツリーのような）ステージング領域を使用してください。一度の操作で反映するには、キャンバスまたはコンソールへの直接書き込み時に --message を渡してください。

ステージングしてからコミット（変更を繰り返す場合に推奨）：

superplane apps staging status [name-or-id]

superplane apps staging update \
  --file canvas.yaml \
  --file console.yaml \
  --file README.md

superplane apps staging commit --message "Commit message"

直接コミット（1 つのコマンドでステージングとコミットを実行）：

superplane apps canvas update -f canvas.yaml --message "Commit message"
superplane apps console set -f console.yaml --message "Commit message"

ルール：

• canvas get と console get では、ライブ（コミット済み）のアプリのみを読み取ります。
• canvas update と console set では --message が必須です。指定しない場合は、代わりに staging update と staging commit を使用してください。
• staging update は、各 --file をベース名のみでリポジトリパスに対応付けます（canvas.yaml、console.yaml、README.md など）。
• staging update でステージングする canvas.yaml には、対象アプリと一致する metadata.id を含める必要があります。
• 作業を続ける場合は、staging status またはエージェントの [Staging Status] コンテキストにある、すでにステージングされたパスを再利用してください。

2. 利用可能なものを確認する

まず次を実行して、利用可能なものを把握してください。

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

プロバイダーを 1 つに絞り込みます。

superplane index triggers --from github
superplane index actions --from github

必須の設定フィールドとペイロードの形式を確認します。

superplane index triggers --name github.onPush
superplane index actions --name semaphore.runWorkflow

integration-resource フィールドの実行時オプション（リポジトリやプロジェクトなど）を一覧表示します。

superplane integrations list-resources --id <integration-id> --type <type> --parameters key1=value1,key2=value2

有効なインテグレーション ID を確認するには、まず superplane integrations list を使用してください。

3. キャンバスを段階的に構築する

ひな形となる YAML を生成してから、作成して変更を繰り返します。

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"

キャンバス YAML からアプリを作成する場合、apps create --canvas-file でキャンバス全体のペイロードがすでに送信されます。グラフを反映するためだけに、2 回目の更新が必要だと想定しないでください。

superplane apps create --canvas-file canvas.yaml

ワークフローのルール：

• superplane apps create --canvas-file canvas.yaml は、仕様に記載されたリソース形式の Canvas YAML（apiVersion、kind、metadata、spec）を受け付けます。
• superplane apps create では、キャンバスのレイアウトフラグに canvas- が付きます。--canvas-auto-layout、--canvas-auto-layout-scope、および繰り返し指定する --canvas-auto-layout-node です。
• superplane apps canvas update ... を後から実行するのは、作成後にキャンバスを意図的に変更する場合に限ってください。たとえば、metadata.id を含むファイルから追加の編集を反映する場合や、作成時に使用されたデフォルトとは異なるフラグで自動レイアウトを実行する場合です。
• 変更を繰り返す場合は apps staging update と apps staging commit を使用するか、--message を指定して canvas update／console set で直接コミットしてください。

完全な形式については、Canvas YAML 仕様を参照してください。

CLI 経由のコンソール YAML

superplane apps console を使用して、アプリのコンソール（パネルとグリッドレイアウト）を読み取り、置き換えます。

コマンド：

# With an explicit app name or id
superplane apps console get <name-or-id>
superplane apps console get <name-or-id> -o yaml > console.yaml
superplane apps console set -f console.yaml --message "Update console"
superplane apps console set <name-or-id> -f console.yaml --message "Update console"
superplane apps console set <name-or-id> -f - --message "Update console" < console.yaml

# Stage console changes without committing immediately
superplane apps staging update --file console.yaml
superplane apps staging commit --message "Update console"

# With the active app from `superplane apps active`
superplane apps console get
superplane apps console set -f console.yaml --message "Update console"

動作：

• get は現在の（コミット済みの）コンソールを読み取ります。
• set --message はパネルとレイアウトを置き換え、すぐにコミットします。
• コミットせずにコンソールの編集をステージングするには、staging update --file console.yaml の後に staging commit を使用します。
• コンソールのインポートは全置換です。YAML によって、すべてのパネルとレイアウトの項目が置き換えられます。
• 編集／インポートするファイルをエクスポートするときは、-o yaml を使用します。

安定した YAML エンベロープ、レイアウトフィールド、現在のウィジェットの詳細の確認場所については、コンソール YAML 仕様を参照してください。

CLI 経由の自動レイアウト

自動レイアウトフラグを指定して apps canvas update を使用します。

エージェントのデフォルト動作：

• 自動レイアウトフラグを指定せずに superplane apps canvas update を実行すると、デフォルトで自動レイアウトが適用されます。
• 対象範囲やシードノードを明示的に制御する必要がある場合は、--auto-layout フラグを使用します。
• canvas update を直接実行するコマンドには --message を含めるか、staging update と staging commit を使用します。

# connected component around one seed node (recommended default for existing canvases)
superplane apps canvas update \
  -f canvas.yaml \
  --message "Re-layout canvas" \
  --auto-layout horizontal \
  --auto-layout-scope connected-component \
  --auto-layout-node <node-id>

# full canvas (use sparingly; see policy below)
superplane apps canvas update -f canvas.yaml --message "Re-layout canvas" --auto-layout horizontal

ルールと動作：

• --auto-layout-scope または --auto-layout-node を使用する場合は、--auto-layout が必須です。
• canvas update を直接実行するコマンドでは、--message が必須です。
• 対応アルゴリズム：horizontal。
• 対応する対象範囲：full-canvas、connected-component。
• 対象範囲のデフォルト動作：
  • シードノードが指定されていない場合：full-canvas と同様に動作します。
  • シードノードが指定され、対象範囲が省略されている場合：connected-component と同様に動作します。
• エージェント向けの推奨方針：
  • 既存のキャンバスや、接続されていないノードを含むキャンバスでは、connected-component を優先します。
  • ゼロから作成する場合、グラフが1つの連結成分である場合、またはユーザーがキャンバス全体のレイアウトを明示的に要求した場合に限り、full-canvas を使用します。
• 対象範囲選択のデフォルト：
  • 変更または選択されたノード ID がわかっている場合は、connected-component と --auto-layout-node を使用します。
  • 変更されたノード ID の集合がわかっている場合は、connected-component と複数回の --auto-layout-node を使用します。
  • ノード ID が不明な場合は、full-canvas を使用します。
• 配置はアンカーを維持します。レイアウトされた領域は、キャンバス座標上の現在の左上アンカーを維持し、大きな移動を避けます。

4. シークレットを管理する

superplane secrets create --file secret.yaml
superplane secrets list
superplane secrets update --file secret.yaml
superplane secrets delete <name_or_id>

5. 実行を監視する

superplane runs list --app-id <id>
superplane runs describe <run-id> --app-id <id>

6. トラブルシューティングのチェックリスト

キャンバスを更新するたびに実行します。

superplane apps canvas get <name>

確認項目：

• 必須の configuration フィールドがすべて存在する
• エッジが正しい出力チャンネルを使用している
• ノードに errorMessage が残っていない（特に「integration is required」）
• 名前の重複に関する warningMessage がない
• 式が既存のノード名を参照している（大文字と小文字を区別）

「integration is required」の解決

フィールドタイプが integration-resource（repository や project など）の場合、ノードには接続済みのインテグレーションインスタンスが必要です。

1. superplane integrations list — プロバイダーが接続済みであることを確認します
2. superplane integrations get <id> — 接続を調べます
3. キャンバス YAML のノードに integration.id を追加します
4. superplane integrations list-resources --id <id> --type <type> — 有効なリソース値を確認します
5. superplane apps canvas update -f canvas.yaml --message "Fix integration" — 修正を適用します（または staging update と staging commit を使用します）
6. superplane apps canvas get <name-or-id> — エラーが解消されたことを確認します

他のスキルを使用する場合

必要な内容	使用するスキル
要件に基づくキャンバスの設計	superplane-app-builder
失敗した実行のデバッグ	superplane-monitor

ドキュメント

URL を取得できるエージェント向けに、SuperPlane のドキュメント全体を LLM に適した形式で公開しています。

• コンパクトなインデックス：https://docs.superplane.com/llms.txt
• 全コンテンツ：https://docs.superplane.com/llms-full.txt

参考資料

• キャンバス YAML 仕様 — 例を含む YAML 形式全体
• コンソール YAML 仕様 — 安定したコンソール YAML エンベロープとレイアウト形式