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ón | Punto de entrada del comando | Propósito |
|---|---|---|
| Web Unlocker | scrapeless unlock / scrapeless scrape | Extraer una página en HTML, Markdown u otros formatos compatibles. |
| Crawl | scrapeless crawl | Crear una tarea de rastreo de un sitio web y obtener sus resultados. |
| AI Scraper | scrapeless ai | Recopilar respuestas de plataformas de IA compatibles. |
| Google Search | scrapeless scraping-api google-search | Obtenga resultados estructurados de Google Search con opciones de idioma, ubicación y paginación. |
| Proxies | scrapeless proxy create | Generar localmente una URL de proxy autenticada. |
| Navegador en la nube | scrapeless browser | Ejecutar 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: instale la CLI, configure su clave y realice su primera solicitud.
- Ejemplos de uso: comandos para cada función.
- Configuración y tareas: credenciales, salida, sondeo y requisitos del navegador.
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 --help2. Configure su clave de API
Copie su clave de API desde el panel de Scrapeless y reemplace YOUR_API_TOKEN:
- Abra Settings (Configuración) en el panel.
- Seleccione API Key Management (Gestión de claves de API).
- 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 statusauth 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 markdownEl 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 --json4. 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 usEl 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.jsonSi 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 --helpEjemplos 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.jsonscrape 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.jsonLas 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.
Google Search
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 nwsOpciones habituales:
| Opción | Descripción |
|---|---|
--q | Consulta de búsqueda obligatoria. Admite operadores de búsqueda de Google. También puede proporcionarse como input.q mediante --data. |
--hl, --gl | Códigos de idioma y país de búsqueda, como en y us. |
--location, --uule | Ubicación canónica o ubicación de Google codificada. Use solo una. |
--google-domain | Dominio de Google, como google.com. |
--tbm | Tipo de búsqueda, como nws para noticias, isch para imágenes o lcl para resultados locales. |
--start | Desplazamiento de resultados no negativo. Para --tbm lcl, use múltiplos de 20. |
--safe | Configuración de SafeSearch: active u off. |
--device | Actualmente solo acepta desktop. |
--country, --proxy-url | País del proxy o URL de proxy personalizada. |
--timeout, --interval | Tiempo de espera e intervalo de sondeo, en segundos. Valores predeterminados: 300 y 5. |
-o, --output | Guarde 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.jsonLos 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 usLa 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.
Navegador en la nube
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 closePara 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".
| Variable | Propósito |
|---|---|
SCRAPELESS_API_KEY | Clave de API; también es compatible con Browser. |
SCRAPELESS_API_TOKEN | Variable alternativa de la clave para los comandos unificados. |
SCRAPELESS_CONFIG_PATH | Ruta de configuración personalizada solo para los comandos unificados. |
SCRAPELESS_API_BASE_URL | Sustitución de la API HTTP unificada; el valor predeterminado es https://api.scrapeless.com. |
SCRAPELESS_CACHE_DIR | Raíz de la caché de Browser; el valor predeterminado es ~/.cache/scrapeless. |
SCRAPELESS_BROWSER_BIN | Ruta 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 5Utilice 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.
Tareas de Google Search
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.jsonEl 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
| Problema | Qué comprobar |
|---|---|
| Falta la clave o HTTP 401/403 | Compruebe la clave guardada, los permisos de la cuenta y el saldo; ejecute scrapeless auth status. |
| Tiempo de sondeo agotado en Crawl o AI | Conserve el ID de la tarea y use los comandos result ... --wait anteriores; inspeccione el estado y el contenido real. |
| Falla la instalación de Browser | Compruebe npm, el acceso a la red, los permisos de escritura en la caché y los requisitos de plataforma anteriores. |
Comando scraping-api desconocido | Actualice con npm install -g scrapeless@latest y ejecute scrapeless scraping-api google-search --help. |
| Tiempo de sondeo de Google Search agotado | Use 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 Search | Proporcione 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. |