> ## 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.

# Output and exit codes

> Understand Octoparse CLI JSON output, JSONL event streams, stdout, stderr, exit codes, and JSONL event types for automation.

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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

A typical stream:

```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}
```

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         |

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

## 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.

<Note>
  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.
</Note>