CLI | EvoCrawl

Search, scrape, and interact with the web directly from the terminal. The EvoCrawl CLI works standalone or as a skill that AI coding agents like Claude Code, Antigravity, and OpenCode can discover and use automatically.

Installation

If you are using an AI agent like Claude Code, you can install the EvoCrawl skill below and the agent will set it up for you.

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

--all installs the EvoCrawl skill to every detected AI coding agent
--browser opens the browser for EvoCrawl authentication automatically
“ points to the EvoCrawl API

After installing the skill, restart your agent for it to discover the new skill.

You can also manually install the EvoCrawl CLI globally using npm:

CLI

# Install globally with npm
npm install -g evocrawl-cli

Authentication

Before using the CLI, you need to authenticate with your EvoCrawl API key.

CLI

# Interactive login (opens browser or prompts for API key)
evocrawl login

# Login with browser authentication (recommended for agents)
evocrawl login --browser

# Login with API key directly
evocrawl login --api-key fc-YOUR-API-KEY

# Or set via environment variable
export EVOCRAWL_API_KEY=fc-YOUR-API-KEY

View Configuration

CLI

# View current configuration and authentication status
evocrawl view-config

Logout

CLI

# Clear stored credentials
evocrawl logout

Self-Hosted / Local Development

For self-hosted EvoCrawl instances or local development, use the --api-url option:

CLI

# Use a local Evocrawl instance (no API key required)
evocrawl --api-url http://localhost:3002 scrape https://example.com

# Or set via environment variable
export EVOCRAWL_API_URL=http://localhost:3002
evocrawl scrape https://example.com

# Configure and persist the custom API URL
evocrawl config --api-url http://localhost:3002

When using a custom API URL (anything other than https://api.evocrawl.com), API key authentication is automatically skipped, allowing you to use local instances without an API key.

Check Status

Verify installation, authentication, and view rate limits:

CLI

evocrawl --status

Output when ready:

   evocrawl cli v1.1.1

  ● Authenticated via EVOCRAWL_API_KEY
  Concurrency: 0/100 jobs (parallel scrape limit)
  Credits: 500,000 remaining

Concurrency: Maximum parallel jobs. Run parallel operations close to this limit but not above.
Credits: Remaining API credits. Each scrape/crawl consumes credits.

Commands

Scrape

Scrape a single URL and extract its content in various formats.

Use --only-main-content to get clean output without navigation, footers, and ads. This is recommended for most use cases where you want just the article or main page content.

CLI

# Scrape a URL (default: markdown output)
evocrawl https://example.com

# Or use the explicit scrape command
evocrawl scrape https://example.com

# Recommended: use --only-main-content for clean output without nav/footer
evocrawl https://example.com --only-main-content

Output Formats

CLI

# Get HTML output
evocrawl https://example.com --html

# Multiple formats (returns JSON)
evocrawl https://example.com --format markdown,links

# Get images from a page
evocrawl https://example.com --format images

# Get a summary of the page content
evocrawl https://example.com --format summary

# Track changes on a page
evocrawl https://example.com --format changeTracking

# Available formats: markdown, html, rawHtml, links, screenshot, json, images, summary, changeTracking, attributes, branding

Scrape Options

CLI

# Extract only main content (removes navs, footers)
evocrawl https://example.com --only-main-content

# Wait for JavaScript rendering
evocrawl https://example.com --wait-for 3000

# Take a screenshot
evocrawl https://example.com --screenshot

# Include/exclude specific HTML tags
evocrawl https://example.com --include-tags article,main
evocrawl https://example.com --exclude-tags nav,footer

# Save output to file
evocrawl https://example.com -o output.md

# Pretty print JSON output
evocrawl https://example.com --format markdown,links --pretty

# Force JSON output even with single format
evocrawl https://example.com --json

# Show request timing information
evocrawl https://example.com --timing

Available Options:

Option	Short	Description
`--url <url>`	`-u`	URL to scrape (alternative to positional argument)
`--format <formats>`	`-f`	Output formats (comma-separated): `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `json`, `images`, `summary`, `changeTracking`, `attributes`, `branding`
`--html`	`-H`	Shortcut for `--format html`
`--only-main-content`		Extract only main content
`--wait-for <ms>`		Wait time in milliseconds for JS rendering
`--screenshot`		Take a screenshot
`--include-tags <tags>`		HTML tags to include (comma-separated)
`--exclude-tags <tags>`		HTML tags to exclude (comma-separated)
`--output <path>`	`-o`	Save output to file
`--json`		Force JSON output even with single format
`--pretty`		Pretty print JSON output
`--timing`		Show request timing and other useful information

Search

Search the web and optionally scrape the results.

CLI

# Search the web
evocrawl search "web scraping tutorials"

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

# Pretty print results
evocrawl search "machine learning" --pretty

Search Options

CLI

# Search specific sources
evocrawl search "AI" --sources web,news,images

# Search with category filters
evocrawl search "react hooks" --categories github
evocrawl search "machine learning" --categories research,pdf

# Time-based filtering
evocrawl search "tech news" --tbs qdr:h   # Last hour
evocrawl search "tech news" --tbs qdr:d   # Last day
evocrawl search "tech news" --tbs qdr:w   # Last week
evocrawl search "tech news" --tbs qdr:m   # Last month
evocrawl search "tech news" --tbs qdr:y   # Last year

# Location-based search
evocrawl search "restaurants" --location "Berlin,Germany" --country DE

# Search and scrape results
evocrawl search "documentation" --scrape --scrape-formats markdown

# Save to file
evocrawl search "evocrawl" --pretty -o results.json

Available Options:

Option	Description
`--limit <number>`	Maximum results (default: 5, max: 100)
`--sources <sources>`	Sources to search: `web`, `images`, `news` (comma-separated)
`--categories <categories>`	Filter by category: `github`, `research`, `pdf` (comma-separated)
`--tbs <value>`	Time filter: `qdr:h` (hour), `qdr:d` (day), `qdr:w` (week), `qdr:m` (month), `qdr:y` (year)
`--location <location>`	Geo-targeting (e.g., “Berlin,Germany”)
`--country <code>`	ISO country code (default: US)
`--timeout <ms>`	Timeout in milliseconds (default: 60000)
`--ignore-invalid-urls`	Exclude URLs invalid for other EvoCrawl endpoints
`--scrape`	Scrape search results
`--scrape-formats <formats>`	Formats for scraped content (default: markdown)
`--only-main-content`	Include only main content when scraping (default: true)
`--json`	Output as JSON
`--output <path>`	Save output to file
`--pretty`	Pretty print JSON output

Map

Discover all URLs on a website quickly.

CLI

# Discover all URLs on a website
evocrawl map https://example.com

# Output as JSON
evocrawl map https://example.com --json

# Limit number of URLs
evocrawl map https://example.com --limit 500

Map Options

CLI

# Filter URLs by search query
evocrawl map https://example.com --search "blog"

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

# Control sitemap usage
evocrawl map https://example.com --sitemap include   # Use sitemap
evocrawl map https://example.com --sitemap skip      # Skip sitemap
evocrawl map https://example.com --sitemap only      # Only use sitemap

# Ignore query parameters (dedupe URLs)
evocrawl map https://example.com --ignore-query-parameters

# Wait for map to complete with timeout
evocrawl map https://example.com --wait --timeout 60

# Save to file
evocrawl map https://example.com -o urls.txt
evocrawl map https://example.com --json --pretty -o urls.json

Available Options:

Option	Description
`--url <url>`	URL to map (alternative to positional argument)
`--limit <number>`	Maximum URLs to discover
`--search <query>`	Filter URLs by search query
`--sitemap <mode>`	Sitemap handling: `include`, `skip`, `only`
`--include-subdomains`	Include subdomains
`--ignore-query-parameters`	Treat URLs with different params as same
`--wait`	Wait for map to complete
`--timeout <seconds>`	Timeout in seconds
`--json`	Output as JSON
`--output <path>`	Save output to file
`--pretty`	Pretty print JSON output

Browser

Have your agents interact with the web using a secure browser sandbox. Launch cloud browser sessions and execute Python, JavaScript, or bash code remotely. Each session runs a full Chromium instance — no local browser install required. Code runs server-side with a pre-configured Playwright page object ready to use.

CLI

# Launch a cloud browser session
evocrawl browser launch-session

# Execute agent-browser commands (default - "agent-browser" is auto-prefixed)
evocrawl browser execute "open https://example.com"
evocrawl browser execute "snapshot"
evocrawl browser execute "click @e5"
evocrawl browser execute "scrape"

# Execute Playwright Python code
evocrawl browser execute --python 'await page.goto("https://example.com")
print(await page.title())'

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

# List all sessions (or: list active / list destroyed)
evocrawl browser list

# Close the active session
evocrawl browser close

Browser Options

CLI

# Launch with custom TTL (10 minutes) and live view
evocrawl browser launch-session --ttl 600 --stream

# Launch with inactivity timeout
evocrawl browser launch-session --ttl 120 --ttl-inactivity 60

# agent-browser commands (default - "agent-browser" is auto-prefixed)
evocrawl browser execute "open https://news.ycombinator.com"
evocrawl browser execute "snapshot"
evocrawl browser execute "click @e3"
evocrawl browser execute "scrape"

# Playwright Python - navigate, interact, extract
evocrawl 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())
'

# Playwright JavaScript - same page object
evocrawl browser execute --node '
await page.goto("https://example.com");
const title = await page.title();
console.log(title);
'

# Explicit bash mode - runs in the sandbox
evocrawl browser execute --bash "agent-browser snapshot"

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

# Save output to file
evocrawl browser execute "scrape" -o result.txt

# Close a specific session
evocrawl browser close --session <id>

# List sessions (all / active / destroyed)
evocrawl browser list
evocrawl browser list active --json

Subcommands:

Subcommand	Description
`launch-session`	Launch a new cloud browser session (returns session ID, CDP URL, and live view URL)
`execute <code>`	Execute Playwright Python/JS code or bash commands in a session
`list [status]`	List browser sessions (filter by `active` or `destroyed`)
`close`	Close a browser session

Execute Options:

Option	Description
`--bash`	Execute bash commands remotely in the sandbox (default). agent-browser (40+ commands) is pre-installed and auto-prefixed. `CDP_URL` is auto-injected so agent-browser connects to your session automatically. Best approach for AI agents.
`--python`	Execute as Playwright Python code. A Playwright `page` object is available — use `await page.goto()`, `await page.title()`, etc.
`--node`	Execute as Playwright JavaScript code. Same `page` object available.
`--session <id>`	Target a specific session (default: active session)

Launch Options:

Option	Description
`--ttl <seconds>`	Total session TTL (default: 600, range: 30–3600)
`--ttl-inactivity <seconds>`	Auto-close after inactivity (range: 10–3600)
`--profile <name>`	Name for a profile (saves and reuses browser state across sessions)
`--no-save-changes`	Load existing profile data without saving changes back
`--stream`	Enable live view streaming

Common Options:

Option	Description
`--output <path>`	Save output to file
`--json`	Output as JSON format

Crawl

Crawl an entire website starting from a URL.

CLI

# Start a crawl (returns job ID immediately)
evocrawl crawl https://example.com

# Wait for crawl to complete
evocrawl crawl https://example.com --wait

# Wait with progress indicator
evocrawl crawl https://example.com --wait --progress

Check Crawl Status

CLI

# Check crawl status using job ID
evocrawl crawl <job-id>

# Example with a real job ID
evocrawl crawl 550e8400-e29b-41d4-a716-446655440000

Crawl Options

CLI

# Limit crawl depth and pages
evocrawl crawl https://example.com --limit 100 --max-depth 3 --wait

# Include only specific paths
evocrawl crawl https://example.com --include-paths /blog,/docs --wait

# Exclude specific paths
evocrawl crawl https://example.com --exclude-paths /admin,/login --wait

# Include subdomains
evocrawl crawl https://example.com --allow-subdomains --wait

# Crawl entire domain
evocrawl crawl https://example.com --crawl-entire-domain --wait

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

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

# Save results to file
evocrawl crawl https://example.com --wait --pretty -o results.json

Available Options:

Option	Description
`--url <url>`	URL to crawl (alternative to positional argument)
`--wait`	Wait for crawl to complete
`--progress`	Show progress indicator while waiting
`--poll-interval <seconds>`	Polling interval (default: 5)
`--timeout <seconds>`	Timeout when waiting
`--status`	Check status of existing crawl job
`--limit <number>`	Maximum pages to crawl
`--max-depth <number>`	Maximum crawl depth
`--include-paths <paths>`	Paths to include (comma-separated)
`--exclude-paths <paths>`	Paths to exclude (comma-separated)
`--sitemap <mode>`	Sitemap handling: `include`, `skip`, `only`
`--allow-subdomains`	Include subdomains
`--allow-external-links`	Follow external links
`--crawl-entire-domain`	Crawl entire domain
`--ignore-query-parameters`	Treat URLs with different params as same
`--delay <ms>`	Delay between requests
`--max-concurrency <n>`	Maximum concurrent requests
`--output <path>`	Save output to file
`--pretty`	Pretty print JSON output

Agent

Search and gather data from the web using natural language prompts.

CLI

# Basic usage - URLs are optional
evocrawl agent "Find the top 5 AI startups and their funding amounts" --wait

# Focus on specific URLs
evocrawl agent "Compare pricing plans" --urls https://slack.com/pricing,https://teams.microsoft.com/pricing --wait

# Use a schema for structured output
evocrawl agent "Get company information" --urls https://example.com --schema '{"name": "string", "founded": "number"}' --wait

# Use schema from a file
evocrawl agent "Get product details" --urls https://example.com --schema-file schema.json --wait

Agent Options

CLI

# Use Spark 1 Pro for higher accuracy
evocrawl agent "Competitive analysis across multiple domains" --model spark-1-pro --wait

# Set max credits to limit costs
evocrawl agent "Gather contact information from company websites" --max-credits 100 --wait

# Check status of an existing job
evocrawl agent <job-id> --status

# Custom polling interval and timeout
evocrawl agent "Summarize recent blog posts" --wait --poll-interval 10 --timeout 300

# Save output to file
evocrawl agent "Find pricing information" --urls https://example.com --wait -o pricing.json --pretty

Available Options:

Option	Description
`--urls <urls>`	Optional list of URLs to focus the agent on (comma-separated)
`--model <model>`	Model to use: `spark-1-mini` (default, 60% cheaper) or `spark-1-pro` (higher accuracy)
`--schema <json>`	JSON schema for structured output (inline JSON string)
`--schema-file <path>`	Path to JSON schema file for structured output
`--max-credits <number>`	Maximum credits to spend (job fails if limit reached)
`--status`	Check status of existing agent job
`--wait`	Wait for agent to complete before returning results
`--poll-interval <seconds>`	Polling interval when waiting (default: 5)
`--timeout <seconds>`	Timeout when waiting (default: no timeout)
`--output <path>`	Save output to file
`--json`	Output as JSON format

Credit Usage

Check your team’s credit balance and usage.

CLI

# View credit usage
evocrawl credit-usage

# Output as JSON
evocrawl credit-usage --json --pretty

Version

Display the CLI version.

CLI

evocrawl version
# or
evocrawl --version

Global Options

These options are available for all commands:

Option	Short	Description
`--status`		Show version, auth, concurrency, and credits
`--api-key <key>`	`-k`	Override stored API key for this command
`--api-url <url>`		Use custom API URL (for self-hosted/local development)
`--help`	`-h`	Show help for a command
`--version`	`-V`	Show CLI version

Output Handling

The CLI outputs to stdout by default, making it easy to pipe or redirect:

CLI

# Pipe markdown to another command
evocrawl https://example.com | head -50

# Redirect to a file
evocrawl https://example.com > output.md

# Save JSON with pretty formatting
evocrawl https://example.com --format markdown,links --pretty -o data.json

Format Behavior

Single format: Outputs raw content (markdown text, HTML, etc.)
Multiple formats: Outputs JSON with all requested data

CLI

# Raw markdown output
evocrawl https://example.com --format markdown

# JSON output with multiple formats
evocrawl https://example.com --format markdown,links

Examples

Quick Scrape

CLI

# Get markdown content from a URL (use --only-main-content for clean output)
evocrawl https://docs.evocrawl.com --only-main-content 

# Get HTML content
evocrawl https://example.com --html -o page.html

Full Site Crawl

CLI

# Crawl a docs site with limits
evocrawl crawl https://docs.example.com --limit 50 --max-depth 2 --wait --progress -o docs.json

Site Discovery

CLI

# Find all blog posts
evocrawl map https://example.com --search "blog" -o blog-urls.txt

Research Workflow

CLI

# Search and scrape results for research
evocrawl search "machine learning best practices 2024" --scrape --scrape-formats markdown --pretty

Agent

CLI

# URLs are optional
evocrawl agent "Find the top 5 AI startups and their funding amounts" --wait

# Focus on specific URLs
evocrawl agent "Compare pricing plans" --urls https://slack.com/pricing,https://teams.microsoft.com/pricing --wait

Browser Automation

CLI

# Launch a session, scrape a page, and close
evocrawl browser launch-session
evocrawl browser execute "open https://news.ycombinator.com"
evocrawl browser execute "snapshot"
evocrawl browser execute "scrape"
evocrawl browser close

# Use agent-browser via bash mode (default — recommended for AI agents)
evocrawl browser launch-session
evocrawl browser execute "open https://example.com"
evocrawl browser execute "snapshot"
# snapshot returns @ref IDs — use them to interact
evocrawl browser execute "click @e5"
evocrawl browser execute "fill @e3 'search query'"
evocrawl browser execute "scrape"
# Run --help to see all 40+ commands
evocrawl browser execute --bash "agent-browser --help"
evocrawl browser close

Combine with Other Tools

CLI

# Extract URLs from search results
jq -r '.data.web[].url' search-results.json

# Get titles from search results
jq -r '.data.web[] | "\(.title): \(.url)"' search-results.json

# Extract links and process with jq
evocrawl https://example.com --format links | jq '.links[].url'

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

Telemetry

The CLI collects anonymous usage data during authentication to help improve the product:

CLI version, OS, and Node.js version
Development tool detection (e.g., Cursor, VS Code, Claude Code)

No command data, URLs, or file contents are collected via the CLI. To disable telemetry, set the environment variable:

CLI

export EVOCRAWL_NO_TELEMETRY=1

Open Source

The EvoCrawl CLI and Skill are open source and available on GitHub: superaihuman/evocrawl

Are you an AI agent that needs an EvoCrawl API key? See evocrawl.com/agent-onboarding/SKILL.md for automated onboarding instructions.

​Installation

​Authentication

​Login

​View Configuration

​Logout

​Self-Hosted / Local Development

​Check Status

​Commands

​Scrape

​Output Formats

​Scrape Options

​Search

​Search Options

​Map

​Map Options

​Browser

​Browser Options

​Crawl

​Check Crawl Status

​Crawl Options

​Agent

​Agent Options

​Credit Usage

​Version

​Global Options

​Output Handling

​Format Behavior

​Examples

​Quick Scrape

​Full Site Crawl

​Site Discovery

​Research Workflow

​Agent

​Browser Automation

​Combine with Other Tools

​Telemetry

​Open Source

Installation

Authentication

Login

View Configuration

Logout

Self-Hosted / Local Development

Check Status

Commands

Scrape

Output Formats

Scrape Options

Search

Search Options

Map

Map Options

Browser

Browser Options

Crawl

Check Crawl Status

Crawl Options

Agent

Agent Options

Credit Usage

Version

Global Options

Output Handling

Format Behavior

Examples

Quick Scrape

Full Site Crawl

Site Discovery

Research Workflow

Agent

Browser Automation

Combine with Other Tools

Telemetry

Open Source