CLI

The MrScraper CLI provides terminal access to page retrieval, web 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, such as HTML-only scraperAPI results, 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,
});

console.log(page.data.markdown);

const results = await webSearch({
  token,
  query: "books",
  country: "us",
  numResults: 10,
});
for (const item of results.data.data) console.log(item.rank, item.title, item.url);

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 calls require an explicit token and do not load saved CLI credentials or .env files. They return an error result for HTTP or network failures and throw for invalid arguments. Programmatic account results place the summary directly in data, not in data.account. Programmatic options use camelCase, such as browserRendering, homePage, waitForSelector, waitUntil, maxRetries, tokenCap, and numResults.

CLI command list

scraperAPI

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

GET https://api.mrscraper.com/

The target URL, output flags, page options, and retry controls are all sent as query parameters.

HTML is requested by default. Requesting only HTML returns the page as a string in data. Requesting Markdown or a screenshot returns an object in data with an entry for each requested output, such as html, markdown, and screenshot. At least one of --html, --markdown, or --screenshot must remain selected.

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

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 searches the web to retrieve real-time search results, including relevant website URLs, titles, and descriptions.

mrscraper webSearch "e-menessaptieka.lv linkedin" --country us --num-results 10
mrscraper webSearch "web scraping best practices"

The CLI sends this request:

curl --location 'https://api.mrscraper.com' \
--header 'x-api-token: {MRSCRAPER_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data '{
    "action": "websearch",
    "query": "e-menessaptieka.lv linkedin",
    "country": "us",
    "numResults": 10
}'

data contains success, message, and data. Each item in data.data has rank, title, url, description, and source.

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

Migrating from earlier versions

From 0.5.x

Version 0.6.0 returns to three public operations: scraperAPI, webSearch, and account. The 0.5.x format-specific commands and package exports (scraperHtml, scraperMarkdown, getScreenshot, scraperJson, scraperMultiplePage, scraperSitemap, scrapeBrand, getBrand, and their snake-case aliases) are no longer public.

From 0.4.x

• scraperAPI now sends a GET request with every option in the query string, and adds --wait-until and --save. Requesting only HTML returns a string in data, and screenshots are returned as base64 in a JSON object.
• webSearch now calls https://api.mrscraper.com with action: "websearch" and accepts --country and --num-results (10–100). The --region, --language, --page, --format, --raw, --render-js, and --client-timeout flags and search URL input are removed, as are the raw, format, region, language, page, and renderJs programmatic options and the url input alias.
• The MRSCRAPER_SYNC_BASE_URL setting and the SYNC_SCRAPER_BASE_URL export are removed.
• account is unchanged.

Removed commands

Version 0.4.0 removed the commands below. The CLI exposes only scraperAPI, webSearch, and account as data commands; login, logout, auth, init, and setup remain.