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

> Octoparse CLI를 사용해 로컬 또는 클라우드 환경에서 Octoparse 작업을 생성, 실행, 관리, 예약, 검사, 자동화하고 내보내세요.

Octoparse CLI는 터미널에서 Octoparse 작업을 생성, 실행, 관리, 예약, 검사하고 내보내는 명령줄 도구입니다.

데스크톱 앱과 달리 Octoparse CLI는 스크립트 기반 워크플로, CI/CD 파이프라인, 서버 환경 및 자동화된 데이터 파이프라인을 위해 설계되었습니다.

## Octoparse CLI의 기능

<CardGroup cols={2}>
  <Card title="URL에서 작업 생성" icon="wand-magic-sparkles" href="./cli/guides/detect">
    URL을 검사하고 자동, 수동 또는 AI 에이전트 워크플로로 로컬 작업 파일을 생성합니다.
  </Card>

  <Card title="작업 검색 및 관리" icon="magnifying-glass" href="./cli/guides/tasks-and-groups">
    클라우드 작업 목록을 보고 키워드로 검색하며 작업 세부 정보를 확인하고 작업 그룹을 관리합니다.
  </Card>

  <Card title="템플릿에서 생성" icon="table-cells" href="./cli/guides/templates">
    템플릿을 조회하고 검색하며 템플릿 작업을 생성하거나 수정합니다.
  </Card>

  <Card title="로컬에서 작업 실행" icon="play" href="./cli/guides/local-runs">
    내장 로컬 엔진과 독립 실행형 Chrome으로 Octoparse 작업을 실행합니다.
  </Card>

  <Card title="브라우저 모드 선택" icon="window" href="./cli/guides/browser-modes">
    독립 실행형 Chrome을 사용하거나 로그인된 Chrome 또는 Edge 프로필을 재사용합니다.
  </Card>

  <Card title="클라우드 작업 실행 및 예약" icon="calendar" href="./cli/guides/cloud-runs-and-schedules">
    클라우드 추출을 시작하고 기록을 검토하며 반복 예약을 설정합니다.
  </Card>

  <Card title="데이터 검사 및 내보내기" icon="file-export" href="./cli/guides/data">
    레코드 수를 확인하고 행을 미리 보며 내보내지 않은 데이터를 검토하고 로컬 또는 클라우드 결과를 내보냅니다.
  </Card>

  <Card title="에이전트로 자동화" icon="robot" href="./cli/guides/automation">
    JSON 출력, JSONL 이벤트 스트림 및 종료 코드를 사용해 CLI를 스크립트와 AI 에이전트에 통합합니다.
  </Card>
</CardGroup>

## 작동 방식

Octoparse CLI는 로컬 추출을 위해 내장 Octoparse 엔진을 직접 실행합니다. 독립 실행형 Chrome을 사용하므로 Electron 데스크톱 클라이언트가 필요하지 않습니다.

클라우드 추출은 백엔드 API를 통해 제어되고, 로컬 추출은 로컬 엔진에서 제어됩니다.

<Note>
  로컬 실행 상태는 이 CLI에서 추적하며 Octoparse 데스크톱 클라이언트 상태와 동기화되지 않습니다.
</Note>

## 요구 사항

Octoparse CLI를 사용하기 전에 다음을 준비하세요.

* Node.js 20 이상
* npm 8 이상
* Octoparse 계정(API 키 또는 OAuth)
* 실행하거나 내보낼 작업에 대한 접근 권한

Linux arm64 제한을 포함한 플랫폼 요구 사항과 설정 단계는 [설치](./cli/quick-start/installation)를 참고하세요.

로컬 `--task-file` 및 `.otd` 실행을 포함한 기능 명령어에는 인증이 필요합니다. `--help`, `--version`, `doctor`, `browser`, `capabilities`, `auth` 같은 설정 및 진단 명령어는 인증 없이 실행할 수 있습니다.

## 일반적인 워크플로

<Steps>
  <Step title="Octoparse CLI 설치">
    npm으로 CLI를 전역 설치합니다.
  </Step>

  <Step title="인증">
    OAuth 또는 Octoparse API 키로 로그인합니다. CI에서는 `OCTO_ENGINE_API_KEY` 환경 변수를 사용하세요.

    <Warning>
      API 키를 Git, 스크립트, 문서, 스크린샷, 공유 로그 또는 CI 출력에 커밋하지 마세요.
    </Warning>
  </Step>

  <Step title="작업 생성 또는 검색">
    `octoparse detect <url>`로 URL에서 작업 파일을 생성하거나 템플릿에서 작업을 생성합니다. 또는 `octoparse task list`로 기존 작업 ID를 찾습니다.
  </Step>

  <Step title="작업 실행 또는 제어">
    작업을 로컬에서 실행하고 클라우드 실행을 시작 또는 중지하거나 클라우드 예약을 설정하고 실행 상태를 확인합니다.
  </Step>

  <Step title="데이터 검사 및 내보내기">
    데이터 상태와 행 미리보기를 확인하고 내보내지 않은 데이터를 검토하거나 로컬 또는 클라우드 결과에서 수집된 데이터를 내보냅니다.
  </Step>
</Steps>

## 빠른 명령어 예시

`<taskId>`는 실제 작업 ID로, `<url>`은 스크래핑할 페이지로 바꾸세요.

```bash theme={null}
octoparse --help
octoparse doctor
octoparse auth login
octoparse detect <url> --auto --goal "Extract product titles and prices" --output task.json
octoparse task list
octoparse task inspect <taskId>
octoparse capabilities --json
octoparse run <taskId>
octoparse cloud start <taskId>
octoparse local status <taskId>
octoparse data export <taskId> --source local --format xlsx
```

## 현재 제한 사항

Octoparse CLI v1은 커널 브라우저 또는 레거시 워크플로를 지원하지 않습니다.

커널 브라우저는 이전 Octoparse 런타임 워크플로에서 사용하던 브라우저 모드를 뜻합니다. 레거시 워크플로는 현재 CLI 런타임이 지원하지 않는 이전 Octoparse 작업 정의로 만든 작업을 뜻합니다.

작업이 지원되지 않으면 최신 Octoparse 데스크톱 앱에서 작업을 다시 만들거나 업데이트한 뒤 CLI로 다시 실행하세요.

## 다음 단계

<CardGroup cols={3}>
  <Card title="Octoparse CLI 설치" icon="download" href="./cli/quick-start/installation">
    Node.js를 설정하고 npm으로 CLI를 설치한 뒤 로컬 런타임을 확인합니다.
  </Card>

  <Card title="URL에서 작업 생성" icon="wand-magic-sparkles" href="./cli/guides/detect">
    detect를 사용해 URL에서 작업 파일을 생성합니다.
  </Card>

  <Card title="모든 명령어 보기" icon="list-check" href="./cli/reference/command-cheatsheet">
    작업, 템플릿, 예약, 감지, 로컬 실행, 클라우드 실행, 인증 및 내보내기 명령어를 확인합니다.
  </Card>
</CardGroup>