> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 出力と終了コード

> Octoparse CLIのJSON出力、JSONLイベントストリーム、stdout、stderr、終了コード、自動化向け推奨事項を説明します。

Octoparse CLIは、ターミナル向けの人が読みやすい出力と、自動化向けの機械可読な出力をサポートしています。

スクリプト、エージェント、CIジョブ、その他の自動化環境からOctoparse CLIを呼び出す場合は、このページを参照してください。

## JSON出力

安定した単一のJSONレスポンスが必要な場合は、`--json` を使用します。

```bash theme={null}
octoparse task list --json
octoparse auth status --json
octoparse local status <taskId> --json
```

成功したコマンドは `ok: true` と `data` フィールドを持つJSONエンベロープを返します。

```json theme={null}
{
  "ok": true,
  "data": {
    "items": [
      { "taskId": "abc123", "taskName": "Example task", "status": "Idle" }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

失敗したコマンドは `ok: false` と `error` フィールドを返します。

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key is required for this command."
  }
}
```

代表的なエラーコード：`AUTH_REQUIRED`、`AUTH_INVALID`、`TASK_INVALID`、`LINUX_ARM64_UNSUPPORTED`、`ENGINE_RUN_FAILED`、`UNSUPPORTED_EXPORT_FORMAT`。完全なリストは `octoparse capabilities --json` で確認できます。

## JSONLイベントストリーム

長時間実行されるローカル抽出には `--jsonl` を使用します。1行につき1つのJSONオブジェクトをストリームします。

```bash theme={null}
octoparse run <taskId> --jsonl
```

典型的なストリーム例：

```jsonl theme={null}
{"event":"run.started","taskId":"abc123","timestamp":"2026-01-01T10:00:00.000Z"}
{"event":"row","taskId":"abc123","count":1}
{"event":"captcha","taskId":"abc123","service":"..."}
{"event":"proxy","taskId":"abc123","status":"..."}
{"event":"run.completed","taskId":"abc123","savedRows":42}
```

安定したイベントタイプ：

| イベント                 | 発火タイミング              |
| -------------------- | -------------------- |
| `warning`            | 非致命的なランタイム警告         |
| `billing.warning`    | 残高が少ない警告             |
| `billing.error`      | 残高不足                 |
| `run.started`        | ローカル実行開始             |
| `row`                | 行が保存された              |
| `log`                | エンジンのログ行             |
| `captcha`            | ランタイムからのCAPTCHAリクエスト |
| `proxy`              | プロキシのリクエストまたは状態      |
| `download.started`   | ファイルダウンロード開始         |
| `download.succeeded` | ファイルダウンロード完了         |
| `download.failed`    | ファイルダウンロード失敗         |
| `run.paused`         | 実行が一時停止              |
| `run.resumed`        | 実行が再開                |
| `run.stopping`       | 停止リクエスト受付、終了処理中      |
| `run.stopped`        | ユーザーにより実行停止          |
| `run.failed`         | エラーにより実行失敗           |

<Note>
  イベント名やフィールドはバージョンによって変わる可能性があります。各行を1つのJSONオブジェクトとして扱い、未知のフィールドは安全に処理してください。
</Note>

## デタッチした実行のアーティファクト

`--detach` で実行した場合、CLIは出力ディレクトリにブートストラップファイルを書き込みます。

| ファイル             | 内容           |
| ---------------- | ------------ |
| `bootstrap.json` | 実行メタデータと初期状態 |
| `stdout.log`     | 実行の標準出力      |
| `stderr.log`     | 実行の標準エラー     |

ローカル実行アーティファクトファイル：

| ファイル              | 内容            |
| ----------------- | ------------- |
| `meta.json`       | 実行メタデータ       |
| `control.json`    | 実行制御状態        |
| `events.jsonl`    | すべてのJSONLイベント |
| `logs.jsonl`      | エンジンのログ行      |
| `rows.jsonl`      | 保存された行        |
| `downloads.jsonl` | ダウンロードイベント    |

## stdoutとstderr

| ストリーム  | 通常モード    | `--json` / `--jsonl` モード |
| ------ | -------- | ------------------------ |
| stdout | コマンド出力   | 構造化JSONまたはJSONL          |
| stderr | 診断、警告、失敗 | プレーンテキストまたはJSONエラーエンベロープ |

この分離により、自動化ツールは診断ログと混ざることなく必要な出力をパイプできます。

## 終了コード

| 終了コード | 意味              | 代表的なトリガー                                                 |
| ----- | --------------- | -------------------------------------------------------- |
| 0     | 成功              | コマンドが要求どおり完了                                             |
| 1     | 操作失敗            | 認証失敗、タスクが見つからない、エクスポートエラー                                |
| 2     | ランタイムまたは環境の失敗   | Node.jsのバージョン不一致、Chrome利用不可、エンジン初期化失敗、Linux arm64        |
| 3     | サポートされていないタスク定義 | CLI v1でサポートされていないkernel browserまたはlegacy workflowをタスクが使用 |

ゼロ以外の終了コードは、コマンドが要求どおりに完了しなかったことを意味します。

## 自動化の推奨事項

* 単一の構造化レスポンスが必要なスクリプトには `--json` を使用します。
* 長時間実行されるタスクには `--jsonl` を使用します。
* ゼロ以外の終了コードは自動化ステップの失敗として扱います。
* デバッグ時はstderrを別途取得します。
* APIキーやトークンをログやCI出力に含めないでください。
* エージェントワークフローの開始時に `octoparse capabilities --json` を実行し、現在のコマンド体系とマシンコントラクトを確認します。

<Note>
  AIエージェントや自動化環境では、人間向け出力よりも `--json` または `--jsonl` の使用を推奨します。`octoparse capabilities --json` でマシンコントラクト全体を取得してから開始してください。
</Note>