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

# Referencia: flags, modos y exit codes

> Flags globales, modos de salida para agentes y CI, introspección con --describe, códigos de salida, variables de entorno y comandos de mantenimiento del CLI de Jelou.

## Flags globales

Disponibles en cualquier comando:

| Flag               | Descripción                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `--json`           | Salida JSON estructurada en stdout. Implica `--no-input`.                                        |
| `--agent`          | Modo agente: implica `--json`, `--no-input`, `--compact`, `NO_COLOR=1`, `JELOU_NO_SPINNERS=1`.   |
| `--compact`        | JSON sin espacios (ahorra \~30-40% de tokens).                                                   |
| `--human`          | Fuerza salida legible aunque stdout esté redirigido (anula el auto-JSON).                        |
| `--no-input`       | Desactiva prompts interactivos; las operaciones destructivas fallan en duro en vez de preguntar. |
| `--profile <name>` | Usa un perfil de auth específico para ese comando.                                               |
| `--describe`       | Emite el esquema del comando como JSON, sin ejecutarlo.                                          |

## Modos de salida para agentes

**Auto-JSON al redirigir:** si stdout no es una terminal (ej. `jelou whoami |
jq`), el CLI pasa a JSON automáticamente. Fuérzalo a legible con `--human` o
`JELOU_FORCE_HUMAN_OUTPUT=1`.

**Forma de la respuesta:**

```json theme={null}
// Éxito
{ "ok": true, "data": { } }
// Error
{ "ok": false, "error": { "code": "...", "message": "...", "details": {} } }
```

Códigos de error: `AUTH_ERROR`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`,
`API_ERROR`, `MISSING_FUNCTIONS_PROJECT`, `MISSING_WORKFLOW_PROJECT`,
`MISSING_AUTH`, `INPUT_ERROR`, `UNKNOWN_ERROR`, `NETWORK_ERROR`,
`TRANSIENT_ERROR`, `MISSING_LOCKFILE`.

El objeto `error` también puede incluir un campo `retryable` (booleano) que
indica si vale la pena reintentar el comando tal cual, sin cambiar nada:

```json theme={null}
{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Not found.", "retryable": false } }
```

Las respuestas `--json` de comandos de acción incluyen un array `breadcrumbs`
con los siguientes comandos sugeridos. Los logs en streaming emiten NDJSON (un
objeto JSON por línea).

<Warning>
  Los flags de modo son **solo de salida**, nunca de seguridad. La preservación de
  colisiones, el rechazo de `push` ante incoming sin resolver, la validación de
  esquema y los chequeos de estado sucio siempre corren, con o sin `--agent`. Las
  operaciones destructivas requieren `--yes` en modo JSON/agente — y ese flag es
  para CI, no un atajo para saltarse confirmaciones.
</Warning>

## Introspección con `--describe`

`--describe` recorre el árbol de comandos y emite su firma como JSON, sin
ejecutar nada. Es de solo lectura — úsalo para planear.

```bash theme={null}
jelou --describe                       # comando raíz: lista subcomandos top-level
jelou project --describe               # subcomandos de project
jelou databases create --describe      # argumentos y opciones de un comando
```

Devuelve `{ command, description, arguments, options, examples, subcommands }`.
Los flags globales se filtran para que solo veas la superficie específica del
comando.

## Exit codes

El CLI usa códigos de salida granulares para que un agente ramifique sin parsear
stderr:

| Código | Significado                  | Causa típica                                                                     |
| ------ | ---------------------------- | -------------------------------------------------------------------------------- |
| 0      | Éxito                        | —                                                                                |
| 1      | Genérico / desconocido       | Fallos de build, errores sin categoría                                           |
| 2      | Input / validación           | Flag inválido, argumento faltante, esquema no coincide                           |
| 3      | No encontrado                | id, slug o nombre desconocido                                                    |
| 4      | Auth / prohibido             | Token faltante o expirado, scope insuficiente                                    |
| 5      | DB no lista                  | Base de datos aún provisionándose                                                |
| 6      | Transitorio / API            | 5xx, timeout de red — seguro reintentar                                          |
| 7      | Conflicto de estado          | Drift de lockfile, incoming sin resolver, push parcial                           |
| 8      | Secret detectado (reservado) | El escáner de secrets existe pero todavía no está conectado en producción        |
| 9      | Lock ocupado                 | Otro `jelou pull`/`push` en curso                                                |
| 10     | Desajuste de esquema local   | El esquema de `qa.db` es incompatible (`QA_SCHEMA_MISMATCH`) — actualiza `jelou` |

Los códigos 7-9 son específicos de `jelou pull`/`push`/`incoming` (el 8 está
reservado y aún no se emite en rutas de producción). El código 10 aparece si
el toolchain local quedó desactualizado respecto al esquema que espera el CLI.
En modo `--json`, el mismo código aparece en `error.code` con un campo `hint`
que sugiere el siguiente comando.

## Variables de entorno

| Variable                   | Descripción                                                               |
| -------------------------- | ------------------------------------------------------------------------- |
| `JELOU_TOKEN`              | Token de autenticación (máxima prioridad; sin necesidad de `jelou login`) |
| `JELOU_PROFILE`            | Perfil por defecto                                                        |
| `JELOU_NO_INPUT`           | `1` para modo no interactivo                                              |
| `JELOU_FORCE_HUMAN_OUTPUT` | `1` para forzar salida legible aunque stdout esté redirigido              |
| `NO_COLOR`                 | `1` para desactivar colores ANSI                                          |
| `JELOU_NO_SPINNERS`        | `1` para desactivar los spinners de progreso (implícito con `--agent`)    |
| `CI`                       | Detectado automáticamente para modo no interactivo                        |

## Comandos de mantenimiento

```bash theme={null}
jelou update --agent     # ¿hay una versión nueva? (solo lectura)
jelou doctor --json      # chequeo de salud (api, auth, perfil, lockfile, proyecto, authoring, skills, versión)
jelou changelog          # notas de versión
jelou feedback           # envía un reporte (siempre pregunta primero)
```

Para actualizar el CLI:

```bash theme={null}
npm install -g @jelou/cli@latest
jelou --version
jelou agent install --global --all-targets --yes --no-input   # refresca las skills
```

<Tip>
  Para consultar la analítica de la empresa (catálogo, una métrica o un tablero
  completo) usa `jelou metrics` — tiene su propia página en
  [Métricas](/guides/cli/metrics).
</Tip>