Firecrawl CLI 是一个面向网页抓取、搜索与浏览器自动化的命令行工具，其特点是返回针对 LLM 上下文窗口优化的干净 markdown，便于 AI 代理直接使用网页内容。完整选项可通过 firecrawl --help 或 firecrawl <command> --help 查看。
【前置条件】 使用前必须已安装并完成认证，可用 firecrawl --status 检查。状态信息包含 CLI 版本、认证方式（示例为 FIRECRAWL_API_KEY）、并发使用情况（如 0/100 jobs 的并行抓取上限）以及剩余积分（如 500,000 credits）。并发值为允许的最大并行任务数，每次 scrape/crawl 会消耗积分。若未就绪，资料指向 rules/install.md；输出处理规范见 rules/security.md。
【用途与命令】 资料按需求给出升级式工作流：尚未有具体 URL 时用 search 找页面、回答问题或发现来源；已有 URL 时用 scrape 直接提取内容；大型站点或需特定子页面时用 map --search 定位 URL 再 scrape；需要整站某栏目（如全部 /docs/）批量内容时用 crawl；内容需要点击、填表、翻页、多步导航或登录时用 browser；需要从复杂站点提取结构化数据时用 agent。download 是 map + scrape 的组合便利命令，可将整站保存为本地文件。
【主要能力】
- search：网页搜索，可选抓取全文；支持 --limit、--sources（web,images,news）、--categories（github,research,pdf）、--tbs 时间范围（qdr:h/d/w/m/y）、--location、--country、--scrape、--scrape-formats、-o。
- scrape：抓取一个或多个 URL，多 URL 并发进行、每个结果分别保存；支持 -f 指定格式（markdown,html,rawHtml,links,screenshot,json）、-H、--only-main-content、--wait-for 毫秒、--include-tags、--exclude-tags、-o。
- map：发现站点 URL；支持 --limit、--search、--sitemap（include|skip|only）、--include-subdomains、--json、-o。
- crawl：批量抓取站点；支持 --wait、--progress、--limit、--max-depth、--include-paths、--exclude-paths、--delay、--max-concurrency、--pretty、-o，可用 job-id 查询运行状态。
- agent：AI 驱动的自主提取（约 2-5 分钟）；支持 --urls、--model（spark-1-mini|spark-1-pro）、--schema/--schema-file 指定 JSON Schema、--max-credits、--wait、--pretty、-o。
- browser：在远程沙箱环境运行云端 Chromium 会话；核心 agent-browser 命令包括 open、snapshot -i（获取带 @ref 的可交互元素）、screenshot、click、type、fill、scrape、scroll、wait、eval；会话管理有 launch-session --ttl、list、close；支持 --ttl、--ttl-inactivity、--session、--profile、--no-save-changes、-o。简写命令在无会话时自动启动。若浏览器报 forbidden 错误，可能需要新建会话，因为旧会话可能已过期。
- credit-usage：查看积分使用情况，支持 --json --pretty -o。
【使用方式与示例】 资料强调优先用 scrape，它能处理静态页面和 JS 渲染的 SPA；browser 仅用于需要交互的场景，且绝不用 browser 做网页搜索（应使用 search）。应避免重复抓取：search --scrape 已获取全文，不必再抓这些 URL；再次抓取前先检查 .firecrawl/ 中已有数据。 示例工作流：search "site:docs.example.com authentication API" 找到文档域名 → map https://docs.example.com --search "auth" 找到具体页面 → scrape 该页面获取内容。翻页场景：scrape 只显示前 10 项且无下一页链接时，用 browser open、snapshot -i 找到分页按钮、click 后 browser "scrape" -o .firecrawl/products-p2.md 提取第二页。登录场景：browser launch-session --profile my-app 创建命名 profile，导航登录页、snapshot -i 定位表单、fill 填入邮箱、click 登录、wait 2 等待跳转、close；之后用同一 profile 重新连接即可保持 cookie 并抓取受保护内容，--no-save-changes 可只读重连。 输出组织：除非用户要求直接返回上下文，否则用 -o 写入 .firecrawl/，并将 .firecrawl/ 加入 .gitignore；URL 始终加引号，避免 shell 将 ? 和 & 解析为特殊字符。命名约定如 .firecrawl/search-{query}.json、.firecrawl/search-{query}-scraped.json、.firecrawl/{site}-{path}.md。不要一次性读取整个输出文件，应使用 grep、head、wc -l 等增量读取。单一格式输出原始内容，多格式（如 --format markdown,links）输出 JSON。可用 jq 处理结果，如 jq -r '.data.web[].url'。 并行化：独立操作可并行，并行前用 firecrawl --status 查看并发上限；浏览器独立任务可用 --session <id> 启动多个会话并行。
【download 批量下载】 先 map 发现页面，再逐个抓取到 .firecrawl/ 下的嵌套目录。所有 scrape 选项都适用于 download，始终加 -y 跳过确认。支持 --limit、--search、--include-paths、--exclude-paths、--allow-subdomains，以及 -f、-H、-S、--screenshot、--full-page-screenshot、--only-main-content、--include-tags、--exclude-tags、--wait-for、--max-age、--country、--languages。示例可过滤指定栏目、排除多语言翻译路径，并可同时生成 markdown、links 与截图文件。
【适用场景】 适合 AI 代理进行网页资料收集、API 文档获取、竞品调研、站点批量归档与需要登录或交互的页面内容提取。
【限制】 需预先安装并认证，抓取和爬取消耗积分，受并发上限约束，超出时应控制并行数。