> ## 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.

# Depure e inspecione

> Visualize solicitações do mka1 CLI com --dry-run, rastreie-as ao vivo com --debug, explore a árvore de comandos interativamente e ative o modo agente para ferramentas de codificação com IA.

A CLI vem com algumas flags de diagnóstico que estão disponíveis em todos os comandos. Elas são a maneira mais rápida de entender o que a CLI está prestes a enviar, por que uma solicitação falhou ou como suas credenciais aparecem para o gateway.

## Visualize uma solicitação com `--dry-run`

Imprima a solicitação que seria enviada sem contatar a API:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Resuma o dia."' \
  --dry-run
```

A saída do dry-run é escrita em **stderr** e inclui:

* Método HTTP e URL.
* Cabeçalhos da solicitação (valores sensíveis são ocultados).
* Uma prévia do corpo da solicitação (campos sensíveis ocultados).

O comando é finalizado com sucesso sem ser executado. Use isso para conferir como flags, `--body` e stdin se combinam no corpo final, e para verificar quais cabeçalhos serão anexados antes de executar de verdade.

## Rastreie o tráfego ao vivo com `--debug`

Execute o comando normalmente e registre toda a troca de solicitação/resposta em stderr:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Resuma o dia."' \
  --debug
```

A saída de debug inclui:

* Método da solicitação, URL, cabeçalhos e prévia do corpo.
* Status da resposta, cabeçalhos e prévia do corpo.
* Erros de transporte (DNS, TLS, timeouts, etc).

Seu stdout regular permanece intacto, então você pode combinar `--debug` com `--output-format json` ou um filtro `--jq` sem que os dois fluxos se misturem:

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

Se você passar tanto `--dry-run` quanto `--debug`, `--dry-run` prevalece e nenhuma chamada de rede é feita.

## Redação na saída de diagnóstico

A CLI oculta segredos que consegue detectar antes de imprimir:

* **Cabeçalhos** — `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` e outros cabeçalhos de segurança são exibidos como `[REDACTED]`.
* **Corpo** — Campos JSON chamados `password`, `secret`, `token`, `api_key`, `client_secret` e similares são exibidos como `[REDACTED]`.

Ainda assim, trate a saída de diagnóstico como dados operacionais — ela revela URLs de solicitações, IDs de recursos e outros contextos que terceiros não deveriam ver.

## Explore a árvore de comandos

Inicie a interface de terminal interativa para navegar por todos os grupos de comandos e executar um sem sair do shell:

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

Use quando não tiver certeza de qual subcomando utilizar ou quais flags um comando aceita. Você pode filtrar, inspecionar descrições e ir direto para a execução.

Quando quiser uma alternativa não interativa, `mka1 --usage` imprime o esquema completo de comandos em [KDL](https://kdl.dev/) para que você possa processá-lo por máquina.

## Modo agente

`--agent-mode` altera os padrões da CLI para serem mais amigáveis a ferramentas de codificação com IA:

* Erros são retornados como objetos estruturados em vez de texto livre.
* O formato de saída padrão se torna `toon` (compacto, eficiente em tokens).

A flag é ativada automaticamente quando a CLI detecta um ambiente de agente conhecido — por exemplo, quando `CLAUDE_CODE` ou `CURSOR_AGENT` está definido. Passe `--agent-mode=false` para desativar, ou defina explicitamente para forçar a ativação em ambientes desconhecidos:

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

## Timeouts, servidores personalizados e cabeçalhos extras

Algumas outras flags herdadas valem a pena conhecer:

* `--timeout 30s` — limita a duração da solicitação HTTP. Aceita sufixos `ms`, `s` ou `m`.
* `--server-url https://custom-api.example.com` — sobrescreve completamente a URL base.
* `--server <nome|índice>` — escolha um servidor nomeado ou indexado da lista interna da CLI.
* `-H 'Header-Name: value'` — anexa um cabeçalho arbitrário. Repetível.
* `--no-interactive` — desativa todos os prompts interativos (auto-prompting, explorer automático, formulários TUI). Use isso em 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
```

## Receita de solução de problemas

Quando um comando se comporta de forma inesperada, esta ordem geralmente te leva à resposta mais rapidamente:

1. Execute com `--dry-run` para confirmar a URL, cabeçalhos e corpo.
2. Execute `mka1 auth whoami` para confirmar qual credencial está em uso e de onde ela veio.
3. Execute novamente com `--debug 2> debug.log` para capturar toda a solicitação e resposta.
4. Se a resposta não for óbvia, execute novamente com `--include-headers --output-format json --jq '.'` para que o payload completo e os cabeçalhos sejam impressos juntos.