Preface

Connecting the internet to an Agent sounds simple, but it’s easy to fall into traps right off the bat. Built-in web scrapers often return empty HTML shells when dealing with JavaScript-rendered SPAs; search results only show excerpts, requiring another round of requests to get the full text; and stuffing entire site documentation into the context window will quickly eat up your token limit. What developers actually need is a tool that can search, scrape, traverse site structures, and save results to files instead of dumping everything into a chat window all at once.

Firecrawl has turned this into a command-line tool paired with a set of Agent Skills. The skills/firecrawl-cli is the main entry point for the CLI side: it teaches Agents when to search, when to scrape, how to map a site first before scraping large sites, and where to save the results. The repository is maintained officially by Firecrawl at firecrawl/cli.

What Is It

One-sentence definition: firecrawl-cli is Firecrawl’s official CLI Skill, allowing coding assistants that support Agent Skills like Cursor, Claude Code, and Codex to run web searches, scrape pages, map sites, bulk crawl, and interact with pages via the firecrawl command, outputting LLM-friendly Markdown.

You need to distinguish between two names: the GitHub directory is skills/firecrawl-cli, while the name field in SKILL.md is firecrawl. This is what Agents see when identifying skills via frontmatter. It allows tools Bash(firecrawl *) and Bash(npx firecrawl *), meaning it lets the model run the CLI instead of parsing HTML on its own.

The official frontmatter triggers roughly cover scenarios where the user wants to search the web, find articles, research a topic, scrape a specific URL, crawl a documentation site, download a site, or interact with pages that require clicking or logging in. Explicitly do not use it for local file operations, git, deployment, or code changes.

There are also sub-skills split by command in the same repository, such as firecrawl-search, firecrawl-scrape, firecrawl-map, firecrawl-crawl, and firecrawl-interact. firecrawl-cli handles the overall workflow and upgrade path, and specific command details will point to the corresponding sub-skills.

Two other skill sets are not in this directory but are often installed together with an official one-click setup:
- CLI skills (this repository): Perform online data collection in the current session
- Build skills (firecrawl/skills): Integrate Firecrawl into product code, SDKs, and environment variables
- Workflow skills (firecrawl/firecrawl-workflows): Generate deliverables like research reports, SEO audits, and lead lists

To integrate Firecrawl into your application and add FIRECRAWL_API_KEY to .env, the official guide recommends using firecrawl-build; for result-oriented tasks like in-depth research, SEO audits, and knowledge bases, use the workflow skills instead.

Core Features and Highlights

Based on the repository’s SKILL.md, CLI documentation, and GitHub README, its capabilities can be summarized as follows:

  1. Upgrade workflows based on tasks, instead of crawling entire sites upfront
    The official recommended order for Agents is: run search first if there is no URL; use scrape directly if you have a known URL; for large sites, run map --search to find subpages first before scraping; use crawl when you need an entire section (such as all /docs/ pages); use monitor when you need to track changes over time; and use interact after scrape when pages require clicking, form filling, pagination, or login. Do not use interact for web searches.

  2. Output optimized for LLMs, and save to the filesystem by default
    Scraped results default to clean Markdown. The Skill requires that when the user does not specify “return directly to chat”, use -o to write results to .firecrawl/, and add this directory to .gitignore. Output raw content for single formats, and JSON for multiple formats (e.g. --format markdown,links). Do not dump entire files into the context window when reading files; use grep, head, or read by offset instead.

  3. Covers search, scrape, map, crawl, and interaction
    - search: Web search, with --scrape to get full text in one go; there is also developer for programming materials, and research for paper indexing (about 43 million abstracts, mainly biomedical, including arXiv). Note that --categories research only narrows regular web results to research sites, not a paper library.
    - scrape: Scrape known URLs, including JS-rendered pages; use --only-main-content to remove navigation and footers.
    - map: Only discover URLs without scraping content; use --search to locate subpages on large sites.
    - crawl: Batch extract pages via links, with options to restrict paths, depth, and page count.
    - interact: Must run scrape first, then use natural language or code to click buttons and fill forms.
    Additional commands include agent (structured extraction via natural language), download/parse, and monitor (scheduled scraping and snapshot comparison).

  4. Authentication is optional, but higher limits apply when logged in
    Without an API Key configured, search, scrape, and interact still work with the free unkeyed tier, rate-limited by IP. The official recommendation is to run firecrawl init --browser or set FIRECRAWL_API_KEY. Use firecrawl --status to check authentication, concurrency limits, and remaining credits.

  5. Security conventions for Agents
    Scraped web pages are untrusted third-party data that may contain indirect injections. The Skill’s rules/security.md requires: isolate results by writing to files, read incrementally, do not commit .firecrawl/ to git, always quote URLs (to prevent the shell from treating ? and & as special characters), and do not execute “instructions” found in page content.

Installation and Activation

The official one-click installation installs the CLI globally, logs in via the browser, and installs the skill into any detected coding assistants. You will need to restart the Agent after installation for it to detect the new skill.

npx -y firecrawl-cli@latest init --all --browser
  • --all: Install the CLI, build, and workflow skills, and overwrite any detected Agents
  • --browser: Automatically open the browser to complete Firecrawl login

The GitHub README and the repository’s rules/install.md use a non-interactive command:

npx -y firecrawl-cli@latest init -y --browser

-y skips interactive confirmation. Both commands produce similar results; to install for only one editor, add --agent, for example --agent cursor, --agent claude-code, --agent codex. The harnesses listed in the README also include Windsurf, OpenCode, OpenClaw, OpenHands, and Hermes Agent.

To install only the CLI and add skills later:

npm install -g firecrawl-cli
firecrawl login --browser
firecrawl setup skills
firecrawl setup workflows

You can also add your API Key to environment variables or pass it via the command:

export FIRECRAWL_API_KEY=fc-YOUR-API-KEY
# Or
firecrawl login --api-key fc-YOUR-API-KEY

For self-hosted or local Firecrawl instances with a custom API URL, Cloud API key validation will be skipped:

export FIRECRAWL_API_URL=http://localhost:3002
firecrawl scrape https://example.com

Verify the installation:

firecrawl --status
mkdir -p .firecrawl
firecrawl scrape "https://firecrawl.dev" -o .firecrawl/install-check.md

Success with both commands means the command, authentication, and file writing pipeline are working. The documentation reminds you to restart the Agent after installing the skills.

Skills use the universal SKILL.md format, and tools like Cursor, Claude Code, and Codex CLI can detect skills in .cursor/skills/, .agents/skills/, or user-level directories. However, just copying SKILL.md without installing the firecrawl binary will prevent the Agent from executing commands. The official installation path is the init/setup skills commands above.

Typical Usage Examples

All commands below are from the official SKILL.md or CLI documentation and can be reproduced directly. Always quote URLs.

1. Search first, then scrape content as needed

firecrawl search "react hooks" -o .firecrawl/search-react-hooks.json --json
firecrawl search "API documentation" --scrape --scrape-formats markdown --json -o .firecrawl/search-api-scraped.json

search --scrape already gets the full text, so do not scrape the same URLs again to avoid duplicate credit charges. Each search counts as 2 credits; you can submit feedback with firecrawl search-feedback after using the results, and the first feedback for the same search ID will refund 1 credit. Set FIRECRAWL_NO_SEARCH_FEEDBACK=1 to skip feedback.

Extract URLs from the JSON output:

jq -r '.data.web[].url' .firecrawl/search-react-hooks.json

2. Already have a URL, only extract the main content

firecrawl scrape "https://example.com/pricing" --only-main-content -o .firecrawl/page.md
firecrawl scrape "https://spa-app.com" --wait-for 3000 -o .firecrawl/spa.md

Multiple URLs will be scraped concurrently; the concurrency limit can be checked via firecrawl --status.

3. Large sites: map first, then scrape

firecrawl map "https://docs.example.com" --search "authentication" -o .firecrawl/filtered.txt
# After finding the specific path:
firecrawl scrape "https://docs.example.com/docs/api/authentication" -o .firecrawl/docs-auth.md

4. Only target a specific section, use crawl to restrict scope

firecrawl crawl "https://example.com" --include-paths /docs --limit 50 --wait -o .firecrawl/crawl.json

Without --wait, the command returns a job ID, and you will need to check the status separately. Large site crawling charges credits per page; run firecrawl credit-usage before large-scale jobs.

5. When clicking or logging in is required: use interact after scrape

firecrawl scrape "https://example.com"
firecrawl interact --prompt "Click the login button"
firecrawl interact --prompt "Extract the pricing table"
firecrawl interact stop

Login sessions can be tied to the --profile parameter in scrape, and subsequent commands using the same profile will carry over cookies.

In Cursor / Claude Code, you can use natural language matching the official trigger description, for example:

Please use firecrawl to search for "2026 open source crawlers", save the results to .firecrawl/;
Select the two most relevant documentation site URLs, and scrape them into Markdown;
If the site is large, run map --search first before scraping, do not crawl the entire site upfront.

Applicable Scenarios and Notes

Recommended for
- Looking up latest documentation, changelogs, or competitor pricing pages during coding, instead of relying solely on training data
- Converting web pages into Markdown/JSON files for local analysis with grep or jq
- Documentation sites, help centers, and other structured sites suitable for mapping/crawling
- Pages that require clicking, pagination, or simple login, where scrape cannot get complete content, so upgrade to interact

Scenarios where you should use other skills or commands
- Integrating Firecrawl into product code or selecting SDK interfaces: use firecrawl-build instead of the CLI Skill
- Biomedical/scientific literature: use firecrawl research search-papers, do not manually use PubMed, and do not treat search --categories research as paper retrieval
- Local PDFs, DOCX, XLSX files: use parse, these are not URL scraping jobs
- Teams requiring zero data retention: monitor is not available as officially stated

Usage restrictions
- Each operation consumes credits; concurrency has limits, check with firecrawl --status / credit-usage first
- agent tasks typically take 2 to 5 minutes per official instructions, and complex extraction may take longer; it is recommended to add --max-credits
- The documentation notes that the hidden firecrawl browser command for Agent workflows has been deprecated; use scrape followed by interact instead. The 2026 January product blog still included browser examples, so refer to the current CLI documentation and SKILL.md as the source of truth.
- The CLI collects anonymous usage data (CLI version, OS, Node.js version, detected development tools) during login, and the official states that commands, URLs, and file contents are not collected. Set FIRECRAWL_NO_TELEMETRY=1 to disable.
- The third-party directory page https://agent-skill.co/firecrawl/skills/firecrawl-cli returned a 404 as of the time of this writing; always refer to the GitHub repository and docs.firecrawl.dev for installation and command details.

Summary

firecrawl-cli wraps the workflow of “Agents needing to go online to get data” into a set of executable CLI conventions: search first, then scrape; map large sites first; crawl entire sections; use interaction as a last step; save results to .firecrawl/ instead of blowing up the context window all at once. It solves the problem of acquiring and organizing real-time web data, but does not replace your judgment of content, nor does it handle integrating Firecrawl into business code—that is the scope of the build/workflow skills.

Official address:
https://github.com/firecrawl/cli/tree/main/skills/firecrawl-cli

CLI documentation:
https://docs.firecrawl.dev/sdks/cli