> ## 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, 종료 코드 및 JSONL 이벤트 유형을 알아보세요.

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

명령어가 실패하면 코드와 메시지가 들어 있는 `error` 필드와 함께 `ok: false`가 반환됩니다.

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

정확한 `data` 구조는 명령어에 따라 다릅니다. 일반적인 오류 코드에는 `AUTH_REQUIRED`, `AUTH_INVALID`, `TASK_INVALID`, `LINUX_ARM64_UNSUPPORTED`, `ENGINE_RUN_FAILED`, `UNSUPPORTED_EXPORT_FORMAT`이 있습니다. 전체 목록은 `octoparse capabilities --json`을 실행해 확인하세요.

## JSONL 이벤트 스트림

오래 실행되는 로컬 추출에는 `--jsonl`을 사용하세요. 출력은 한 줄에 하나의 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>
  이벤트 이름과 필드는 버전에 따라 변경될 수 있습니다. 각 줄을 독립된 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이 지원하지 않는 커널 브라우저 또는 레거시 워크플로 사용          |

0이 아닌 종료 코드는 명령어가 예상대로 완료되지 않았음을 뜻합니다.

## 자동화 권장 사항

* 하나의 구조화된 응답이 필요한 스크립트에는 `--json`을 사용하세요.
* 오래 실행되는 작업에는 `--jsonl`을 사용하세요.
* 0이 아닌 종료 코드는 자동화 단계 실패로 처리하세요.
* 디버깅할 때는 stderr를 별도로 캡처하세요.
* 로그나 CI 출력에 API 키 또는 토큰을 노출하지 마세요.
* 에이전트 워크플로를 시작할 때 `octoparse capabilities --json`을 실행하여 현재 명령어 범위와 기계 판독 계약을 확인하세요.

<Note>
  AI 에이전트와 자동화 환경에서는 사람이 읽는 출력보다 `--json` 또는 `--jsonl`을 우선 사용하세요. 전체 기계 판독 계약을 확인하려면 `octoparse capabilities --json`부터 실행하세요.
</Note>