出力形式と終了コード

difyctl の各出力形式が何を出力するか、stdout と stderr の分かれ方、エラーの構造、そして各終了コードの意味

このドキュメントは 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 in
hint: 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	バージョンまたは互換性エラー	unsupported_endpoint、または読み取れない設定ファイル（config_schema_unsupported）。
7	レート制限	HTTP 429（rate_limited）。スクリプトがバックオフして再試行できるよう 1 とは区別される。
64	互換性ゲートの失敗	version --check-compat のみ：サーバーが互換と確認されなかった。

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

人間の入力のために一時停止したワークフロー実行は 0 で終了

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

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

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