CLI

The MrScraper CLI provides terminal access to HTML fetching, AI extraction, Google SERP, saved scraper reruns, stored results, and account usage. This guide covers installation, verification, authentication, output formats, environment variables, programmatic usage, and complete command details.

Requirements

• Node.js 20 or newer
• A MrScraper account for browser login, or an API key for non-interactive use

Installation

Install only the CLI globally:

npm install -g @mrscraper/cli@latest
mrscraper --version

Install the CLI and all four MrScraper agent skills for every detected harness:

npx -y @mrscraper/cli@latest init --all

Install for one harness:

npx -y @mrscraper/cli@latest init --agent codex

Supported IDs are claude-code, cursor, codex, grok, hermes, opencode, openclaw, pi, and omp.

Copyable AI setup prompt

Read and follow https://github.com/mrscraper-com/cli/blob/main/skills/mrscraper/SKILL.md

For an agent-controlled, non-interactive setup, skip authentication during bootstrap and start login separately:

npx -y @mrscraper/cli@latest init --agent codex --yes --skip-auth
mrscraper auth status --json
mrscraper login

init parameters

Refresh only the skills with mrscraper setup skills. It accepts --agent <id> for one harness and --dry-run; without --agent, it targets detected harnesses.

Native plugins (optional)

The MrScraper CLI repository also provides skills-only native plugins for Codex, Claude Code, and Cursor. Plugin installation is an alternative to mrscraper init, not an additional setup step.

Plugins do not install or authenticate the CLI. When using a plugin, install and authenticate the CLI separately:

npm install -g @mrscraper/cli@latest
mrscraper login

• Claude Code: run claude plugin marketplace add mrscraper-com/cli, then install mrscraper-cli@mrscraper.
• Cursor: use /add-plugin mrscraper-cli after its public marketplace listing; until then, load the repository through Cursor's local plugin directory.
• Codex: until its public plugin listing is available, use the local marketplace example from the CLI repository.

Verifying installation

After completing installation, verify that the CLI binary and commands are accessible in your environment:

mrscraper --version
mrscraper auth status --json
mrscraper scrape "https://example.com" \
  --prompt "Extract the page title"

A successful scrape confirms that the CLI can load its authentication and reach the MrScraper service.

Authentication

Browser login

mrscraper login

The CLI opens the MrScraper login page, waits for the local browser callback, exchanges the returned code, and saves the provisioned API key in ~/.mrscraper/auth.json. Set MRSCRAPER_HOME to change the containing directory.

API-key login

mrscraper login --api-key "$MRSCRAPER_API_KEY"

Prefer environment variables to literal keys in shell history:

export MRSCRAPER_API_KEY="your-key"

Authentication precedence for API commands is:

1. Command --token
2. MRSCRAPER_API_KEY
3. MRSCRAPER_API_TOKEN
4. ~/.mrscraper/auth.json

login parameters

Auth status and logout

mrscraper auth status reports the credential currently available to the CLI. It reads the local configuration without sending a test request. JSON output uses the credential_configured field:

{
  "credential_configured": true,
  "auth_type": "api_key",
  "path": "/home/user/.mrscraper/auth.json"
}

mrscraper logout deletes local credential files. It does not revoke an API key remotely.

Output contract

API commands return a consistent JSON envelope:

{
  "status_code": 200,
  "data": "the parsed JSON response or response text",
  "headers": {
    "content-type": "text/html"
  }
}

The fields are:

• status_code contains the HTTP response code.
• headers contains non-sensitive response headers.
• data contains the response body. JSON responses are parsed; other bodies remain strings.
• Known credential metadata, sensitive response headers, and credentials in generated curl commands are redacted.
• Fetched HTML and scraper extraction results are returned in data.
• HTTP failures remain JSON on stdout, set error, and exit non-zero.
• Progress messages use stderr so stdout remains machine-readable.

status presents account and analytics data as a normalized summary.

Environment variables

The CLI also loads a .env file from the current working directory.

Programmatic use

The package exports the same direct API helpers used by the commands:

import {
  fetchContentApi,
  createAiScraperApi,
  googleSerpSyncApi,
  getAllResultsApi,
} from "@mrscraper/cli";

const result = await fetchContentApi({
  token: process.env.MRSCRAPER_API_KEY,
  url: "https://example.com",
  browserRendering: true,
  maxRetries: 3,
});

The helpers return the same response envelope used by the CLI commands.

CLI command list

fetch

fetch uses MrScraper's Web Unblocker to retrieve HTML from public, protected, JavaScript-rendered, or geo-sensitive pages through:

GET https://api.mrscraper.com/

The returned HTML is available in the envelope's .data field.

mrscraper fetch "https://example.com"
mrscraper fetch "https://example.com" | jq -r '.data'

For JavaScript-rendered content, enable browser rendering:

mrscraper fetch "https://example.com/products" \
  --browser-rendering \
  --wait-for-selector ".product-card"

fetch parameters

Start with the default request and add page-loading controls when the target needs them. Unblocker usage is based on runtime and bandwidth: one plan token per 30 seconds and one plan token per 0.2 MB, rounded up per component. Resource blocking can reduce bandwidth for text-focused pages. Use --max-retries and --token-cap to balance retry reliability with usage. See the Token Plan for the complete calculation.

scrape

scrape calls:

POST https://api.app.mrscraper.com/api/v1/scrapers-ai

The default agent is general. General and listing require an extraction prompt:

mrscraper scrape "https://example.com/product" \
  --prompt "Extract name, price, availability, and image URLs"

The request body contains url, message, and agent, plus optional fields for the selected agent.

Listing agent

mrscraper scrape "https://example.com/products" \
  --agent listing \
  --prompt "Extract every product's name, price, and URL" \
  --max-pages 5

Listing is synchronous and may take several minutes. Progress is printed to stderr. If --max-pages is omitted, the service default applies.

Map agent

mrscraper scrape "https://example.com" \
  --agent map \
  --max-depth 2 \
  --max-pages 50 \
  --limit 1000 \
  --include-patterns '/products/'

Map accepts crawl limits and URL patterns. Prompts, schema guidance, and proxy country selection are available with the general and listing agents.

Local output file

mrscraper scrape "https://example.com/product" \
  --prompt "Extract the product" \
  --output ./.mrscraper/product.json

--output creates parent directories and writes the extracted data.data.data value as pretty JSON. The complete response remains on stdout. The file is created after a completed extraction returns data.

Best-effort schema prompt

mrscraper scrape "https://example.com/product" \
  --prompt "Extract the product" \
  --schema-prompt ./product.schema.json

--schema-prompt reads a local JSON Schema object and adds it to the extraction instructions as best-effort shape guidance. Use a separate validator when strict schema compliance is required.

Reproduce a scrape with rerun

Every successful scrape creates a saved AI scraper configuration by default. The complete stdout response contains its UUID at data.data.scraperId. Save that response when the extraction may need to run again:

mrscraper scrape "https://example.com/product" \
  --prompt "Extract the product name, price, and availability" \
  --output ./.mrscraper/product.json \
  > ./.mrscraper/product-run.json

SCRAPER_UUID=$(jq -r '.data.data.scraperId' ./.mrscraper/product-run.json)
mrscraper rerun "https://example.com/product-2" \
  --type ai \
  --scraper-id "$SCRAPER_UUID"

The output file contains only data.data.data; the stdout envelope retains the scraper UUID. rerun reproduces the saved prompt and agent configuration, but page changes and model behavior can still change the extracted values.

rerun also supports dashboard-built manual workflows and asynchronous bulk jobs across multiple target URLs. See the full rerun section below for the available modes and result-tracking workflow.

scrape parameters

serp

serp calls:

POST https://sync.scraper.mrscraper.com/api/google/serp/v2/sync

Use --format to choose parsed JSON or the result-page HTML:

mrscraper serp "iphone 17" --region id --language id --page 2
mrscraper serp "iphone 17" --format html --render-js

A complete Google search URL can also be passed directly:

mrscraper serp "https://www.google.com/search?q=iphone+17&gl=us&hl=en&start=20"

The CLI extracts q, gl, hl, and start, converts start to a page number, then sends the normal API body.

serp parameters

status

status combines account information into a concise summary. It calls:

GET https://api.app.mrscraper.com/api/v1/subscription-accounts

The CLI removes credential and billing identifiers, renames selected fields, and calculates token_remaining and usage_percent. Interactive terminals get a dashboard; redirected output is JSON. Force either mode with --pretty or --json.

mrscraper status
mrscraper status --json

The JSON summary includes its source endpoints:

{
  "kind": "mrscraper-cli-status-summary",
  "source_endpoints": ["/subscription-accounts"],
  "status_code": 200,
  "data": {
    "account": {}
  }
}

With --domain, the CLI makes a second request to /analytic/statuses, converts a URL to its hostname, converts relative dates to the API timestamp format, and merges the result:

mrscraper status --domain "https://example.com/products" --from 7d --to now

status parameters

rerun

Choose the saved scraper and the number of target URLs independently:

• --type ai runs an AI scraper created by mrscraper scrape.
• --type manual runs a step-based workflow created in the MrScraper dashboard. The CLI reruns existing manual workflows; it does not create them.
• Without --bulk, the scraper runs on one URL. With --bulk, the same saved configuration is submitted once with a comma- or newline-separated URL list.

Manual reruns can be single or bulk. Bulk reruns can use either an AI or a manual scraper; bulk describes the number of targets, not the scraper type.

Bulk mode submits one asynchronous backend job; it does not loop over the single-URL endpoint locally. Save data.data.bulkResultId from the submission response and retrieve the stored result until it finishes:

mrscraper result --id BULK_RESULT_UUID

rerun selects an endpoint based on --type and --bulk:

mrscraper rerun "https://example.com/product" \
  --type ai --scraper-id SCRAPER_UUID

mrscraper rerun "https://a.example,https://b.example" \
  --bulk --type manual --id SCRAPER_UUID

rerun parameters

The crawl controls apply to single AI reruns.

results

results calls GET /api/v1/results and maps its filtering options directly to query parameters:

mrscraper results --page-size 20 --page 2
mrscraper results --search example.com
mrscraper results \
  --date-range-column updatedAt \
  --start-at "2026-08-01T00:00:00Z" \
  --end-at "2026-08-18T00:00:00Z"

results parameters

result

result calls GET /api/v1/results/{id}:

mrscraper result RESULT_UUID
mrscraper result --id RESULT_UUID

The positional ID and --id are local input alternatives. --token overrides authentication for this command.