このドキュメントは 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 と、任意の詳細行で構成されます。
request: <METHOD> <url> 行と http_status: <n> 行が出力されます。
サーバーの応答が Dify 標準のエラーボディを含む場合、ヘッダー行には CLI の転送レベルのコードではなく、サーバーのより具体的なコード（not_found、invalid_param）が表示されます。
フィールドごとの検証詳細はインデントされた行として続き、difyctl 自身のヒントがない場合はサーバーのヒントが表示されます。
-o json では、同じエラーが stderr 上の 1 行の JSON オブジェクトになります。
-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 で終了しますが、既知のフラグに対する無効な値は 2 で終了します。
人間の入力のために一時停止したワークフロー実行は 0 で終了
ワークフローアプリは、人間の入力を集めるために実行の途中で一時停止できます。この一時停止は失敗ではなく、正常な結果の 1 つです。run app と resume app は 0 で終了し、一時停止のペイロードを stdout に出力します。
スクリプトやエージェントで一時停止を検出するには、-o json で実行し、stdout に "status": "paused" があるかを確認します。終了コードで分岐しないでください。
ペイロードの構造と再開プロトコルは、Apps 参考ページの ワークフローが一時停止したとき を参照してください。