AXI-compliant CLI for Firecrawl web data — scrape, search, map, crawl, parse, agent research, papers, and monitors over the hosted Firecrawl MCP server. Built against the AXI design principles, spec axi/1.0-2026-07, Node.js 20+, and TypeScript.
Phase A wraps 24 of the 27 hosted Firecrawl MCP tools behind agent-ergonomic commands. It intentionally does not expose the deprecated extract tool, the feedback endpoints, or the live interact browser sessions (see UNRESOLVED).
Install the firecrawl-axi skill in the Agent Skills format with npx skills:
npx -y skills@latest add brycehamrick/firecrawl-axi --skill firecrawl-axi --agent opencode -g -y
That is the entire setup - no npm install needed. The skill teaches your agent to run firecrawl-axi through npx -y firecrawl-axi@latest, so the CLI comes along on demand. -g installs the skill user-level for all projects; drop it to install for the current project only. Swap --agent opencode for your agent of choice (or --agent '*'); the flag keeps the install non-interactive - plain -g prompts for target agents and fails in a non-TTY.
Other ways to install:
# zero setup - any capable agent can run the CLI directly
npx -y firecrawl-axi@latest scrape https://example.com
# global install (only needed for the `setup hooks` ambient context)
npm install -g firecrawl-axi
firecrawl-axi setup hooks
For development:
git clone https://github.com/brycehamrick/firecrawl-axi.git
cd firecrawl-axi
npm install
node bin/firecrawl-axi.js # runs the committed dist/ directly
npm run build # rebuild dist/ from src/ after changes
npm test
The CLI talks to the hosted Firecrawl MCP server at https://mcp.firecrawl.dev/v2/mcp using stateless MCP tools/call requests. Three access modes, resolved from the environment:
export FIRECRAWL_API_KEY="fc-..." # optional; unlocks the full tool surface
export FIRECRAWL_MCP_URL="https://mcp.firecrawl.dev/v2/mcp" # optional override
FIRECRAWL_API_KEYis Firecrawl's documented key variable. When unset, the CLI runs keyless:search,scrape, andparsework within daily anonymous limits, and every gated command fails fast with a structuredAUTH_REQUIREDerror.FIRECRAWL_MCP_URLis this package's own override (Firecrawl documents the endpoint but not an environment-variable name for overriding it). It must use HTTPS and must not contain credentials, query parameters, or fragments. No localhost exception.- The key is sent only as a request header, never in argv, request bodies, or output, and is scrubbed from every error message.
# Read one page: markdown (default), targeted answers, or schema extraction
firecrawl-axi scrape https://example.com
firecrawl-axi scrape https://example.com --query "what is the pricing?"
firecrawl-axi scrape https://example.com --prompt "extract the title" --schema '{"title":"string"}'
# Search: web, news, images, developer index, research-affiliated, pdf
firecrawl-axi search "rust web frameworks comparison" --limit 10
firecrawl-axi search "react hooks error" --category developer
firecrawl-axi search "site:news.ycombinator.com firecrawl" --tbs qdr:m
# Discover URLs without fetching pages
firecrawl-axi map https://docs.firecrawl.dev --search "mcp" --limit 200
# Crawl a site (bounded by --limit, or explicitly confirmed unbounded)
firecrawl-axi crawl https://docs.firecrawl.dev --limit 20 --with-content
firecrawl-axi crawl status <crawl-id>
# Parse local documents (PDF/DOCX/XLSX/HTML...) with transparent upload handoff
firecrawl-axi parse report.pdf --max-pages 20
firecrawl-axi parse contract.docx --query "termination notice period"
# Developer + GitHub research indexes
firecrawl-axi dev-search "vitest mock fetch not a function"
firecrawl-axi github-search "streamable http mcp session handling"
# Autonomous research jobs (paid, async)
firecrawl-axi agent start --prompt "Find the top 5 AI scraping startups and their funding" --confirm
firecrawl-axi agent status <job-id> --full
# Research Index literature (PubMed, bioRxiv, medRxiv, arXiv)
firecrawl-axi papers search "attention mechanisms" --from 2023-01-01
firecrawl-axi papers read arxiv:1706.03762 --question "how is multi-head attention computed?"
firecrawl-axi papers inspect doi:10.1016/j.neunet.2025.108095
firecrawl-axi papers related arxiv:1706.03762 --intent "efficient attention variants"
# Monitors: recurring checks with change alerts
firecrawl-axi monitors list
firecrawl-axi monitors create --page https://example.com/pricing --goal "alert on price changes" --confirm
firecrawl-axi monitors checks <monitor-id> --status completed
firecrawl-axi monitors check <monitor-id> <check-id>
# Ambient context for agent sessions (Claude Code, Codex, OpenCode)
firecrawl-axi setup hooks
firecrawl-axi setup status
Every command supports --json for machine-readable output and --full to escape content truncation. Running firecrawl-axi with no arguments prints a live home view (auth mode, monitor summary, command cheatsheet), not help text.
Every command that creates paid work or mutates account state requires --confirm for that single invocation — no prompts, no remembered consent:
agent start(dynamic credit billing)crawlwithout--limit(unbounded crawls can consume thousands of credits; a bounded crawl needs no confirm)monitors create,monitors update,monitors runmonitors delete— irreversible, called out explicitly in the gate message
Reads (scrape, search, map, parse, dev-search, github-search, papers ..., monitors list/get/checks/check, crawl status, agent status) never require confirmation. Missing confirmation and invalid input fail before any network request.
Compact TOON is the default on stdout, with minimal default schemas, pre-computed aggregates (count, credits, check summaries), size-hinted truncation ((truncated, 2847 chars total — use --full)), definitive empty states (0 results, 0 monitors), and help[] next-step suggestions after each output. Errors are structured objects with an actionable help[], written to stdout.
| Code | Meaning |
|---|---|
0 |
Success or informational help |
2 |
Usage, validation, missing confirmation, unknown flags |
1 |
Runtime, network, timeout, auth, rate-limit, credit, or Firecrawl API errors |
Error codes: VALIDATION_ERROR, AUTH_REQUIRED, RATE_LIMITED, PAYMENT_REQUIRED, NOT_FOUND, NETWORK_ERROR, TIMEOUT, API_ERROR.
npm test # vitest, all HTTP mocked, no credentials needed
npm run build
npm run typecheck
- Interact sessions (
firecrawl_interact,firecrawl_interact_stop): live browser operation with persistent side effects on external sites deserves its own combined-operation design (click --query-style, as chrome-devtools-axi does for snapshots). Planned for a later phase. - Feedback endpoints (
firecrawl_search_feedback,firecrawl_feedback): quality telemetry, not agent task work. Agents that want to rate results can do it through the MCP server directly. - Deprecated extract (
firecrawl_extract): Firecrawl marks it deprecated;scrape --prompt/--schemaandagentcover the space. - Parse upload-handoff payload: verified live against the hosted server: phase one returns a GCS signed-policy form (
uploadUrl+ orderedfields, file part last) plus acommandstring; the executor prefers the structured form viafetchand falls back to an allowlisted, shell-freecurlargv.--keep-uploadprints the handoff without executing it. - Monitor
--bodyadvanced form:monitors createexposes the documented simple form; the advanced body form is reachable throughmonitors update --bodyafter creation. - Self-hosted Firecrawl: the CLI targets the hosted MCP endpoint. Self-hosted deployments speak stdio MCP, which a stateless HTTP client cannot reach.
Reviewed against Firecrawl's live documentation and direct probes of the hosted MCP server (tools/list, tools/call):
- Firecrawl MCP server — endpoint, auth modes, keyless surface
- MCP tools — tool availability matrix and operating behavior
- Scrape, Search, Crawl, Parse
- Agent — job lifecycle, statuses, credits
- Monitoring — monitor object, check summaries, schedules
- Research Index / Developer Index
MIT