Output and exit codes

Octoparse CLI supports human-readable output for terminal use and machine-readable output for automation. Use this page when calling Octoparse CLI from scripts, agents, CI jobs, or other automation environments.

JSON output

Use --json when you need one stable JSON response.

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

Successful commands return a JSON envelope with ok: true and a data field:

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

Failed commands return ok: false with an error field containing a code and message:

{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key is required for this command."
  }
}

The exact data structure depends on the command. Common error codes include AUTH_REQUIRED, AUTH_INVALID, TASK_INVALID, LINUX_ARM64_UNSUPPORTED, ENGINE_RUN_FAILED, and UNSUPPORTED_EXPORT_FORMAT. Run octoparse capabilities --json to see the full list.

JSONL event streams

Use --jsonl for long-running local extractions. Output streams one JSON object per line:

octoparse run <taskId> --jsonl

A typical stream:

{"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}

Stable event types:

Event	When it fires
`warning`	Non-fatal runtime warning
`billing.warning`	Low balance warning
`billing.error`	Balance exhausted
`run.started`	Local run started
`row`	A row was saved
`log`	Engine log line
`captcha`	CAPTCHA request from the runtime
`proxy`	Proxy request or status
`download.started`	File download started
`download.succeeded`	File download completed
`download.failed`	File download failed
`run.paused`	Run paused
`run.resumed`	Run resumed
`run.stopping`	Stop requested, run winding down
`run.stopped`	Run stopped by user
`run.failed`	Run failed with an error

Event names and fields may evolve between versions. Treat each line as a self-contained JSON object and handle unknown fields safely.

Detached run artifacts

When you run with --detach, the CLI writes bootstrap files to the output directory:

File	Contents
`bootstrap.json`	Run metadata and initial state
`stdout.log`	Standard output from the run
`stderr.log`	Standard error from the run

Local run artifact files (in the run directory):

File	Contents
`meta.json`	Run metadata
`control.json`	Run control state
`events.jsonl`	All JSONL events
`logs.jsonl`	Engine log lines
`rows.jsonl`	Saved rows
`downloads.jsonl`	Download events

stdout and stderr

Stream	Human mode	`--json` / `--jsonl` mode
stdout	Command output	Structured JSON or JSONL
stderr	Diagnostics, warnings, failures	Plain text or JSON error envelope

This separation lets automation tools pipe requested output without mixing in diagnostic logs.

Exit codes

Exit code	Meaning	Typical triggers
0	Success	Command completed as requested
1	Operation failed	Auth failure, task not found, export error
2	Runtime or environment failure	Node.js version mismatch, Chrome unavailable, engine init failure, Linux arm64
3	Unsupported task definition	Task uses kernel browser or legacy workflow not supported by CLI v1

A non-zero exit code means the command did not complete as expected.

Automation recommendations

Use --json for scripts that need a single structured response.
Use --jsonl for long-running task execution.
Treat non-zero exit codes as failed automation steps.
Capture stderr separately when debugging.
Do not expose API keys or tokens in logs or CI output.
Run octoparse capabilities --json at the start of an agent workflow to discover the current command surface and machine contract.

For AI agents and automation environments, prefer --json or --jsonl over human-readable output. Start with octoparse capabilities --json to get the full machine contract.

OVERVIEW

GET STARTED

GUIDES

REFERENCE

JSON output

JSONL event streams

Detached run artifacts

stdout and stderr

Exit codes

Automation recommendations

​JSON output

​JSONL event streams

​Detached run artifacts

​stdout and stderr

​Exit codes

​Automation recommendations

JSON output

JSONL event streams

Detached run artifacts

stdout and stderr

Exit codes

Automation recommendations