Imported from Juliotamara23/CV-Pilot-Agent (cv-pilot-agent/skills/apify/SKILL.md). Install upstream with npx skills add Juliotamara23/CV-Pilot-Agent --skill apify. Copyright stays with the author.

Skill: Apify Scraper (CLI cli.py)

Documentación del CLI skills/apify/scripts/cli.py. Adaptadores: skills/apify/scripts/platforms/ (Indeed, LinkedIn, Computrabajo).

Comando search

python skills/apify/scripts/cli.py search \
  --platform {indeed|linkedin|computrabajo} \
  --position "React Developer" \
  --location "Medellín" \
  --country CO \
  --count 5 \
  [--workplace onsite|remote|hybrid]   # solo LinkedIn
  [--experience entry|mid|senior]      # solo LinkedIn
  [--confirm]

Dos fases (cost wizard)

1. Sin --confirm — NO llama al actor. Devuelve el costo real en USD:

   {"ok": true, "phase": "cost", "actor": "...", "platform": "linkedin",
    "count": 5, "cost_usd": 0.005, "position": "...", "location": "..."}

2. Con --confirm — ejecuta el actor, normaliza vía el adapter, etiqueta cada resultado high|medium|low (NO descarta nada) y persiste TODO vía query.py job insert-batch --file <tmp>:

   {"ok": true, "phase": "done", "platform": "linkedin", "count": 3,
    "cost_usd": 0.005, "relevance": {"high": 2, "medium": 1, "low": 0},
    "persisted": {"ok": true, "inserted": 3, "duplicates": 0}}

Comandos de dataset (recuperación)

Estos tres comandos permiten recuperar datos de runs interrumpidos o inspeccionar datasets sin re-ejecutar el actor.

datasets-list

Lista runs recientes de un actor. Sirve para encontrar el dataset_id de un run pasado.

python skills/apify/scripts/datasets_cli.py datasets-list \
  --actor <actor-full-name> \
  [--since-minutes 60] \
  [--limit 10]

Envelope de salida:

{
  "ok": true,
  "actor": "curious_coder/linkedin-jobs-scraper",
  "since_minutes": 60,
  "count": 2,
  "runs": [
    {
      "run_id": "abc123",
      "dataset_id": "def456",
      "items_count": 15,
      "started_at": "2026-07-08T10:00:00Z",
      "finished_at": "2026-07-08T10:01:30Z",
      "elapsed_seconds": 90.0,
      "status": "SUCCEEDED",
      "usage_total_usd": 0.005
    }
  ]
}

Casos borde:

• Sin runs recientes → count: 0, runs: [], exit cero.
• Actor inválido o sin permisos → error APIFY_RUNS_LS_FAILED, exit no-cero.

datasets-inspect

Inspeciona un dataset: cuenta items y muestra las claves del schema. Útil para verificar cuántos items tiene antes de hacer fetch.

python skills/apify/scripts/datasets_cli.py datasets-inspect \
  --dataset-id <apify-dataset-id>

Envelope de salida:

{
  "ok": true,
  "dataset_id": "def456",
  "items_count": 15,
  "schema_keys": ["companyName", "positionName", "location", "link", ...],
  "sample_item_preview": {"companyName": "Acme Corp", "positionName": "React Dev..."}
}

Casos borde:

• Dataset vacío → items_count: 0, schema_keys: [], sample_item_preview: null.
• Dataset inexistente → error de Apify CLI, exit no-cero.

datasets-fetch

Trae items de un dataset y persiste los que no están ya en la DB (idempotente, no duplica). Sirve para recuperar runs interrumpidos.

python skills/apify/scripts/datasets_cli.py datasets-fetch \
  --dataset-id <apify-dataset-id> \
  [--persist|--no-persist]

Envelope de salida:

{
  "ok": true,
  "dataset_id": "def456",
  "fetched": 15,
  "new": 3,
  "duplicates": 12,
  "validation_failures": [],
  "persisted": {"ok": true, "inserted": 3, "duplicates": 0},
  "cost_usd": null
}

Casos borde:

• Todos duplicados → new: 0, persisted: null (no hay nada que insertar).
• Items con campos faltantes → aparecen en validation_failures con índice y error; no bloquean los válidos.
• Dataset vacío → fetched: 0, new: 0, exit cero.

Comportamiento

• Plataforma inválida → error INVALID_PLATFORM y exit no-cero.
• CLI de Apify ausente → error APIFY_CLI_MISSING.
• position genérico (ej. "developer", "ingeniero") → advertencia en stderr.
• LinkedIn exige mínimo 10 resultados: el script clampea count y advierte.
• Vacío (0 resultados) → count: 0, persisted: null, exit cero.
• Errores a stderr: {"ok": false, "error": "...", "code": "..."} con exit no-cero.