🔥 Firecrawl CLI
AI 에이전트용 컨텍스트 API인 Firecrawl의 명령어 인터페이스(CLI)입니다. 웹 검색, 스크래핑, 파싱, 크롤링, 매핑을 수행하고, 연구 논문, 개발자 소스, 정부 출처와 상호 작용하며, 터미널에서 직접 에이전트 작업을 실행할 수 있습니다.
설치 (Installation)
npm install -g firecrawl-cli
또는 단일 명령어로 모든 것을 설정할 수 있습니다 (CLI를 전역으로 설치하고, 인증하며, 감지된 코딩 에디터에 공유 스킬을 설치합니다):
npx -y firecrawl-cli@latest init -y --browser
-y: 설정을 비대화형(non-interactively)으로 실행합니다.--browser: Firecrawl 인증을 위해 브라우저를 자동으로 엽니다.- 스킬은 공유 스킬 디렉터리에 전역적으로 설치되며, 기본적으로 감지된 AI 코딩 에이전트에 사용 가능합니다.
스킬(Skills), 워크플로우(Workflows), MCP 설정
Claude Code와 같은 AI 코딩 에이전트를 사용하는 경우, 가족별로 하나의 명령어를 사용하여 스킬 그룹을 수동으로 설치할 수도 있습니다:
firecrawl setup core
기본 설치는 공유 디렉토리인 `~/.agents/skills`와 Firecrawl이 감지한 코딩 에디터를 사용합니다. npx 설치 프로그램은 Codex를 공유 디렉토리 대상으로 항상 포함하며, 이 과정에서 Codex가 감지되지 않더라도 공유 파일과 에이전트 링크를 보존합니다. 에디터가 감지되지 않은 경우, 공유 디렉토리만 채워집니다. npx 경로는 Kiro와 같은 지원되는 전역 대상(global targets) 및 `CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME`과 같은 사용자 지정 구성 위치를 감지합니다. 프로젝트 전용 대상은 제외됩니다. 특정 에디터를 대상으로 하려면 `--agent <에이전트>`를 사용하십시오.
기본적으로 스킬은 감지된 모든 하네스로 라우팅됩니다. 하나의 명령으로 오직 하나의 하네스에만 설치하고 라우팅하려면 다음을 수행합니다:
```bash
curl -fsSL https://firecrawl.dev/install.sh | bash -s -- --agent openclaw
...
bash -s -- 뒤에 오는 모든 인수는 firecrawl init으로 전달되므로, 스킬만 사용하고 로그인 과정이 필요 없는 설정을 위해 --skip-auth와 같은 항목을 추가할 수 있습니다. --agent 없이 대화형으로 firecrawl init을 실행하면 감지된 하네스들의 체크박스가 표시되며(기본적으로 모두 선택됨), 이 중 원하는 부분집합을 선택할 수 있습니다.
| Harness | --agent 값 |
|---|
| Claude Code | claude-code |
| ... | |
에이전트 스킬 (Agent skills)
init 명령어는 기본적으로 CLI 스킬을 설치하고, AI 코딩 에이전트(Cursor, Claude Code, Windsurf 등)에 선택적 추가 기능으로 워크플로우 스킬을 제공합니다:
- CLI 스킬: 에이전트가 라이브 웹 작업(검색, 스크래핑, 상호작용, 매핑, 크롤링, 에이전트) 및 Alexandria 데이터 공급자를 위해 Firecrawl CLI를 사용하는 방법을 학습시킵니다. 기본적으로 설치됩니다.
- 워크플로우 스킬: 에이전트가 리서치 브리프(research briefs), SEO 감사 보고서(SEO audits), QA 보고서, 잠재 고객 목록(lead lists), 지식 기반(knowledge bases), 디자인 시스템 추출 등 Firecrawl 기반 결과물을 생성하는 방법을 학습시킵니다. init 과정에서 대화형 다중 선택을 통해 설정합니다.
모든 스킬 패밀리는 firecrawl/skills 카탈로그에 존재하며, 애플리케이션 코드에 Firecrawl을 통합하기 위한 **빌드 스킬(build skills)**도 포함됩니다:
npx skills add firecrawl/skills
스킬 기여 방법이 궁금하신가요? CLI 스킬(연구/개발자 인덱스 스킬 포함) → 이 레포지토리(skills/)에 PR 제출. 빌드/SDK 스킬 → firecrawl 모노레포(skills/)에 PR 제출. 워크플로우 스킬 → firecrawl/firecrawl-workflows에 PR 제출. 카탈로그(firecrawl/skills)는 읽기 전용이므로, 직접 PR을 제출하지 마십시오.
Firecrawl Claude Code 및 Cursor 플러그인은 별도로 출시되며 이러한 CLI 스킬을 포함하지 않습니다. 여기에서 변경된 내용은 여전히 스킬 카탈로그에 반영됩니다.
스킬을 수동으로 재설치하려면:
firecrawl setup core
firecrawl setup build
firecrawl setup workflows
CLI 업데이트
글로벌 npm, pnpm, bun, yarn 설치는 물론 macOS 및 Linux용 독립형 바이너리도 백그라운드에서 업데이트를 확인합니다. 명령어 실행 시 업데이트를 기다리지 않으며, 업데이트 도구는 stdout에 절대 쓰지 않습니다. 다음 호출에서는 업데이트된 릴리스가 사용되며, 대화형 터미널에서 일회성 알림이 표시됩니다.
전역 패키지 설치의 경우, 설치된 패키지는 안정적인 런처(stable launcher) 역할을 합니다. 업데이트 도구는 npm을 사용하여 새 버전을 ~/.firecrawl/versions/ 아래의 별도 디렉터리에 설치하고, 이를 검증한 후 현재 버전 포인터를 원자적으로(atomically) 전환합니다. 전역 설치를 절대 재작성하거나 실행 중인 명령어에 사용되는 파일을 제거하지 않습니다. 관리되는 버전은 Node 메이저 버전 내에서 공유되므로, 패치 업그레이드 시 저장된 릴리스를 재사용합니다. 런처는 버전을 선택하기 전에 해당 릴리스의 Node 요구 사항을 확인합니다. 자동 패키지 업데이트를 위해서는 npm이 PATH에 사용 가능해야 하며, 그렇지 않은 경우 패키지 관리자의 수동 업데이트 명령어를 사용하십시오. 설치 스크립트는 비활성화되어 있습니다. 의존성은 릴리스 자체보다 늦게 게시된 버전으로 해결되므로, 대기 기간에도 이들이 포함됩니다.
각 전역 설치는 고유의 버전 선택을 가집니다. 유지보수 측면에서는 각 설치에 대해 현재 및 이전 릴리스와 더불어, 실행 중인 CLI 프로세스에서 여전히 사용되는 모든 구형 릴리스를 보존합니다. 이 과정에서 비활성 상태이거나 설치 프로그램이 종료된 지 24시간이 지난 다른 스테이징 디렉터리나 버전은 제거됩니다. 공유 저장소에 있는 다른 기기에 의해 소유된 파일은 신중하게 보존됩니다.
npm으로 재설치하면, 명시적인 다운그레이드를 포함하여 해당 패키지로 런처의 선택이 초기화됩니다. 선택된 버전을 유지하고 싶다면 재설치하기 전에 자동 업데이트를 비활성화하십시오. 업데이트만 비활성화하는 것만으로는 현재 선택된 릴리스가 유지됩니다.
독립형 바이너리(Standalone binaries)는 릴리스 아카이브를 다운로드하여 SHA-256 체크섬과 보고된 버전을 검증한 후, 실행 파일을 원자적으로 대체합니다. 이전 바이너리는 그 옆에 .previous 접미사로 보존됩니다.
새롭게 관찰된 릴리스는 수동 설치 전에 최소 24시간을 기다립니다. 작업자는 이 지연 시간 후에 여전히 최신 릴리스인지 재확인하며, 변경된 후보 버전은 새로운 대기 기간을 시작합니다. 버전 확인은 일반적으로 하루에 한 번씩 새로 고침됩니다. 자동 업데이트는 메이저 버전을 건너뛰거나 프리릴리스(prerelease)를 설치하지 않습니다. 프리릴리스 설치는 고정(pinned) 상태로 유지됩니다.
즉시, 대기 기간을 건너뛰고 새로운 주요 버전으로 업데이트하려면:
네트워크 없이 이전 버전으로 복원하려면:
firecrawl update --rollback
전역 패키지 설치의 경우, 런처는 활성 릴리스를 로드하지 않고도 롤백을 처리하므로, 해당 릴리스가 시작될 수 없는 경우에도 작동합니다. 롤백은 자동 업데이트를 비활성화하여 동일한 릴리스가 즉시 다시 설치되는 것을 방지합니다. 첫 번째 managed-package 롤백은 원래의 package-manager 설치로 돌아갑니다. 이후 업데이트는 이전 관리된 버전으로 롤백할 수 있습니다. 레지스트리의 최신 태그를 되돌린다고 해서 기존 설치가 자동으로 다운그레이드되지는 않습니다.
자동 업데이트는 다음 명령어로 제어합니다:
firecrawl update --disable-auto
firecrawl update --enable-auto
export FIRECRAWL_NO_AUTO_UPDATE=1
CI가 설정된 경우에도 자동 업데이트는 꺼지며, 이는 0 또는 false인 경우가 아니라면 그렇습니다. FIRECRAWL_NO_UPDATE_CHECK=1은 자동 업데이트와 알림을 모두 비활성화합니다. 명시적 업데이트는 이러한 설정에서도 여전히 작동합니다. 실패한 경우 활성 설치는 변경되지 않으며, 재시도하기 전에 뒤로 물러납니다(back off). 자세한 내용은 ~/.firecrawl/auto-update.log에 기록됩니다.
Homebrew 및 기타 시스템 패키지, 프로젝트 로컬 설치, npx와 같은 패키지 러너, 독립형 Windows 바이너리는 선택된 릴리스를 유지하며 적절한 수동 업데이트 지침을 표시합니다. 이러한 설치에서 자동 업데이트를 활성화하는 경우 외부에서 관리됨(externally managed)을 보고합니다. 업데이트를 비활성화하면 공유 사용자 환경설정(shared user preference)이 모든 설치로부터 보호됩니다. 쓰기 권한이 없거나 소유자가 다른 독립형 바이너리는 대체되지 않습니다.
패키지 업데이트는 npm의 레지스트리 구성을 사용합니다. 바이너리 버전 확인은 npm_config_registry를 준수하며, 바이너리 다운로드는 GitHub releases 또는 FIRECRAWL_RELEASES_URL에 설정된 미러를 사용합니다.
Skill updates
대화형 CLI 세션(init, setup 및 -y/--yes init 단축 사용 제외)은 설치된 Firecrawl 스킬이 현재 카탈로그와 다를 경우 상자 형태의 알림을 표시합니다. 이 확인 과정에는 지원 참조 파일이 포함되며 CLI 릴리스와 독립적으로 실행됩니다. 설치 시 어떤 카탈로그 스킬이 존재했는지 기록하므로, 해당 알림은 나중에 게시된 스킬들을 그 우산 스킬(umbrella skill)이 설치된 가족 단위로 한 번만 공지합니다. 설정 과정에서 건너뛴 스킬은 다시 제공되지 않습니다.
영향을 받는 각 가족에는 하나의 명령어가 있습니다: firecrawl setup core, firecrawl setup build, 또는 firecrawl setup workflows. 이 명령어들은 이전에 건너뛰었거나 CLI가 릴리스된 이후 추가된 새로운 스킬들을 포함하여 현재 가족 전체를 설치합니다. npx를 통해 설치할 경우, 실패한 카탈로그 API 검색은 경고와 함께 이 CLI 릴리스의 알려진 이름으로 폴백(fallback)됩니다. 네이티브 설치는 Git 저장소에서 직접 스킬을 발견하며 해당 저장소가 사용 가능해야 합니다. 명시적인 새로 고침(refresh)은 로컬 편집 내용을 포함하여 설치된 파일을 교체하지만, 알림 자체는 이를 변경하지 않습니다.
확인 과정은 ~/.agents/.skill-lock.json에 기록된 전역 설치와 ~/.agents/skills 내의 파일들을 다룹니다. 이 시스템은 카탈로그 결과를 20시간 동안 캐시하며, 최대 12시간마다 한 번 알림을 반복하고, 실패한 확인 과정은 1시간 후에 재시도합니다. 비대화형 실행(Non-interactive runs) 시에는 조용히 넘어갑니다. CLI 및 스킬 업데이트 알림을 모두 비활성화하려면 FIRECRAWL_NO_UPDATE_CHECK=1을 설정하십시오.
MCP 및 웹 기본값
Firecrawl MCP 서버를 편집기(Cursor, Claude Code, VS Code 등)에 설치하려면:
firecrawl login으로 저장된 키를 사용하여 FIRECRAWL_API_KEY를 내보내고 --agent <agent> (또는 --agent all)을 전달하거나, --keyless를 추가하십시오. 이 경우 설정 과정에서 클라이언트 구성 파일에 저장된 키가 기록되지 않습니다.
하나의 클라이언트로는 --agent <agent>를 사용하고, Claude Code, VS Code, Codex, OpenCode, Cursor, Gemini CLI, Windsurf, Antigravity, Amp, Grok Build, Zed, Hermes Agent, 그리고 OpenClaw를 한 번에 구성하려면 --agent all --global을 사용합니다. 최신 클라이언트의 경우 --agent 값은 amp (또는 ampcode, amp-code), grok (또는 grok-build, grok-cli), 그리고 zed입니다. Amp, Grok Build, Zed는 사용자 설정 파일에 작성되므로 --project를 사용하지 않습니다: Amp는 ~/.config/amp/settings.json (또는 기존의 settings.jsonc)로, Grok Build는 ~/.grok/config.toml로, 그리고 Zed는 ~/.config/zed/settings.json ($XDG_CONFIG_HOME/zed/settings.json이 설정된 Linux 환경에서는 이 경로, Windows 환경에서는 %APPDATA%\Zed\settings.json)에 작성됩니다. 이 장치에서 구성할 수 없는 클라이언트(예: openclaw 명령어가 설치되지 않은 경우의 OpenClaw)는 건너뛰고 요약 목록에 나열되며, 명령어는 시도한 클라이언트 중 하나라도 실패했을 때만 오류가 발생합니다. FIRECRAWL_API_KEY가 설정된 경우, Antigravity와 Zed는 환경 변수에서 키를 참조할 검증된 방법이 없기 때문에 건너뛰어지므로 --keyless를 추가하여 포함시킬 수 있습니다.
Firecrawl을 지원되는 AI 에이전트의 기본 웹 공급자로 설정하려면:
이렇게 하면 네이티브 웹 가져오기/검색 기능이 비활성화되어 에이전트가 웹 작업을 Firecrawl을 통해 처리하도록 라우팅됩니다. 대화형으로 실행할 경우, 어떤 하네스(Claude Code, Codex)부터 순서대로 질문하므로 정확히 무엇을 변경할지 선택할 수 있습니다. 모든 항목에 적용하고 선택기를 건너뛰려면 -y를 사용하거나, 특정 항목만 지정하려면 --agent를 사용합니다:
firecrawl setup defaults --agent codex
firecrawl setup defaults -y
이러한 구성 변경 사항을 되돌리려면 (역시 대화형이며, 하네스별로 진행됨):
firecrawl setup defaults --undo
firecrawl setup defaults --undo --agent claude
빠른 시작
명령어를 실행하기만 하면 됩니다. CLI가 필요에 따라 인증을 요청합니다:
firecrawl https://example.com
인증 (Authentication)
최초 실행 시, 인증을 요청받게 됩니다:
🔥 firecrawl cli
Search, scrape, and interact with the web
...
인증 방법 (Authentication Methods)