Scrapeless CLI

Descripción general

La Scrapeless CLI ofrece un único comando scrapeless para la extracción web, el rastreo de sitios, los resultados estructurados de Google Search, las respuestas de IA, la generación de URL de proxy y las operaciones del navegador en la nube. Ejecútelo en una terminal o invóquelo desde sus scripts de automatización.

Funciones

FunciónPunto de entrada del comandoPropósito
Web Unlockerscrapeless unlock / scrapeless scrapeExtraer una página en HTML, Markdown u otros formatos compatibles.
Crawlscrapeless crawlCrear una tarea de rastreo de un sitio web y obtener sus resultados.
AI Scraperscrapeless aiRecopilar respuestas de plataformas de IA compatibles.
Google Searchscrapeless scraping-api google-searchObtenga resultados estructurados de Google Search con opciones de idioma, ubicación y paginación.
Proxiesscrapeless proxy createGenerar localmente una URL de proxy autenticada.
Navegador en la nubescrapeless browserEjecutar la CLI upstream del navegador en la nube.

api es un alias de scraping-api. Por ejemplo, scrapeless api google-search y scrapeless scraping-api google-search ejecutan el mismo comando.

Primeros pasos

Inicio rápido

Requisitos

Utilice Node.js 22 o posterior y npm. Node.js es el entorno de ejecución de la CLI; no necesita escribir JavaScript ni TypeScript. Se requieren una cuenta de Scrapeless y una clave de API para los servicios autenticados.

1. Instale la CLI

npm install -g scrapeless
scrapeless --version
scrapeless --help

2. Configure su clave de API

Copie su clave de API desde el panel de Scrapeless y reemplace YOUR_API_TOKEN:

  1. Abra Settings (Configuración) en el panel.
  2. Seleccione API Key Management (Gestión de claves de API).
  3. Utilice una clave disponible o elija Create API Key (Crear clave de API) si necesita una. Copie la clave para el comando de configuración que aparece a continuación.
scrapeless config set api_token YOUR_API_TOKEN
scrapeless auth status

auth status comprueba la autenticación y el saldo de la cuenta. Las solicitudes en la nube y el tráfico de proxy consumen créditos de la cuenta.

3. Extraiga una página

scrapeless unlock https://example.com --type markdown

El comando imprime el Markdown extraído de la página.

Inspeccione la respuesta completa

Añada --json para inspeccionar la respuesta completa, incluidos su código y el contenido de la página:

scrapeless unlock https://example.com --type markdown --json

4. Busque en Google

Ejecute una búsqueda con una consulta, un idioma y un país:

scrapeless scraping-api google-search --q "coffee" --hl en --gl us

El comando imprime el JSON completo del resultado. Para guardarlo en un archivo:

scrapeless scraping-api google-search --q "coffee" --hl en --gl us -o search.json

Si su CLI instalada no reconoce scraping-api, actualícela y consulte la ayuda del comando:

npm install -g scrapeless@latest
scrapeless scraping-api google-search --help

Ejemplos de uso

Instale la CLI y configure su clave de API antes de ejecutar estos ejemplos.

Web Unlocker

Extraiga una región seleccionada como HTML o guarde una respuesta JSON completa:

scrapeless unlock https://example.com --type html --selector body
scrapeless unlock https://example.com --type markdown --json -o page.json

scrape es un alias de unlock. La salida predeterminada es HTML, con el renderizado de JavaScript habilitado.

Crawl

scrapeless crawl https://example.com --limit 3 --max-depth 2 --formats markdown --json -o crawl.json

--formats markdown selecciona el formato del contenido de la página; el resultado general de la tarea sigue siendo JSON. Delimite el alcance de un rastreo con --include-paths y --exclude-paths.

AI Scraper

scrapeless ai platforms
scrapeless ai chatgpt "Explain what Scrapeless is used for" -o answer.md
scrapeless ai perplexity "What web scraping techniques are available?" --web-search true --json -o answer.json

Las tareas completadas correctamente devuelven Markdown de forma predeterminada. Las opciones varían según la plataforma; use ai platforms para consultar la lista actual. Las indicaciones en inglés son ejemplos: la CLI acepta texto Unicode y la disponibilidad de idiomas depende del servicio seleccionado.

Use scraping-api google-search, o su alias abreviado api google-search, para obtener resultados de búsqueda estructurados.

# Search with a Google search operator and a specific location
scrapeless api google-search \
  --q "site:example.com coffee" \
  --location "Seattle,Washington,United States"
 
# Request results starting at offset 10 and save the JSON
scrapeless api google-search \
  --q "coffee" --hl en --gl us --start 10 \
  -o search.json
 
# Search Google News
scrapeless api google-search --q "artificial intelligence" --tbm nws

Opciones habituales:

OpciónDescripción
--qConsulta de búsqueda obligatoria. Admite operadores de búsqueda de Google. También puede proporcionarse como input.q mediante --data.
--hl, --glCódigos de idioma y país de búsqueda, como en y us.
--location, --uuleUbicación canónica o ubicación de Google codificada. Use solo una.
--google-domainDominio de Google, como google.com.
--tbmTipo de búsqueda, como nws para noticias, isch para imágenes o lcl para resultados locales.
--startDesplazamiento de resultados no negativo. Para --tbm lcl, use múltiplos de 20.
--safeConfiguración de SafeSearch: active u off.
--deviceActualmente solo acepta desktop.
--country, --proxy-urlPaís del proxy o URL de proxy personalizada.
--timeout, --intervalTiempo de espera e intervalo de sondeo, en segundos. Valores predeterminados: 300 y 5.
-o, --outputGuarde el JSON del resultado en un archivo.

--gl controla el país de búsqueda; --country configura el país del proxy. Son ajustes independientes. Un --proxy-url no vacío tiene prioridad sobre el país del proxy.

Para incluir otros campos de solicitud, pase un cuerpo JSON completo. Guarde lo siguiente como search-request.json:

{
  "actor": "scraper.google.search",
  "input": {
    "q": "coffee",
    "hl": "en",
    "gl": "us",
    "as_eq": "instant"
  },
  "proxy": {
    "country": "US"
  }
}

Ejecute la solicitud:

scrapeless api google-search --data @search-request.json -o search.json

Los flags explícitos sobrescriben los campos correspondientes del cuerpo. El comando siempre establece el actor en scraper.google.search.

Ejecute scrapeless scraping-api google-search --help para ver todas las opciones de la CLI. Consulte la documentación de Google Search para obtener detalles de la API.

Proxies

scrapeless proxy gateways
scrapeless proxy create --type residential --country US --gateway us

La generación de la URL se realiza localmente, sin probar la conectividad. Los tipos compatibles son residential, ipv6 y datacenter; las puertas de enlace aceptan us, eu, ap o hostname:port. La URL contiene credenciales; manténgala en privado.

Reemplace SESSION_ID por el ID de sesión devuelto por new-session:

scrapeless browser new-session --name demo --ttl 300 --json
scrapeless browser --session-id SESSION_ID open https://example.com
scrapeless browser --session-id SESSION_ID snapshot -i
scrapeless browser --session-id SESSION_ID screenshot page.png
scrapeless browser --session-id SESSION_ID close

Para click @e1 o fill @e2 "hello world", utilice referencias interactivas reales de una instantánea reciente mientras la sesión esté abierta. De forma predeterminada, el primer uso, incluido browser --help, instala la CLI upstream; consulte Requisitos del navegador en Configuración y tareas.

Para ver las opciones de los comandos, ejecute scrapeless unlock --help, scrapeless crawl --help, scrapeless ai --help, scrapeless scraping-api google-search --help o scrapeless proxy create --help. El comportamiento de instalación en el primer uso de browser --help se describe más arriba.

La referencia completa de comandos y las instrucciones para compilar desde el código fuente se encuentran en el repositorio de la CLI. El comportamiento y la facturación del servicio de IA se tratan en la documentación de AI Scraper.

Configuración y tareas

Credenciales

El archivo predeterminado es ~/.scrapeless/config.json. El orden de prioridad de la clave es archivo de configuración → SCRAPELESS_API_TOKEN → SCRAPELESS_API_KEY. Para usar una variable de entorno:

export SCRAPELESS_API_KEY="YOUR_API_TOKEN"

Una clave guardada tiene prioridad. La CLI no carga .env automáticamente. Esta es la sintaxis POSIX; PowerShell usa $env:SCRAPELESS_API_KEY="YOUR_API_TOKEN".

VariablePropósito
SCRAPELESS_API_KEYClave de API; también es compatible con Browser.
SCRAPELESS_API_TOKENVariable alternativa de la clave para los comandos unificados.
SCRAPELESS_CONFIG_PATHRuta de configuración personalizada solo para los comandos unificados.
SCRAPELESS_API_BASE_URLSustitución de la API HTTP unificada; el valor predeterminado es https://api.scrapeless.com.
SCRAPELESS_CACHE_DIRRaíz de la caché de Browser; el valor predeterminado es ~/.cache/scrapeless.
SCRAPELESS_BROWSER_BINRuta absoluta a un ejecutable compatible; omite la instalación automática.

Una ruta de configuración personalizada no cambia el archivo predeterminado de Browser. El wrapper transmite la clave resuelta mediante una variable de entorno, pero la clave guardada predeterminada de Browser puede sobrescribirla. Utilice el archivo predeterminado compartido para mantener una autenticación coherente.

Salida y cuerpos de solicitud

Los comandos HTTP admiten --json para obtener la respuesta completa y -o, --output <file> para guardar la salida. De forma predeterminada, los resultados se envían a stdout; con -o, se guardan en el archivo. El progreso, los avisos de ID de tarea durante el sondeo y los errores se envían a stderr. Con --no-wait, la respuesta de creación, incluido su ID de tarea, forma parte de la salida del resultado.

Los comandos de creación de Unlocker, Crawl, AI y Scraping API aceptan --data '<JSON>' o --data @request.json. El orden de prioridad es flags explícitos → campos del cuerpo → valores predeterminados de la CLI; los objetos anidados se combinan y los arrays se reemplazan.

Google Search siempre devuelve el JSON completo del resultado, incluso si se omite --json. Use -o, --output <file> para guardarlo. Los avisos de ID de tarea y los errores se envían a stderr.

Gestión de tareas

La creación en Crawl y AI realiza un sondeo cada 5 segundos durante un máximo de 300 segundos de forma predeterminada. Añada --no-wait para que el comando regrese tras la creación. Consulte una tarea existente con el ID devuelto:

scrapeless crawl result TASK_ID --wait --timeout 300 --interval 5
scrapeless ai result TASK_ID --platform chatgpt --wait --timeout 300 --interval 5

Utilice el ID del servicio correspondiente. Un tiempo de espera agotado durante el sondeo no cancela la tarea en el servidor. Compruebe completed para Crawl o success para AI e inspeccione el contenido real; el código de salida 0 por sí solo no es suficiente.

--timeout y --interval usan segundos; las opciones de scraping --wait-for y --scrape-timeout usan milisegundos. Cada solicitud HTTP tiene un tiempo de espera independiente de 60 segundos. Las solicitudes POST de creación de tareas no se reintentan automáticamente.

Google Search devuelve resultados inmediatamente con HTTP 200. Si la API responde con HTTP 201 y un taskId, la CLI sondea automáticamente el resultado cada 5 segundos durante un máximo de 300 segundos. Ajuste estos valores con --interval y --timeout.

Para continuar comprobando una tarea existente sin crear otra solicitud:

scrapeless scraping-api result TASK_ID \
  --timeout 300 --interval 5 \
  -o search.json

El comando result realiza el sondeo automáticamente; no necesita el flag --wait.

Las respuestas HTTP 4xx o 5xx y los tiempos de sondeo agotados finalizan con código 1. Si se agota el tiempo de sondeo, stderr incluye el ID de tarea, la última respuesta y un comando para continuar comprobando. El timeout no cancela la tarea del servidor. Las solicitudes POST de creación de tareas no se reintentan automáticamente.

Requisitos del navegador

El wrapper necesita npm, acceso a npm y a GitHub Releases, y permisos de escritura en la caché. Las sesiones se ejecutan en la nube; el wrapper se ejecuta localmente sin necesidad de instalar Chromium por separado.

La versión fijada es compatible con macOS x64/arm64, Linux x64/arm64 y Windows x64; no se incluye ningún binario para Windows arm64.

Solución de problemas

ProblemaQué comprobar
Falta la clave o HTTP 401/403Compruebe la clave guardada, los permisos de la cuenta y el saldo; ejecute scrapeless auth status.
Tiempo de sondeo agotado en Crawl o AIConserve el ID de la tarea y use los comandos result ... --wait anteriores; inspeccione el estado y el contenido real.
Falla la instalación de BrowserCompruebe npm, el acceso a la red, los permisos de escritura en la caché y los requisitos de plataforma anteriores.
Comando scraping-api desconocidoActualice con npm install -g scrapeless@latest y ejecute scrapeless scraping-api google-search --help.
Tiempo de sondeo de Google Search agotadoUse el ID de tarea indicado con scrapeless scraping-api result TASK_ID. Aumente --timeout si es necesario.
Falla la validación de parámetros de Google SearchProporcione una consulta no vacía, use solo uno de --location y --uule y un valor --start no negativo. La búsqueda local requiere desplazamientos en múltiplos de 20.