@scraping-run/actor-cli

v1.0.0

Published

5 months ago

Official CLI for Scraping.run Actor development

Downloads

0High
0Medium
0Low

junsikpark

scraping-run scraping actor serverless developer cli dp api development web-scraping

@scraping-run/actor-cli

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

📖 목차

🚀 설치

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

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

# 설치 확인
actor --version

🎯 빠른 시작

1. 로그인

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

2. 새 Actor 생성

# Actor 초기화
actor init

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

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

3. 기존 Actor 작업

# Actor 복제
actor clone <actor-id>

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

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

📚 명령어 레퍼런스

핵심 명령어 (Git-like)

`actor init`

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

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과 유사)

# 대화형 선택
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과 유사)

actor pull

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

Git-style 충돌 처리:

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

옵션:

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

`actor push`

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

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

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

멀티파일 지원:

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

옵션:

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

`actor status`

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

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에 로그인합니다.

actor login

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

`actor logout`

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

actor logout

`actor whoami`

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

actor whoami

# 출력:
# 👤 현재 사용자 정보
# ✅ 로그인 상태: 인증됨
# 📧 이메일: [email protected]
# 👤 이름: John Doe

개발 명령어

`actor dev`

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

actor dev

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

옵션:

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

`actor run`

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

actor run

# 또는 별칭
actor test

옵션:

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

유틸리티 명령어

`actor log`

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

actor log

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

옵션:

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

`actor diff`

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

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');

다양한 비교 옵션:

actor diff                    # 현재 작업 디렉토리 vs 마지막 알려진 상태
actor diff --remote           # 현재 작업 디렉토리 vs 서버 최신 상태  
actor diff --staged           # 마지막 알려진 상태 vs 서버 최신 상태

옵션:

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

`actor studio`

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

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 설정을 관리합니다.

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

`actor list`

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

actor list

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

`actor info`

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

actor info

🔄 워크플로우

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

# 1. Actor 초기화
actor init

# 2. 개발 모드 시작
actor dev

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

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

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

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

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

# 3. 개발 모드 시작
actor dev

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

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

팀 협업 (Git-like)

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

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

🛠 문제 해결

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

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

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

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

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

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

개발 모드가 시작되지 않음

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

# 또는 Actor 초기화
actor init

🔧 고급 설정

환경 변수

# 설정 파일로 관리됨 (환경변수 직접 사용 안함)
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 파일

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@scraping-run/actor-cli

📖 목차

🚀 설치

🎯 빠른 시작

1. 로그인

2. 새 Actor 생성

3. 기존 Actor 작업

📚 명령어 레퍼런스

핵심 명령어 (Git-like)

actor init

actor clone [actor-id]

actor pull

actor push

actor status

인증 명령어 (Docker-like)

actor login

actor logout

actor whoami

개발 명령어

actor dev

actor run

유틸리티 명령어

actor log

actor diff

actor studio

actor config

actor list

actor info

🔄 워크플로우

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

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

팀 협업 (Git-like)

🛠 문제 해결

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

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

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

개발 모드가 시작되지 않음

🔧 고급 설정

환경 변수

설정 파일 위치

.actorignore 파일

.actor/ 메타데이터 폴더

📚 참고 자료

🆘 도움말

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

✨ 새로운 기능

🔄 명령어 변경

🗂️ 메타데이터 관리

📝 라이선스

`actor init`

`actor clone [actor-id]`

`actor pull`

`actor push`

`actor status`

`actor login`

`actor logout`

`actor whoami`

`actor dev`

`actor run`

`actor log`

`actor diff`

`actor studio`

`actor config`

`actor list`

`actor info`