CLI

The MrScraper CLI provides terminal access to page retrieval, Google search, 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 account --json

A successful account call 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

scraperAPI and webSearch return a consistent JSON envelope:

{
  "status_code": 200,
  "data": {},
  "headers": {
    "content-type": "application/json"
  }
}

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 and sensitive response headers are redacted.
• HTTP and network failures remain JSON on stdout, set error, and exit non-zero.
• Progress messages use stderr so stdout remains machine-readable.

account presents account data as a normalized summary at data.account.

Environment variables

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

Programmatic use

The package exports the same three operations used by the commands:

import { scraperAPI, webSearch, account } from "@mrscraper/cli";

const token = process.env.MRSCRAPER_API_KEY;

const page = await scraperAPI({
  token,
  url: "https://www.scrapethissite.com/pages/simple/",
  markdown: true,
});

const results = await webSearch({
  token,
  query: "books",
  raw: false,
  format: "json",
});

const status = await account({ token, timeout: 30 });
console.log(status.data.token_remaining);

The functions return the same response envelope used by the CLI commands. Programmatic account results place the summary directly in data, not in data.account. Programmatic options use camelCase, such as browserRendering, homePage, maxRetries, and tokenCap.

scraperAPI and webSearch use the Python SDK's defaults, including webSearch's raw: true (result-page HTML); pass raw: false for parsed JSON.

CLI command list

scraperAPI

scraperAPI uses MrScraper's Web Fetching to retrieve a known page as HTML, Markdown, a screenshot, or a combination through:

POST https://api.mrscraper.com/

HTML is requested by default. The content is in the envelope's data object:

mrscraper scraperAPI "https://www.scrapethissite.com/pages/simple/"
mrscraper scraperAPI "https://www.scrapethissite.com/pages/simple/" | jq -r '.data.html'
mrscraper scraperAPI "https://www.scrapethissite.com/pages/simple/" \
  --markdown --no-html | jq -r '.data.markdown'

data also reports token_usage, runtime, retry_count, and error. A screenshot is a base64-encoded JPEG; the x-status-code response header carries the target page's status.

Browser rendering is automatic unless you set it: the service falls back to a browser when needed. --browser-rendering forces a browser, --no-browser-rendering disables it, and --screenshot always uses one. Real-device routing (--super) is independent of browser rendering:

mrscraper scraperAPI "https://www.scrapethissite.com/pages/ajax-javascript/#2015" \
  --browser-rendering \
  --wait-for-selector ".film"

mrscraper scraperAPI "https://www.scrapethissite.com/pages/simple/" \
  --super --geo-code ID --home-page

scraperAPI parameters

Web Fetching usage is based on runtime and bandwidth: one plan token per 30 seconds and one plan token per 0.25 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.

webSearch

webSearch calls:

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

Parsed JSON is the default; organic results are in data.data.organic. Use --format html for the result-page HTML:

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

A complete Google search URL can also be passed directly:

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

The CLI extracts q, gl, hl, and start, and converts start to a page number (start=10 selects page 2). Explicit --region, --language, and --page values override the values from the URL.

webSearch parameters

account

account checks the remote account's identity, subscription, token quota, and rate limits. It calls:

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

mrscraper account
mrscraper account --json
mrscraper account --pretty --no-color

Interactive terminals show a dashboard by default; redirected output is JSON. API keys and billing identifiers are excluded, and remaining tokens are clamped to zero for over-quota accounts.

{
  "status_code": 200,
  "data": {
    "account": {
      "subscription_status": "active",
      "enterprise": false,
      "token_usage": 250,
      "token_limit": 1000,
      "token_remaining": 750,
      "usage_percent": 25,
      "rate_limit": 10,
      "rate_ttl": 60,
      "auto_renew": true,
      "ends_at": null,
      "user": {
        "name": "Ada",
        "email": "ada@example.com",
        "verified": true
      }
    }
  },
  "headers": {}
}

account parameters

Removed commands

Version 0.4.0 exposes only scraperAPI, webSearch, and account as data commands. login, logout, auth, init, and setup remain.