DEV Community

Cover image for 파이어크롤 CLI 설치 및 사용 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

파이어크롤 CLI 설치 및 사용 방법

#ai #cli #tutorial #webscraping

Firecrawl CLI 개요

Firecrawl CLI는 AI 에이전트와 개발자가 마크다운, JSON, 스크린샷 등 다양한 포맷으로 웹사이트의 데이터를 직접 파일 시스템에 스크랩, 검색, 매핑, 크롤링, 브라우저 자동화할 수 있게 해주는 통합 터미널 도구입니다. npx firecrawl로 설치 없이 빠르게 실행하거나 전역 설치도 가능하며, firecrawl init 한 번으로 Claude Code, Cursor, OpenCode 등 주요 에이전트와 자동으로 연결할 수 있습니다.

지금 Apidog를 사용해보세요

AI 에이전트와 개발자는 깨지기 쉬운 스크립트나 차단된 요청 없이 안정적인 실시간 웹 데이터가 필요합니다. Firecrawl CLI는 스크래핑, 웹 검색, 사이트 매핑, 재귀 크롤링, 클라우드 브라우저 세션을 하나의 터미널 도구로 통합합니다. 결과는 깔끔한 마크다운, 구조화된 JSON, 스크린샷, HTML 등 원하는 형태로 파일 시스템에 바로 저장되어 LLM 토큰 수를 최소화하고 컨텍스트를 정확하게 만듭니다. JavaScript 렌더링 페이지, 동적 사이트, 보호된 흐름도 지원합니다.

💡 팁: Firecrawl CLI 명령을 실행하기 전에 Apidog로 Firecrawl API 엔드포인트(API 키, 매개변수, 응답 등)를 시각적으로 테스트·디버깅해보세요. 에이전트 통합과 문제 해결이 훨씬 쉬워집니다.

시스템 준비, 설치, 인증, 명령 사용, 에이전트 통합, 모범 사례까지 한 번에 정리합니다. Firecrawl CLI는 동시성, 속도 제한, 로컬 캐싱을 자동 관리해주므로 데이터 추출에만 집중할 수 있습니다. 형식 선택기 및 대기 타이머 등의 플래그 선택이 출력 품질과 효율성에 직접적인 영향을 줍니다.

Firecrawl CLI 주요 기능 및 기존 도구 대비 장점

  • 클라우드 브라우저: JavaScript 네이티브 렌더링, 봇 방지 우회, 복잡한 사이트 80% 이상 콘텐츠 추출
  • LLM 최적화: 마크다운으로 정형화된 내용 제거, 컨텍스트 창 압력 최소화
  • 로컬 파일 저장: 대용량 데이터도 API 호출 없이 bash로 검색 가능
  • 스크립트/에이전트 연동: scrape, search, map, crawl, browser 명령을 파이프라인으로 결합
  • 프록시/헤드리스/별도 라이브러리 불필요
  • --only-main-content 등 플래그로 저렴하고 깔끔한 결과 생성

환경 준비 및 설치

Node.js 확인 (최소 18 버전)

node --version
# 필요시 nvm 또는 패키지 관리자로 업데이트
Enter fullscreen mode Exit fullscreen mode

작업 디렉토리 생성

mkdir firecrawl-cli-projects && cd firecrawl-cli-projects
Enter fullscreen mode Exit fullscreen mode

데이터셋 관리와 버전 관리를 쉽게 할 수 있습니다.

원격 분석 비활성화 (선택)

export FIRECRAWL_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Firecrawl CLI 설치 및 에이전트 초기화

가장 빠른 설치와 인증, 에이전트 스킬 자동 추가:

npx -y firecrawl-cli@latest init --all --browser
Enter fullscreen mode Exit fullscreen mode
  • 브라우저가 열려 로그인/가입과 API 키 관리, 에이전트 스킬 구성까지 한 번에 처리합니다.
  • 에이전트(예: Claude Code, Cursor 등)를 재시작하면 Firecrawl CLI 연동이 자동 활성화됩니다.

전역 설치 (지속적 사용)

npm install -g firecrawl-cli
firecrawl --version
Enter fullscreen mode Exit fullscreen mode
  • 어떤 디렉토리에서도 즉시 명령 실행 가능

인증 및 설정 확인

인증 및 API 키 설정

firecrawl login
# 또는 수동 설정:
export FIRECRAWL_API_KEY=fc-your-key-here
Enter fullscreen mode Exit fullscreen mode

상태 및 구성 확인

firecrawl --status
firecrawl view-config
Enter fullscreen mode Exit fullscreen mode
  • 계정 전환은 firecrawl logout 후 재로그인
  • 자체 호스팅 사용 시: --api-url http://localhost:3002

Scrape 명령 실전 활용

기본 스크랩

firecrawl scrape https://example.com --only-main-content
Enter fullscreen mode Exit fullscreen mode
  • -o output.md로 파일 저장
  • --only-main-content로 광고, 네비게이션 제거 → 토큰 절감

여러 포맷 요청

firecrawl scrape https://example.com --format markdown,json,html,links,images --pretty
Enter fullscreen mode Exit fullscreen mode
  • 구조화된 JSON 포함 모든 데이터 반환
  • 스크린샷: --screenshot 또는 --full-page-screenshot
  • 느린 로더: --wait-for 5000

정확한 태그 필터링

firecrawl scrape https://docs.example.com --include-tags main,article --exclude-tags nav,footer,script
Enter fullscreen mode Exit fullscreen mode

성능 벤치마크

firecrawl scrape https://example.com --timing
Enter fullscreen mode Exit fullscreen mode

웹 검색 자동화

검색 및 결과 스크랩

firecrawl search "latest AI agent benchmarks" --scrape --limit 8 --scrape-formats markdown
Enter fullscreen mode Exit fullscreen mode
  • 최신순, 위치, 소스 유형 필터 가능
  • 검색 결과와 브라우저 세션 결합 가능

사이트 매핑 및 재귀 크롤링

사이트 맵핑

firecrawl map https://example.com -o sitemap.json
Enter fullscreen mode Exit fullscreen mode
  • URL 목록 생성 후 scrape/crawl 명령에 공급

재귀 크롤링

firecrawl crawl https://example.com --wait --progress -o crawl-output.json
Enter fullscreen mode Exit fullscreen mode
  • 내부 링크 따라가며 전체 페이지 저장
  • 깊이, 최대 페이지, 동시성 직접 설정 가능

브라우저 세션 자동화

클라우드 브라우저 세션 시작 및 명령 실행

firecrawl browser launch-session
firecrawl browser execute "open https://news.ycombinator.com" --session <id>
firecrawl browser execute "click .titleline > a" --session <id>
firecrawl browser execute "scrape" --session <id>
Enter fullscreen mode Exit fullscreen mode
  • 클릭, 타이핑, 탐색, 추출 등 동적 상호작용 지원
  • 세션 종료로 리소스 해제

고급 구성 및 글로벌 플래그

글로벌 API URL 및 동시성 조정

firecrawl config --api-url https://your-custom-endpoint --concurrency 5
Enter fullscreen mode Exit fullscreen mode
  • JSON 출력, 헤더 등도 전역 설정 가능
  • 대규모 작업 전 --status로 크레딧 모니터링

AI 코딩 에이전트와 통합

  • npx -y firecrawl-cli@latest init --all로 스킬 설치 시 에이전트가 자동 감지
  • CLI+Skills 모드: 에이전트가 명령 직접 실행
  • MCP 모드: 네이티브 도구를 자동 호출
  • Firecrawl CLI는 로컬 파일 경로 반환 → 에이전트 토큰 절감

문제 해결 빠르게 하기

  • 인증 오류: firecrawl login 재실행
  • 속도 제한: 동시성 낮추기, 플랜 업그레이드
  • JS-heavy 사이트 결과 없음: --wait-for 증가, --only-main-content 추가
  • 진단: --timing 플래그 사용
  • 키 변경: firecrawl logout 후 재설정

모범 사례 정리

  • 항상 --only-main-content로 노이즈 최소화
  • 출력 파일과 폴더는 명확하게 네이밍
  • 전체 크롤링 전 소규모 테스트 반복
  • 검색→매핑→크롤링 파이프라인 결합
  • 출력 디렉토리 버전 관리로 재현성 확보
  • 주간 크레딧 사용량 점검

Apidog로 Firecrawl CLI 워크플로우 강화

  • Apidog 무료 다운로드 후 Firecrawl 엔드포인트(스크랩, 검색, 크롤링 등) 컬렉션으로 가져오기
  • 요청 시각화, API 키 변수화, 응답 모킹, 자동화 테스트 지원
  • 복잡한 옵션, 사용자 지정 페이로드도 터미널 실행 전 디버깅 가능
  • Firecrawl CLI + Apidog로 실시간 웹 데이터와 검증된 API 동작 확보

결론

이제 Firecrawl CLI의 설치, 인증, 스크래핑, 검색, 매핑, 크롤링, 브라우저 자동화까지 개발자가 직접 제어할 수 있습니다. Firecrawl CLI는 혼란스러운 웹 액세스를 깔끔한 터미널 기반 파이프라인으로 변환합니다.

오늘 바로 init 명령으로 스크랩을 테스트하고, 플래그를 조합하여 자신만의 워크플로우를 만드세요. 실험적이고 신중한 사용이 더 좋은 결과로 이어집니다.

지금 Apidog로 Firecrawl CLI 테스트와 API 유효성 검증을 시작하세요. Firecrawl CLI로 실시간 웹 마스터리를 손쉽게 구현할 수 있습니다.

추가 자료

Top comments (0)