> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 出力形式と終了コード

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

> このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/cli/reference/output-formats-and-exit-codes) を参照してください。

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

## 出力形式

`-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` と、任意の詳細行で構成されます。

```text theme={null}
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 オブジェクトになります。

```json theme={null}
{"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`。<br /><br />トップレベルの `code` は CLI の安定した転送レベルのコードのまま。`server.code` がサーバーのより細かい理由を伝える。 |

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

## 終了コード

| コード  | 意味             | 例                                                                                                                             |
| :--- | :------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `0`  | 成功             | `--help`、`version`、および [人間の入力のために一時停止](#人間の入力のために一時停止したワークフロー実行は-0-で終了) したワークフロー実行も含む。                                        |
| `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`](/ja/cli/reference/version#スクリプトを互換性でゲートする) のみ：サーバーが互換と確認されなかった。                                    |

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

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

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

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

ペイロードの構造と再開プロトコルは、Apps 参考ページの [ワークフローが一時停止したとき](/ja/cli/reference/apps#ワークフローが一時停止する場合) を参照してください。