> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Salida y códigos de salida

> Comprende la salida JSON, los flujos de eventos JSONL, stdout, stderr, los códigos de salida y los tipos de eventos de Octoparse CLI.

Octoparse CLI admite una salida legible para el uso en terminal y una salida legible por máquinas para la automatización.

Usa esta página cuando llames a Octoparse CLI desde scripts, agentes, trabajos de CI u otros entornos de automatización.

## Salida JSON

Usa `--json` cuando necesites una única respuesta JSON estable.

```bash theme={null}
octoparse task list --json
octoparse auth status --json
octoparse local status <taskId> --json
```

Los comandos ejecutados correctamente devuelven un contenedor JSON con `ok: true` y un campo `data`:

```json theme={null}
{
  "ok": true,
  "data": {
    "items": [
      { "taskId": "abc123", "taskName": "Example task", "status": "Idle" }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}
```

Los comandos fallidos devuelven `ok: false` con un campo `error` que contiene un código y un mensaje:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key is required for this command."
  }
}
```

La estructura exacta de `data` depende del comando. Entre los códigos de error habituales se incluyen `AUTH_REQUIRED`, `AUTH_INVALID`, `TASK_INVALID`, `LINUX_ARM64_UNSUPPORTED`, `ENGINE_RUN_FAILED` y `UNSUPPORTED_EXPORT_FORMAT`. Ejecuta `octoparse capabilities --json` para ver la lista completa.

## Flujos de eventos JSONL

Usa `--jsonl` para extracciones locales de larga duración. La salida transmite un objeto JSON por línea:

```bash theme={null}
octoparse run <taskId> --jsonl
```

Un flujo habitual:

```jsonl theme={null}
{"event":"run.started","taskId":"abc123","timestamp":"2026-01-01T10:00:00.000Z"}
{"event":"row","taskId":"abc123","count":1}
{"event":"captcha","taskId":"abc123","service":"..."}
{"event":"proxy","taskId":"abc123","status":"..."}
{"event":"run.completed","taskId":"abc123","savedRows":42}
```

Tipos de eventos estables:

| Evento               | Cuándo se activa                                              |
| -------------------- | ------------------------------------------------------------- |
| `warning`            | Advertencia no fatal durante la ejecución                     |
| `billing.warning`    | Advertencia de saldo bajo                                     |
| `billing.error`      | Saldo agotado                                                 |
| `run.started`        | Se ha iniciado la Ejecución local                             |
| `row`                | Se ha guardado una fila                                       |
| `log`                | Línea de registro del motor                                   |
| `captcha`            | Solicitud de CAPTCHA del entorno de ejecución                 |
| `proxy`              | Solicitud o estado del Proxy                                  |
| `download.started`   | Se ha iniciado la descarga de un archivo                      |
| `download.succeeded` | Ha finalizado la descarga de un archivo                       |
| `download.failed`    | Ha fallado la descarga de un archivo                          |
| `run.paused`         | Se ha pausado la ejecución                                    |
| `run.resumed`        | Se ha reanudado la ejecución                                  |
| `run.stopping`       | Se ha solicitado detener la ejecución y esta está finalizando |
| `run.stopped`        | El usuario ha detenido la ejecución                           |
| `run.failed`         | La ejecución ha fallado con un error                          |

<Note>
  Los nombres y los campos de los eventos pueden evolucionar entre versiones. Trata cada línea como un objeto JSON independiente y gestiona de forma segura los campos desconocidos.
</Note>

## Artefactos de ejecuciones desvinculadas

Cuando ejecutas con `--detach`, la CLI escribe archivos de arranque en el directorio de salida:

| Archivo          | Contenido                                  |
| ---------------- | ------------------------------------------ |
| `bootstrap.json` | Metadatos y estado inicial de la ejecución |
| `stdout.log`     | Salida estándar de la ejecución            |
| `stderr.log`     | Salida de error estándar de la ejecución   |

Archivos de artefactos de la Ejecución local (en el directorio de ejecución):

| Archivo           | Contenido                         |
| ----------------- | --------------------------------- |
| `meta.json`       | Metadatos de la ejecución         |
| `control.json`    | Estado de control de la ejecución |
| `events.jsonl`    | Todos los eventos JSONL           |
| `logs.jsonl`      | Líneas de registro del motor      |
| `rows.jsonl`      | Filas guardadas                   |
| `downloads.jsonl` | Eventos de descarga               |

## stdout y stderr

| Flujo  | Modo para personas                  | Modo `--json` / `--jsonl`                    |
| ------ | ----------------------------------- | -------------------------------------------- |
| stdout | Salida del comando                  | JSON o JSONL estructurado                    |
| stderr | Diagnósticos, advertencias y fallos | Texto sin formato o contenedor de error JSON |

Esta separación permite que las herramientas de automatización canalicen la salida solicitada sin mezclarla con los registros de diagnóstico.

## Códigos de salida

| Código de salida | Significado                       | Causas habituales                                                                                      |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| 0                | Listo                             | El comando ha finalizado según lo solicitado                                                           |
| 1                | La operación ha fallado           | Fallo de autenticación, tarea no encontrada o error de exportación                                     |
| 2                | Fallo del entorno o de ejecución  | Versión de Node.js incompatible, Chrome no disponible, fallo de inicialización del motor o Linux arm64 |
| 3                | Definición de tarea no compatible | La tarea usa el navegador kernel o un Flujo de trabajo antiguo no compatible con CLI v1                |

Un código de salida distinto de cero significa que el comando no ha finalizado según lo previsto.

## Recomendaciones de automatización

* Usa `--json` para scripts que necesiten una única respuesta estructurada.
* Usa `--jsonl` para ejecuciones de tareas de larga duración.
* Trata los códigos de salida distintos de cero como pasos de automatización fallidos.
* Captura stderr por separado al depurar.
* No expongas claves de API ni tokens en registros o en la salida de CI.
* Ejecuta `octoparse capabilities --json` al principio del Flujo de trabajo de un agente para descubrir la superficie de comandos y el contrato legible por máquinas actuales.

<Note>
  Para los agentes de IA y los entornos de automatización, usa preferentemente `--json` o `--jsonl` en lugar de la salida legible para personas. Empieza con `octoparse capabilities --json` para obtener el contrato completo legible por máquinas.
</Note>