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

# Depurar e inspeccionar

> Previsualiza las solicitudes del CLI mka1 con --dry-run, rastrea en vivo con --debug, explora el árbol de comandos de forma interactiva y habilita el modo agente para herramientas de codificación con IA.

El CLI incluye un conjunto de banderas de diagnóstico que están disponibles en cada comando. Son la forma más rápida de entender qué está a punto de enviar el CLI, por qué falló una solicitud o cómo se ven tus credenciales para el gateway.

## Previsualiza una solicitud con `--dry-run`

Imprime la solicitud que se enviaría sin contactar la API:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-es-mini \
  --input '"Summarize the day."' \
  --dry-run
```

La salida de dry-run se escribe en **stderr** e incluye:

* Método HTTP y URL.
* Cabeceras de la solicitud (valores sensibles redactados).
* Una vista previa del cuerpo de la solicitud (campos sensibles redactados).

El comando finaliza correctamente sin ejecutarse. Úsalo para verificar cómo las banderas, `--body` y la entrada estándar (stdin) se combinan en el cuerpo final, y para comprobar qué cabeceras se adjuntan antes de ejecutar realmente.

## Rastrea el tráfico en vivo con `--debug`

Ejecuta el comando normalmente y registra el intercambio completo de solicitud/respuesta en stderr:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-es-mini \
  --input '"Summarize the day."' \
  --debug
```

La salida de depuración incluye:

* Método de la solicitud, URL, cabeceras y vista previa del cuerpo.
* Estado de la respuesta, cabeceras y vista previa del cuerpo.
* Errores de transporte (DNS, TLS, tiempos de espera, etc.).

Tu salida estándar regular permanece intacta, así que puedes combinar `--debug` con `--output-format json` o un filtro `--jq` sin que los dos flujos colisionen:

```bash theme={null}
mka1 llm models list --debug --jq '.data[].id' 2> debug.log
```

Si pasas tanto `--dry-run` como `--debug`, `--dry-run` tiene prioridad y no se realiza ninguna llamada de red.

## Redacción en la salida de diagnóstico

El CLI redacta los secretos que puede detectar antes de imprimir:

* **Cabeceras** — `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` y otras cabeceras de seguridad se muestran como `[REDACTED]`.
* **Cuerpo** — Los campos JSON llamados `password`, `secret`, `token`, `api_key`, `client_secret` y similares se muestran como `[REDACTED]`.

De todas formas, trata la salida de diagnóstico como datos operativos: aún revela URLs de solicitudes, IDs de recursos y otro contexto que un tercero no debería ver.

## Explora el árbol de comandos

Lanza la interfaz de terminal interactiva para explorar cada grupo de comandos y ejecutar uno sin salir de la terminal:

```bash theme={null}
mka1 explore
```

Úsalo cuando no estés seguro de qué subcomando necesitas o qué banderas acepta un comando. Puedes filtrar, inspeccionar descripciones y saltar directamente a la ejecución.

Cuando quieras una alternativa no interactiva, `mka1 --usage` imprime el esquema completo de comandos en [KDL](https://kdl.dev/) para que puedas procesarlo con una máquina.

## Modo agente

`--agent-mode` cambia los valores predeterminados del CLI para ser más amigable con herramientas de codificación con IA:

* Los errores se devuelven como objetos estructurados en lugar de prosa libre.
* El formato de salida predeterminado se convierte en `toon` (compacto, eficiente en tokens).

La bandera se habilita automáticamente cuando el CLI detecta un entorno de agente conocido — por ejemplo, cuando `CLAUDE_CODE` o `CURSOR_AGENT` está establecido. Pasa `--agent-mode=false` para desactivarlo, o establécelo explícitamente para forzarlo en entornos desconocidos:

```bash theme={null}
mka1 llm models list --agent-mode
```

## Tiempos de espera, servidores personalizados y cabeceras extra

Vale la pena conocer algunas banderas heredadas adicionales:

* `--timeout 30s` — limita la duración de la solicitud HTTP. Acepta los sufijos `ms`, `s` o `m`.
* `--server-url https://custom-api.example.com` — sobrescribe completamente la URL base.
* `--server <name|index>` — elige un servidor nombrado o indexado de la lista interna del CLI.
* `-H 'Header-Name: value'` — adjunta una cabecera arbitraria. Repetible.
* `--no-interactive` — desactiva cualquier aviso interactivo (auto-prompts, lanzamiento automático del explorador, formularios TUI). Úsalo en CI.

```bash theme={null}
mka1 llm models list \
  --server-url https://custom-api.example.com \
  --timeout 10s \
  -H 'X-Request-Id: audit-42' \
  --no-interactive
```

## Receta para resolución de problemas

Cuando un comando se comporta de forma inesperada, este orden suele llevarte a la respuesta más rápido:

1. Ejecuta con `--dry-run` para confirmar la URL, cabeceras y cuerpo.
2. Ejecuta `mka1 auth whoami` para confirmar qué credencial está en uso y de dónde proviene.
3. Vuelve a ejecutar con `--debug 2> debug.log` para capturar la solicitud y respuesta completas.
4. Si la respuesta no es obvia, vuelve a ejecutar con `--include-headers --output-format json --jq '.'` para que la carga útil completa y las cabeceras se impriman juntas.