出力形式と終了コード

このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版を参照してください。

difyctl はスクリプトで扱えるよう設計されています。データは stdout へ、それ以外はすべて stderr へ出力され、-o グローバルフラグで出力形式を選択し、失敗時には予測可能なコードで終了します。

出力形式#

-o <format> は、コマンドが結果を stdout にどう表示するかを選択します。各コマンドは 5 つのフォーマットのうち一部に対応しており、対応状況は --help と各参考ページのフラグ表に記載されています。

フォーマット	stdout に出力される内容
`json`	結果を整形した JSON（2 スペースインデント）。Unicode 文字はそのまま表示され、空のフィールドは省略されず明示的に `null` となる。
`yaml`	同じデータを YAML 形式で出力。
`name`	リソース ID のみを 1 行に 1 つ出力。Shell ループ向けで、パース不要。
`wide`	デフォルトのテーブルに列を追加。例えば `get app -o wide` は `WORKSPACE` 列を追加する。
`text`	人間が読みやすいテキスト。`describe app` や `run app` などの単一リソースコマンドのデフォルト。

-o を付けない場合、get app などのリスト系コマンドは整列したテキストテーブルを出力し、その他のコマンドはテキストを出力します。

JSON の構造は安定しています。get app などのリスト系コマンドは行を配列に入れた JSON オブジェクトを出力し、同じコマンドを 2 回実行しても同一のトップレベル構造を返します。コマンドごとの正確な JSON 構造は、各参考ページを参照してください。

チャネル	出力される内容
stdout	データ：テーブル、JSON と YAML ドキュメント、ID、実行結果、エクスポートした DSL
stderr	それ以外すべて：エラー、ヒント、進行中スピナー、`✓ form submitted` などのステータス行、`--think` でストリーミングされる推論

スクリプトで前提にできるルールは次のとおりです。

失敗時、stdout は空のままです。キャプチャしたデータからエラーテキストを除外する必要はありません。
成功時、get と describe コマンドは stderr を空のままにします。run app と resume app はヒントを stderr に出力する場合があります。
進行中スピナーはターミナルでのみ stderr に表示され、-o json、-o yaml、-o name では抑制されます。
パイプ出力に ANSI カラーコードは含まれません。
パイプの受け手が早期に終了した場合（difyctl get app -o name | head -2）、difyctl はパイプ破損で失敗せず 0 で終了します。

エラーは stderr に出力されます。デフォルトの人間向けフォーマットでは、エラーは 1 行の code: message と、任意の詳細行で構成されます。

not_logged_in: not logged inhint: run 'difyctl auth login'

HTTP リクエストが関わっていた場合、続けて request: <METHOD> <url> 行と http_status: <n> 行が出力されます。

サーバーの応答が Dify 標準のエラーボディを含む場合、ヘッダー行には CLI の転送レベルのコードではなく、サーバーのより具体的なコード（not_found、invalid_param）が表示されます。

フィールドごとの検証詳細はインデントされた行として続き、difyctl 自身のヒントがない場合はサーバーのヒントが表示されます。

-o json では、同じエラーが stderr 上の 1 行の JSON オブジェクトになります。

{"error":{"code":"not_logged_in","message":"not logged in","hint":"run 'difyctl auth login'"}}

エラー表示を切り替えるのは -o json だけです。-o yaml の失敗は人間向けフォーマットで出力されます。

フィールド	出現条件	意味
`code`	常時	安定した機械可読のエラーコード。メッセージ文ではなく、これで分岐する。
`message`	常時	人間が読める説明。
`hint`	判明している場合	最も速い修正方法。多くはコピー＆ペーストできるコマンド。
`http_status`	HTTP 失敗時	失敗したリクエストのステータスコード。
`method`、`url`	HTTP 失敗時	失敗したリクエスト。
`raw_response`	`-v` 指定時のみ	サーバーの生のレスポンスボディ。bearer token はマスク済み。
`server`	HTTP 失敗かつ応答が Dify 標準のエラーボディの場合	サーバー自身のエラー：`code`、`message`、`status`、および任意の `hint` と `details`。トップレベルの `code` は CLI の安定した転送レベルのコードのまま。`server.code` がサーバーのより細かい理由を伝える。

各コードの意味と修正方法は、トラブルシューティングを参照してください。

コード	意味	例
`0`	成功	`--help`、`version`、および人間の入力のために一時停止したワークフロー実行も含む。
`1`	一般的な失敗	ネットワークとサーバーのエラー（`network_connection`、`server_5xx`、`server_4xx_other`）、不明なコマンド、不明なフラグ、到達できない OS キーチェーン（`keyring_unavailable`）。
`2`	用法エラー	無効なフラグ値（`-o table`、`--limit 0`）、引数の不足、UUID でないアプリまたはワークスペース ID、JSON オブジェクトでない `--inputs`。
`4`	認証エラー	`not_logged_in`、`auth_expired`、`token_expired`、`access_denied`。
`6`	バージョンまたは互換性エラー	`version_skew`（サーバーがこの `difyctl` のサポート対象より古い、またはサーバーが古すぎる `difyctl` を HTTP 426 で拒否した）、`unsupported_endpoint`（サーバーにこのビルドが必要とするエンドポイントがない）、または読み取れない設定ファイル（`config_schema_unsupported`）。
`7`	レート制限	HTTP 429（`rate_limited`）。スクリプトがバックオフして再試行できるよう `1` とは区別される。
`64`	互換性ゲートの失敗	`version --check-compat` のみ：サーバーが互換と確認されなかった。

厳密なスクリプト向けの注意点が 1 つあります。パーサーレベルの誤り（不明なコマンド、不明なフラグ、値が欠けたフラグ）はプレーンテキストのメッセージとともに 1 で終了しますが、既知のフラグに対する無効な値は 2 で終了します。

Workflow または Chatflow のアプリは、人間の入力を集めるために実行の途中で一時停止できます。この一時停止は失敗ではなく、正常な結果の 1 つです。run app と resume app は 0 で終了し、一時停止のペイロードを stdout に出力します。

スクリプトやエージェントで一時停止を検出するには、-o json で実行し、stdout に "status": "paused" があるかを確認します。終了コードで分岐しないでください。

ペイロードの構造と再開プロトコルは、Apps 参考ページのワークフローが一時停止する場合を参照してください。