CLI Reference

Updated Feb 2026

The official Firecrawl command-line interface. Supports scraping, crawling, mapping, searching, agent-based extraction, and cloud browser sessions directly from the terminal. Works in shell scripts, CI/CD pipelines, and with AI coding agents.


Package	`firecrawl-cli`
npm	npmjs.com/package/firecrawl-cli
API Versions	v1, v2
Source	github.com/firecrawl/cli

Installation

Global install:

bash

npm install -g firecrawl-cli

For AI agents (one-line setup):

bash

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

The --all flag installs the CLI configuration to all detected AI agents. The --browser flag opens a browser for automatic authentication.

Authentication

bash

# Interactive mode
firecrawl login

# Browser authentication (recommended)
firecrawl login --browser

# Direct API key
firecrawl login --api-key fc-YOUR-API-KEY

# Environment variable
export FIRECRAWL_API_KEY=fc-YOUR-API-KEY

Configuration Management

bash

# View current settings
firecrawl view-config

# Check status (auth, concurrency, credits)
firecrawl --status

# Set custom API URL (for self-hosted)
firecrawl config --api-url http://localhost:3002

# Clear credentials
firecrawl logout

Self-Hosted Usage

bash

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

Commands

scrape

Extracts content from a single URL. This is the default command -- you can omit the scrape keyword. See Scrape feature docs for API details.

Usage:

bash

# Both are equivalent
firecrawl https://example.com
firecrawl scrape https://example.com

Flags:

Flag	Short	Description
`--url <url>`	`-u`	Target URL
`--format <formats>`	`-f`	Output formats (comma-separated)
`--html`	`-H`	Shortcut for HTML format
`--only-main-content`	--	Remove navigation, footer, sidebar
`--wait-for <ms>`	--	Wait for JavaScript rendering
`--screenshot`	--	Capture page screenshot
`--include-tags <tags>`	--	HTML tags to keep
`--exclude-tags <tags>`	--	HTML tags to remove
`--output <path>`	`-o`	Save to file
`--json`	--	Force JSON output
`--pretty`	--	Pretty-print JSON
`--timing`	--	Show performance data

Available formats: markdown (default), html, rawHtml, links, screenshot, json, images, summary, changeTracking, attributes, branding

Examples:

bash

# Default markdown output
firecrawl https://example.com

# HTML format
firecrawl https://example.com --html

# Multiple formats
firecrawl https://example.com --format markdown,links

# Main content only, saved to file
firecrawl scrape https://example.com --only-main-content -o content.md

# Screenshot capture
firecrawl https://example.com --screenshot

# Wait for JS rendering
firecrawl https://example.com --wait-for 3000

# Pipe to other tools
firecrawl https://example.com | head -50
firecrawl https://example.com > output.md

search

Performs a web search with optional result scraping. See Search feature docs for API details.

Usage:

bash

firecrawl search "<query>"

Flags:

Flag	Description
`--limit <number>`	Max results (default: 5, max: 100)
`--sources <sources>`	Result types: `web`, `images`, `news`
`--categories <categories>`	Filter: `github`, `research`, `pdf`
`--tbs <value>`	Time filter: `qdr:h` (hour), `qdr:d` (day), `qdr:w` (week), `qdr:m` (month), `qdr:y` (year)
`--location <location>`	Geographic targeting (e.g., `"Berlin,Germany"`)
`--country <code>`	ISO country code (default: US)
`--timeout <ms>`	Request timeout (default: 60000)
`--ignore-invalid-urls`	Exclude invalid URLs from results
`--scrape`	Scrape the search results
`--scrape-formats <formats>`	Formats for scraped content
`--only-main-content`	Main content only when scraping
`--json`	JSON output
`--output <path>`	Save to file

Examples:

bash

# Basic search
firecrawl search "web scraping tutorials"

# Limit results
firecrawl search "AI news" --limit 10

# Multiple sources
firecrawl search "AI" --sources web,news,images

# Category filter
firecrawl search "react hooks" --categories github

# Recent results only (past day)
firecrawl search "tech news" --tbs qdr:d

# Location-based search
firecrawl search "restaurants" --location "Berlin,Germany"

# Search and scrape results
firecrawl search "documentation" --scrape --scrape-formats markdown -o results.json

# Pretty JSON output
firecrawl search "machine learning" --pretty

crawl

Crawls a website from a starting URL. See Crawl feature docs for API details.

Usage:

bash

firecrawl crawl <url>
firecrawl crawl <job-id>  # Check status of existing job

Flags:

Flag	Description
`--url <url>`	Starting URL
`--wait`	Wait for crawl to complete
`--progress`	Show progress bar
`--poll-interval <seconds>`	Status check interval (default: 5)
`--timeout <seconds>`	Maximum wait time
`--status`	Check existing job status
`--limit <number>`	Maximum pages to crawl
`--max-depth <number>`	Maximum crawl depth
`--include-paths <paths>`	Comma-separated paths to include
`--exclude-paths <paths>`	Comma-separated paths to exclude
`--sitemap <mode>`	Sitemap mode: `include`, `skip`, `only`
`--allow-subdomains`	Include subdomains in crawl
`--allow-external-links`	Follow external URLs
`--crawl-entire-domain`	Crawl the full domain
`--ignore-query-parameters`	Deduplicate URLs by ignoring query params
`--delay <ms>`	Delay between requests
`--max-concurrency <n>`	Maximum concurrent requests
`--output <path>`	Save to file
`--pretty`	Pretty-print JSON

Examples:

bash

# Start a crawl and wait
firecrawl crawl https://example.com --wait

# With progress bar
firecrawl crawl https://example.com --wait --progress

# Limit scope
firecrawl crawl https://example.com --limit 100 --max-depth 3 --wait

# Include/exclude paths
firecrawl crawl https://example.com --include-paths /blog,/docs --wait
firecrawl crawl https://example.com --exclude-paths /admin,/login --wait

# Rate limiting
firecrawl crawl https://example.com --delay 1000 --max-concurrency 2 --wait

# Sitemap-only crawl
firecrawl crawl https://example.com --sitemap only --wait

# Custom polling
firecrawl crawl https://example.com --wait --poll-interval 10 --timeout 300

# Check job status
firecrawl crawl <job-id>

map

Discovers all URLs on a website. See Map feature docs for API details.

Usage:

bash

firecrawl map <url>

Flags:

Flag	Description
`--url <url>`	Target URL
`--limit <number>`	Maximum URLs to discover
`--search <query>`	Filter URLs by search query
`--sitemap <mode>`	Sitemap handling: `include`, `skip`, `only`
`--include-subdomains`	Include subdomain URLs
`--ignore-query-parameters`	Deduplicate URLs
`--wait`	Wait for completion
`--timeout <seconds>`	Maximum wait time
`--json`	JSON output
`--output <path>`	Save to file
`--pretty`	Pretty-print JSON

Examples:

bash

# Basic URL discovery
firecrawl map https://example.com

# Limit results
firecrawl map https://example.com --limit 500

# Filter by keyword
firecrawl map https://example.com --search "blog"

# Include subdomains
firecrawl map https://example.com --include-subdomains

# Sitemap-only
firecrawl map https://example.com --sitemap only

# Save to file
firecrawl map https://example.com --wait --timeout 60 -o urls.json

# Count URLs
firecrawl map https://example.com | wc -l

agent

Natural language data gathering from the web. The agent autonomously searches, navigates, and extracts data. See Agent feature docs for API details.

Usage:

bash

firecrawl agent "<prompt>" --wait

Flags:

Flag	Description
`--urls <urls>`	Focus URLs (comma-separated)
`--model <model>`	`spark-1-mini` (default) or `spark-1-pro`
`--schema <json>`	Inline JSON schema for structured output
`--schema-file <path>`	Path to JSON schema file
`--max-credits <number>`	Credit spending limit
`--status`	Check existing job status
`--wait`	Wait for completion
`--poll-interval <seconds>`	Status check interval
`--timeout <seconds>`	Maximum wait time
`--output <path>`	Save to file
`--json`	JSON output

Examples:

bash

# Basic agent query
firecrawl agent "Find top 5 AI startups and their funding" --wait

# With specific URLs
firecrawl agent "Compare pricing plans" \
  --urls https://slack.com/pricing,https://teams.microsoft.com/pricing \
  --wait

# With inline schema
firecrawl agent "Get company info" \
  --urls https://example.com \
  --schema '{"name":"string","founded":"number"}' \
  --wait

# With schema file
firecrawl agent "Get product details" \
  --urls https://example.com \
  --schema-file schema.json \
  --wait

# Using pro model
firecrawl agent "Competitive analysis" --model spark-1-pro --wait

# With credit limit
firecrawl agent "Gather contact info" --max-credits 100 --wait

# Check job status
firecrawl agent <job-id> --status

# Custom polling
firecrawl agent "Summarize blog posts" --wait --poll-interval 10 --timeout 300

browser

Cloud browser sessions with Chromium. Launch, execute commands, and manage sessions. See Browser feature docs for API details.

Session management:

bash

# Launch a session
firecrawl browser launch-session

# With options
firecrawl browser launch-session --ttl 600 --stream
firecrawl browser launch-session --ttl 120 --ttl-inactivity 60

# With browser profile
firecrawl browser launch-session --profile my-profile
firecrawl browser launch-session --profile my-profile --no-save-changes

# List sessions
firecrawl browser list
firecrawl browser list active --json

# Close sessions
firecrawl browser close
firecrawl browser close --session <id>

Launch flags:

Flag	Description
`--ttl <seconds>`	Session duration (default: 300, range: 30-3600)
`--ttl-inactivity <seconds>`	Auto-close on inactivity (range: 10-3600)
`--profile <name>`	Browser profile name
`--no-save-changes`	Load profile without saving changes
`--stream`	Enable live view streaming

Execute commands:

bash

# Default bash mode
firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"
firecrawl browser execute "click @e5"
firecrawl browser execute "scrape"

# Bash mode (explicit)
firecrawl browser execute --bash "agent-browser snapshot"

# Python mode (Playwright)
firecrawl browser execute --python 'await page.goto("https://example.com"); print(await page.title())'

# JavaScript mode (Playwright)
firecrawl browser execute --node 'await page.goto("https://example.com"); console.log(await page.title());'

# Target specific session
firecrawl browser execute --session <id> --python 'print(await page.title())'

# Save output
firecrawl browser execute "scrape" -o result.txt

Execute flags:

Flag	Description
`--bash`	Bash command mode (default)
`--python`	Playwright Python code
`--node`	Playwright JavaScript code
`--session <id>`	Target specific session
`--output <path>`	Save output to file
`--json`	JSON format output

Python Playwright example:

bash

firecrawl browser execute --python '
await page.goto("https://news.ycombinator.com")
items = await page.query_selector_all(".titleline > a")
for item in items[:5]:
    print(await item.text_content())
'

credit-usage

Check your Firecrawl credit balance and usage.

bash

firecrawl credit-usage
firecrawl credit-usage --json --pretty

version

Display the CLI version.

bash

firecrawl version
firecrawl --version

Global Options

These options work with any command.

Option	Short	Description
`--status`	--	Show version, auth, concurrency, and credits
`--api-key <key>`	`-k`	Override API key for this command
`--api-url <url>`	--	Override API URL for this command
`--help`	`-h`	Show help for any command
`--version`	`-V`	Show CLI version

Output Handling

The CLI outputs to stdout by default, making it pipeable and composable with other tools.

Output rules:

Single format requested: raw content is printed directly
Multiple formats requested: output switches to JSON

Piping and redirection examples:

bash

# Pipe to other tools
firecrawl https://example.com | head -50

# Save to file
firecrawl https://example.com > output.md

# Multiple formats to JSON file
firecrawl https://example.com --format markdown,links --pretty -o data.json

# Process search results with jq
jq -r '.data.web[].url' search-results.json

# Count mapped URLs
firecrawl map https://example.com | wc -l

Telemetry

The CLI collects anonymous usage telemetry to improve the product.

Data collected: CLI version, OS, Node.js version, development tool detection.

Data NOT collected: Command data, URLs, file contents, API keys.

Disable telemetry:

bash

export FIRECRAWL_NO_TELEMETRY=1

SDKs Overview -- Compare all available SDKs
Python SDK -- Python SDK reference
Node.js SDK -- Node.js SDK reference
Scrape -- Single-page extraction details
Crawl -- Multi-page crawling details
Map -- URL discovery details
Search -- Web search details
Agent -- Autonomous data gathering

CLI Reference ​

Installation ​

Authentication ​

Login Methods ​

Configuration Management ​

Self-Hosted Usage ​

Commands ​

scrape ​

search ​

crawl ​

map ​

agent ​

browser ​

credit-usage ​

version ​

Global Options ​

Output Handling ​

Telemetry ​

Related Pages ​

CLI Reference

Installation

Authentication

Login Methods

Configuration Management

Self-Hosted Usage

Commands

scrape

search

crawl

map

agent

browser

credit-usage

version

Global Options

Output Handling

Telemetry

Related Pages