firecrawl-axi

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

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

Authentication

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_KEY is Firecrawl's documented key variable. When unset, the CLI runs keyless: search, scrape, and parse work within daily anonymous limits, and every gated command fails fast with a structured AUTH_REQUIRED error.
• FIRECRAWL_MCP_URL is 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.

Commands

# 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.

Safety gates

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)
• crawl without --limit (unbounded crawls can consume thousands of credits; a bounded crawl needs no confirm)
• monitors create, monitors update, monitors run
• monitors 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.

Output and exit codes

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.

Development

npm test          # vitest, all HTTP mocked, no credentials needed
npm run build
npm run typecheck

UNRESOLVED / intentionally not implemented

• 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/--schema and agent cover the space.
• Parse upload-handoff payload: verified live against the hosted server: phase one returns a GCS signed-policy form (uploadUrl + ordered fields, file part last) plus a command string; the executor prefers the structured form via fetch and falls back to an allowlisted, shell-free curl argv. --keep-upload prints the handoff without executing it.
• Monitor --body advanced form: monitors create exposes the documented simple form; the advanced body form is reachable through monitors update --body after creation.
• Self-hosted Firecrawl: the CLI targets the hosted MCP endpoint. Self-hosted deployments speak stdio MCP, which a stateless HTTP client cannot reach.

Official documentation used

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

License

MIT