npm package: @scraping-run/actor-cli
Description: Official CLI for Scraping.run Actor development
Author: scraping.run team
Latest version: 1.0.0

# @scraping-run/actor-cli

**🎭 Actor CLI** - Scraping.run Actor 개발을 위한 공식 CLI 도구입니다. Git과 Docker의 직관적인 워크플로우로 Actor를 개발, 테스트, 배포할 수 있습니다.

## 📖 목차

- [설치](#-설치)
- [빠른 시작](#-빠른-시작)
- [명령어 레퍼런스](#-명령어-레퍼런스)
  - [핵심 명령어 (Git-like)](#핵심-명령어-git-like)
  - [인증 명령어 (Docker-like)](#인증-명령어-docker-like)
  - [개발 명령어](#개발-명령어)
  - [유틸리티 명령어](#유틸리티-명령어)
- [워크플로우](#-워크플로우)
- [문제 해결](#-문제-해결)

## 🚀 설치

```bash
# npm을 통한 전역 설치
npm install -g @scraping-run/actor-cli

# 또는 yarn을 통한 설치
yarn global add @scraping-run/actor-cli

# 설치 확인
actor --version
```

## 🎯 빠른 시작

### 1. 로그인

```bash
actor login
# 브라우저가 열리고 Google OAuth 또는 이메일로 로그인
```

### 2. 새 Actor 생성

```bash
# Actor 초기화
actor init

# 개발 모드 실행 (hot reload 지원)
actor dev

# 서버에 배포 (메시지 필수)
actor push -m "첫 배포"
```

### 3. 기존 Actor 작업

```bash
# Actor 복제
actor clone <actor-id>

# 최신 코드 가져오기 (Git-style)
actor pull

# 변경사항 배포
actor push -m "버그 수정"
```

## 📚 명령어 레퍼런스

### 핵심 명령어 (Git-like)

#### `actor init`

새 Actor 프로젝트를 초기화합니다.

```bash
actor init

# 대화형 프롬프트:
# 🎭 새 Actor 초기화
# 
# ? Actor 표시 이름: My Web Scraper
# ? 설명: 웹 데이터 수집용 스크래퍼  
# ? API 경로 (예: api/v1/my-actor): api/v1/my-scraper
```

**옵션:**
- `-n, --name <name>`: Actor 이름 지정
- `-d, --dir <dir>`: 초기화할 디렉토리 (기본: 현재 디렉토리)
- `-f, --force`: 디렉토리가 비어있지 않아도 강제 초기화
- `--skip-install`: npm install 건너뛰기

#### `actor clone [actor-id]`

서버에서 기존 Actor를 복제합니다. (git clone과 유사)

```bash
# 대화형 선택
actor clone

# 직접 지정 (ID, name, displayName 모두 가능)
actor clone cmf6vaujs000jjt7wlo8lf1l5
actor clone lsvqpm
actor clone "My Web Scraper"
```

**옵션:**
- `-o, --output <dir>`: 출력 디렉토리 이름 (기본: actor의 name)
- `--no-install`: npm install 건너뛰기

#### `actor pull`

서버에서 최신 Actor 코드를 가져옵니다. (git pull과 유사)

```bash
actor pull

# Git-style 변경사항 감지:
# ✅ 이미 최신 상태입니다
# 또는
# ⚡ Fast-forward 업데이트
# 또는
# ⚠️ 로컬 변경사항이 있습니다
```

**Git-style 충돌 처리:**
- 로컬 변경사항이 있으면 자동으로 감지
- 충돌 시 사용자에게 선택지 제공 (`--force`, `push` 먼저 하기)
- `.actor/` 폴더에 자동 백업 생성

**옵션:**
- `-f, --force`: 로컬 변경사항 무시하고 강제 pull

#### `actor push`

Actor를 서버에 배포합니다. (git push와 유사) **배포 메시지 필수**

```bash
actor push -m "버그 수정 및 성능 개선"

# 메시지 없이 실행 시 프롬프트
# 💬 배포 메시지가 필요합니다
# ? 배포 메시지를 입력하세요: _
```

**멀티파일 지원:**
- 전체 프로젝트 구조를 서버에 동기화
- `.actorignore` 파일로 업로드 제외 파일 지정
- Git-style 파일 해시 추적

**옵션:**
- `-m, --message <message>`: 배포 메시지 (필수)
- `--skip-validation`: 코드 검증 건너뛰기

#### `actor status`

현재 Actor의 상태를 확인합니다. (git status와 유사)

```bash
actor status

# 출력:
# 📊 Actor 상태
# 
# Actor 정보:
#   표시 이름: My Web Scraper
#   Actor Name: lsvqpm
#   Actor ID: cmf6vaujs000jjt7wlo8lf1l5
#   Actor URL: https://lsvqpm.prod.scraping.run
# 
# DataPlane 상태:
#   상태: ACTIVE ✅
```

### 인증 명령어 (Docker-like)

#### `actor login`

브라우저를 통해 Control Plane에 로그인합니다.

```bash
actor login

# 출력:
# 🔐 Scraping.run 로그인
# 브라우저에서 로그인 페이지를 여는 중...
# ✅ 로그인 성공!
```

#### `actor logout`

로그아웃하고 저장된 인증 정보를 삭제합니다.

```bash
actor logout
```

#### `actor whoami`

현재 로그인한 사용자 정보를 표시합니다.

```bash
actor whoami

# 출력:
# 👤 현재 사용자 정보
# ✅ 로그인 상태: 인증됨
# 📧 이메일: user@example.com
# 👤 이름: John Doe
```

### 개발 명령어

#### `actor dev`

개발 모드를 시작합니다. (watch 모드)

```bash
actor dev

# 출력:
# 🚀 개발 모드 시작
# 포트: 3000
# 호스트: localhost
# 파일 변경 시 자동 재시작됩니다
```

**옵션:**
- `-p, --port <port>`: 포트 번호 지정 (기본: 3000)
- `--host <host>`: 호스트 지정 (기본: localhost)

#### `actor run`

로컬에서 Actor를 실행합니다.

```bash
actor run

# 또는 별칭
actor test
```

**옵션:**
- `-p, --port <port>`: 포트 번호 (기본: 8080)
- `--watch`: watch 모드 활성화
- `--inspect`: 디버그 모드

### 유틸리티 명령어

#### `actor log`

push/pull 히스토리를 표시합니다. (git log와 유사)

```bash
actor log

# 출력:
# 📋 Actor 히스토리 (최근 10개)
# 
# 📤 PUSH
#    시간: 2025-01-05 14:30:00
#    메시지: 버그 수정 및 성능 개선
#    파일 수: 3
#    결과: 성공 ✅
```

**옵션:**
- `-n, --limit <number>`: 표시할 항목 수 (기본: 10)
- `--oneline`: 간단한 한 줄 형식

#### `actor diff`

현재 작업 디렉토리와 마지막 알려진 상태의 변경사항을 표시합니다. (git diff와 유사)

```bash
actor diff

# 출력:
# 📝 Changes between Last Known State and Working Directory:
# 
# M actor.ts
# A new-file.ts
# D old-file.ts
# 
# --- actor.ts (last known state)
# +++ actor.ts (working directory)
# @@ -10,3 +10,4 @@
#    console.log('hello');
# +  console.log('world');
```

**다양한 비교 옵션:**
```bash
actor diff                    # 현재 작업 디렉토리 vs 마지막 알려진 상태
actor diff --remote           # 현재 작업 디렉토리 vs 서버 최신 상태  
actor diff --staged           # 마지막 알려진 상태 vs 서버 최신 상태
```

**옵션:**
- `--remote`: 서버의 최신 상태와 비교
- `--staged`: 마지막 알려진 상태와 서버 최신 상태 비교

#### `actor studio`

Actor Studio를 브라우저에서 엽니다.

```bash
actor studio

# Actor 디렉토리에서 실행 시:
# 🎭 My Web Scraper Studio를 열고 있습니다...
# URL: http://localhost:3000/actors/cmf6vaujs000jjt7wlo8lf1l5/studio
```

**스마트 URL 생성:**
- Actor 디렉토리에서: `/actors/{id}/studio`
- 일반 디렉토리에서: `/studio`
- `config.webUrl` 설정 자동 사용

**옵션:**
- `--no-open`: URL만 출력하고 브라우저는 열지 않기

#### `actor config`

CLI 설정을 관리합니다.

```bash
actor config set api-url https://custom-api.example.com
actor config get api-url
actor config list
```

#### `actor list`

서버에 있는 모든 Actor 목록을 표시합니다.

```bash
actor list

# 출력:
# 📋 Actor 목록 (총 2개)
# 
# 1. My Web Scraper (lsvqpm)
#    ID: cmf6vaujs000jjt7wlo8lf1l5
#    상태: ACTIVE ✅
```

#### `actor info`

현재 Actor의 상세 정보를 표시합니다.

```bash
actor info
```

## 🔄 워크플로우

### 새 프로젝트 시작 (Git-like)

```bash
# 1. Actor 초기화
actor init

# 2. 개발 모드 시작
actor dev

# 3. 코드 작성 및 테스트
# actor.ts 편집

# 4. 서버에 배포
actor push -m "초기 버전"
```

### 기존 프로젝트 수정 (Git-like)

```bash
# 1. Actor 복제 (첫 번째만)
actor clone lsvqpm
cd lsvqpm

# 2. 최신 코드 가져오기
actor pull

# 3. 개발 모드 시작
actor dev

# 4. 수정 및 테스트
# 코드 편집

# 5. 변경사항 배포
actor push -m "기능 추가: 이미지 다운로드"
```

### 팀 협업 (Git-like)

```bash
# 팀원 A
actor push -m "API 엔드포인트 추가"

# 팀원 B  
actor pull  # 최신 변경사항 받기
# 로컬 변경사항이 있으면 충돌 감지 및 해결 안내
actor push -m "오류 처리 개선"
```

## 🛠 문제 해결

### "Actor 디렉토리가 아닙니다" 오류

```bash
# 현재 디렉토리에 actor.json이 없음
# 해결책:
actor init  # 새 Actor 시작
# 또는
actor clone <actor-id>  # 기존 Actor 복제
```

### "로컬 변경사항이 있습니다" 충돌

```bash
# Git-style 충돌 해결:
actor pull --force    # 로컬 변경사항 무시
# 또는
actor push -m "변경사항"  # 로컬을 먼저 push
```

### "서버에 연결할 수 없습니다" 오류

```bash
# 인증 토큰이 만료되었거나 없음
# 해결책:
actor login
# 또는 현재 상태 확인
actor whoami
```

### 개발 모드가 시작되지 않음

```bash
# package.json의 dev 스크립트 확인
{
  "scripts": {
    "dev": "ts-node --watch actor.ts"
  }
}

# 또는 Actor 초기화
actor init
```

## 🔧 고급 설정

### 환경 변수

```bash
# 설정 파일로 관리됨 (환경변수 직접 사용 안함)
actor config set api-url https://custom-api.example.com
actor config set web-url https://custom-web.example.com
```

### 설정 파일 위치

- **Windows**: `%USERPROFILE%\.scraping\config.json`
- **macOS/Linux**: `~/.scraping/config.json`

### .actorignore 파일

```gitignore
# Actor 업로드에서 제외할 파일들
node_modules/
dist/
.actor/
*.log
.env
```

### .actor/ 메타데이터 폴더

Git-style 워크플로우를 위한 메타데이터가 저장되는 폴더입니다.

```
.actor/
├── backup/                    # pull 시 자동 백업
│   ├── initial-2025-01-05T14-30-00/   # 첫 pull 시 로컬 파일 백업
│   └── 2025-01-05T14-30-00/           # 정규 백업
├── base/                      # 3-way merge를 위한 베이스 파일들
│   ├── actor.ts
│   ├── package.json
│   └── ...
└── logs.json                  # push/pull 히스토리 (향후 구현)
```

**자동 초기화:**
- 첫 번째 `actor pull` 시 자동으로 생성
- 현재 로컬 파일들을 `initial-{timestamp}` 백업으로 안전하게 보존
- Git-style Fast-forward로 서버 파일 적용

## 📚 참고 자료

- [Actor 개발 가이드](../../docs/actor-development-guide.md)
- [API 문서](https://docs.scraping.run/api)
- [예제 프로젝트](https://github.com/scraping-run/examples)

## 🆘 도움말

```bash
# 전체 도움말
actor --help

# 특정 명령어 도움말
actor init --help
actor push --help
actor pull --help
```

## 🆕 주요 변경사항 (v1.0.0)

### ✨ 새로운 기능
- **Git-style 워크플로우**: `pull`에서 로컬 변경사항 보호 및 충돌 감지
- **Docker-like 명령어**: `actor login/logout/whoami`로 간편한 인증
- **멀티파일 지원**: 전체 프로젝트 구조 동기화
- **새 개발 명령어**: `actor dev` (watch 모드), `actor log` (히스토리)
- **스마트 Studio**: 현재 Actor ID 자동 감지하여 정확한 Studio URL 생성

### 🔄 명령어 변경
- `scr actor init` → `actor init`
- `scr actor clone` → `actor clone`  
- `scr actor push` → `actor push`
- `scr actor pull` → `actor pull`
- `scr auth login` → `actor login`
- `scr auth logout` → `actor logout`

### 🗂️ 메타데이터 관리
- `.actor/` 폴더로 메타데이터 통합 관리
- 자동 백업 및 히스토리 추적
- `.actorignore` 지원으로 업로드 제외 파일 관리

## 📝 라이선스

MIT

---

*최종 업데이트: 2025년 9월*