@benvargas/pi-firecrawl

Firecrawl tools for pi, the AI coding agent.

Provides focused Firecrawl REST API access for:

• firecrawl_scrape
• firecrawl_map
• firecrawl_search

Features

• Scrape (firecrawl_scrape) — Scrape a single URL
• Map (firecrawl_map) — Discover URLs on a site
• Search (firecrawl_search) — Search the web and optionally scrape results
• Tool allowlist — Enable/disable tools via tools config
• Configurable limits — Client-side truncation with configurable max bytes/lines
• Multiple config sources — JSON config, environment variables, or CLI flags
• Direct REST API — Simple, fast, no protocol overhead

Installation

pi install npm:@benvargas/pi-firecrawl

Or try without installing:

pi -e npm:@benvargas/pi-firecrawl

Setup

Get an API key from firecrawl.dev and configure it using one of these methods.

Option 1: Environment Variable

export FIRECRAWL_API_KEY="your_firecrawl_api_key"
pi

Option 2: JSON Config

Create ~/.pi/agent/extensions/firecrawl.json:

{
  "url": "https://api.firecrawl.dev",
  "apiKey": "your_firecrawl_api_key",
  "headers": null,
  "tools": ["firecrawl_scrape", "firecrawl_map", "firecrawl_search"],
  "timeoutMs": 30000,
  "maxBytes": 51200,
  "maxLines": 2000
}

If you want to disable search, remove it from the tools array.

Option 3: CLI Flags

pi --firecrawl-api-key=your_firecrawl_api_key

Usage

Once installed, the AI can use these tools when appropriate:

"Scrape https://example.com and get the main content"
"Map docs.example.com and list likely API pages"
"Search for React tutorials and summarize top results"

Tools

firecrawl_scrape

Scrape a single URL.

Parameter	Description	Default
url	Target URL (required)	—
formats	Output formats array	—
onlyMainContent	Extract only main content	—
waitFor	Wait time in milliseconds	—
timeout	Request timeout	—
mobile	Use mobile viewport	—
includeTags	Tags to include	—
excludeTags	Tags to exclude	—
skipTlsVerification	Skip TLS verification	—
piMaxBytes	Client-side max bytes override	—
piMaxLines	Client-side max lines override	—

firecrawl_map

Discover URLs on a site.

Parameter	Description	Default
url	Base URL to map (required)	—
search	Search query to filter URLs	—
sitemap	Sitemap handling mode (include, skip, only)	—
includeSubdomains	Include subdomains	—
limit	Maximum URLs to return	—
ignoreQueryParameters	Ignore query parameters	—
piMaxBytes	Client-side max bytes override	—
piMaxLines	Client-side max lines override	—

firecrawl_search

Search the web and optionally scrape results.

Parameter	Description	Default
query	Search query (required)	—
limit	Maximum results	—
lang	Language code	—
country	Country code	—
scrapeOptions	Scrape options for results	—
piMaxBytes	Client-side max bytes override	—
piMaxLines	Client-side max lines override	—

Configuration

Config File Locations

Config files are loaded in order (first match wins):

1. Path from --firecrawl-config flag
2. Path from FIRECRAWL_CONFIG environment variable
3. ./.pi/extensions/firecrawl.json (project-level)
4. ~/.pi/agent/extensions/firecrawl.json (global)

If none exist, the extension writes a default config to the global path with apiKey set to null.

Config File Format

{
  "url": "https://api.firecrawl.dev",
  "apiKey": null,
  "headers": null,
  "tools": ["firecrawl_scrape", "firecrawl_map", "firecrawl_search"],
  "timeoutMs": 30000,
  "maxBytes": 51200,
  "maxLines": 2000
}

Environment Variables

Variable	Description	Default
FIRECRAWL_URL	API base URL	https://api.firecrawl.dev
FIRECRAWL_API_KEY	Firecrawl API key (Bearer token)	—
FIRECRAWL_TIMEOUT_MS	Request timeout (ms)	30000
FIRECRAWL_TOOLS	Comma-separated tool list	—
FIRECRAWL_MAX_BYTES	Max bytes to keep from output	51200
FIRECRAWL_MAX_LINES	Max lines to keep from output	2000
FIRECRAWL_CONFIG	Path to JSON config file	—

CLI Flags

Flag	Description
--firecrawl-url	Override the Firecrawl API base URL
--firecrawl-api-key	Firecrawl API key
--firecrawl-timeout-ms	HTTP timeout (milliseconds)
--firecrawl-config	Path to JSON config file
--firecrawl-tools	Comma-separated tool list
--firecrawl-max-bytes	Max bytes to keep from output
--firecrawl-max-lines	Max lines to keep from output

Output Truncation

Tool output is automatically truncated to prevent context window overflow:

• Default limits: 51200 bytes and 2000 lines
• Client overrides: models can request piMaxBytes/piMaxLines (clamped to configured max)
• Temp files: when truncated, full output is saved to a temp file with the path included in the response

Requirements

• pi v0.51.0 or later
• Firecrawl API key from firecrawl.dev

Uninstall

pi remove npm:@benvargas/pi-firecrawl

License

MIT