출력 및 종료 코드

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

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

{
  "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 객체를 스트리밍합니다.

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`	오류로 실행 실패

이벤트 이름과 필드는 버전에 따라 변경될 수 있습니다. 각 줄을 독립된 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이 지원하지 않는 커널 브라우저 또는 레거시 워크플로 사용

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

자동화 권장 사항

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

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

개요

시작하기

작업 만들기

작업 및 실행

데이터

자동화

레퍼런스

JSON 출력

JSONL 이벤트 스트림

분리 실행 아티팩트

stdout 및 stderr

종료 코드

자동화 권장 사항

​JSON 출력

​JSONL 이벤트 스트림

​분리 실행 아티팩트

​stdout 및 stderr

​종료 코드

​자동화 권장 사항

JSON 출력

JSONL 이벤트 스트림

분리 실행 아티팩트

stdout 및 stderr

종료 코드

자동화 권장 사항