出力と終了コード

Octoparse CLIは、ターミナル向けの人が読みやすい出力と、自動化向けの機械可読な出力をサポートしています。スクリプト、エージェント、CIジョブ、その他の自動化環境からOctoparse CLIを呼び出す場合は、このページを参照してください。

JSON出力

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

octoparse task list --json
octoparse auth status --json
octoparse local status <taskId> --json

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

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

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

{
  "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オブジェクトをストリームします。

octoparse run <taskId> --jsonl

典型的なストリーム例：

{"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`	エラーにより実行失敗

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

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

--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 を実行し、現在のコマンド体系とマシンコントラクトを確認します。

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

概要

はじめに

ガイド

リファレンス

JSON出力

JSONLイベントストリーム

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

stdoutとstderr

終了コード

自動化の推奨事項

​JSON出力

​JSONLイベントストリーム

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

​stdoutとstderr

​終了コード

​自動化の推奨事項

JSON出力

JSONLイベントストリーム

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

stdoutとstderr

終了コード

自動化の推奨事項