# 出力と終了コード

> Nodaro CLI の出力をテーブルまたは JSON で読み取り、--watch で実行の終了まで追跡し、失敗・キャンセル・保留の終了コードでスクリプトを分岐させます。

Source: https://nodaro.ai/ja/docs/developers/cli/output

Nodaro CLI の**出力**は、デフォルトではターミナルで読みやすい形式になり、`--json` を付けると機械可読になります。`--watch` を付けると、実行系のコマンドは実行が終わるまで待機し、その結果を終了コードで報告するので、シェルスクリプトや CI ジョブはそれをもとに処理を分岐できます。

## テーブルと JSON
`--json` を付けない場合、`list` コマンドは小さな ASCII テーブルを表示し、`get` コマンドは整形された JSON ブロックを表示します。読み取り系のコマンドはすべて `--json` を受け付け、付けると `jq` にそのまま渡せる完全なペイロードを表示します。

```bash
nodaro projects list --json | jq '.[].id'
nodaro workflows run wf_abc --json
```

## --watch で実行を追跡する
実行系のコマンドは、Nodaro が実行を受け付けた時点ですぐに応答を返します。実行が終わるまでポーリングを続けるには、`--watch` を付けます。

```bash
nodaro workflows run wf_abc --watch
nodaro nodes run generate-image --param prompt="a snow leopard" --watch --poll-interval 1000
```

`--watch` は、`workflows run`、`apps run`、`nodes run` などの実行系のコマンド、`executions get`、そして[アセット](https://nodaro.ai/docs/developers/cli/asset-commands)グループと[メディア](https://nodaro.ai/docs/developers/cli/media-commands)グループの生成系コマンドで使えます。`--poll-interval` は、2 回のポーリングの間隔をミリ秒単位で設定します。

## 終了コード
| コード | 意味 |
| --- | --- |
| `0` | 成功です。 |
| `1` | 認証エラー、対象が見つからない、引数のエラー、ネットワークのエラーのいずれかです。 |
| `2` | `--watch` が終了し、実行は失敗しました。 |
| `3` | ジョブがレビューのために保留された（`pending_review`）ため、`--watch` が停止しました。人が判断している状態で、失敗ではありません。 |
| `130` | `--watch` が終了し、実行はキャンセルされました。 |

`--json` を付けると、CLI はペイロードを表示するだけで、コード `2`、`3`、`130` のいずれも設定せずに終了します。このモードでは、代わりに出力の `status` フィールドで分岐してください。

```bash
status=$(nodaro workflows run wf_abc --watch --json | jq -r '.status')
```

トークンがない、期限切れ、または無効な場合、CLI はその旨を表示して `nodaro auth login` を提案し、コード `1` で終了します。それ以外の API エラーでは、メッセージとエラーコードを表示します。コードの一覧は、[エラー](https://nodaro.ai/docs/developers/api/errors)を参照してください。

## ジョブがレビューのために保留された場合
一部のデプロイ環境では、生成結果を引き渡す前にレビューします。そのようなデプロイ環境では、ジョブが `pending_review` ステータスになることがあります。作業自体は完了しており、クレジットは確保されたままで、結果を引き渡すかどうかは人が判断します。

このステータスは自動では変わらないため、`--watch` はポーリングを停止します。`awaiting review (a human decision is pending; not a failure)` と表示し、コード `3` で終了します。

- **リクエストを再送信しないでください。**重複したリクエストも、同じように保留されます。
- **後で確認してください。**`nodaro jobs get <id>` を使います。ジョブは、次の 3 つの状態のいずれかで終わります。

| ステータス | 意味 |
| --- | --- |
| `completed` | 結果が承認され、引き渡されました。 |
| `failed` | 結果が却下されました。`error_hint.kind` は `policy-block` で、`error_hint.reason` にはユーザーに表示するテキストが入ります。 |
| `cancelled` | ジョブがキャンセルされました。 |

```bash
nodaro nodes run generate-image --param prompt="..." --watch
case $? in
  0) echo "released" ;;
  3) echo "awaiting review, check back later" ;;
  *) echo "failed" ;;
esac
```

## Frequently asked questions

### Nodaro CLI から機械可読な出力を得るには、どうすればよいですか？

読み取り系のコマンドに --json を付けます。付けない場合、list コマンドは小さなテーブルを、get コマンドは整形された JSON ブロックを表示します。

### Nodaro CLI の終了コード 3 は、何を意味しますか？

ジョブがレビューのために保留されていることを意味します。作業自体は完了しており、人が結果を引き渡すかどうかを判断する間、クレジットは確保されたままです。失敗ではないので、リクエストを再送信しないでください。後で nodaro jobs get を使って確認してください。

### 実行が失敗したのに、スクリプトで終了コード 2 が検出できないのはなぜですか？

--json を付けると、CLI は結果を表示するだけで、終了コード 2、3、130 のいずれも設定せずに終了します。代わりに、JSON 出力の status フィールドを読み取ってください。

### CI ジョブに Nodaro の実行を待たせるには、どうすればよいですか？

実行コマンドに --watch を付けます。CLI は実行が終わるまでポーリングを続け、成功なら 0、失敗なら 2、キャンセルなら 130 で終了するので、次のステップをそれに応じて分岐できます。