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

# Debug and inspect

> Preview mka1 CLI requests with --dry-run, trace them live with --debug, explore the command tree interactively, and enable agent mode for AI coding tools.

The CLI ships with a handful of diagnostic flags that are available on every command. They are the fastest way to understand what the CLI is about to send, why a request failed, or what your credentials look like to the gateway.

## Preview a request with `--dry-run`

Print the request that would be sent without contacting the API:

```bash theme={null}
mka1 llm responses create \
  --model auto \
  --input '"Summarize the day."' \
  --dry-run
```

Dry-run output is written to **stderr** and includes:

* HTTP method and URL.
* Request headers (sensitive values redacted).
* A preview of the request body (sensitive fields redacted).

The command exits successfully without executing. Use it to sanity-check how flags, `--body`, and stdin combine into the final body, and to verify which headers are attached before running for real.

## Trace live traffic with `--debug`

Run the command normally and log the full request / response exchange to stderr:

```bash theme={null}
mka1 llm responses create \
  --model auto \
  --input '"Summarize the day."' \
  --debug
```

Debug output includes:

* Request method, URL, headers, and body preview.
* Response status, headers, and body preview.
* Transport errors (DNS, TLS, timeouts, and so on).

Your regular stdout is untouched, so you can combine `--debug` with `--output-format json` or a `--jq` filter without the two streams colliding:

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

If you pass both `--dry-run` and `--debug`, `--dry-run` wins and no network call is made.

## Redaction in diagnostic output

The CLI redacts secrets it can detect before printing:

* **Headers** — `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, and other security headers are shown as `[REDACTED]`.
* **Body** — JSON fields named `password`, `secret`, `token`, `api_key`, `client_secret`, and similar are shown as `[REDACTED]`.

Treat diagnostic output as operational data anyway — it still reveals request URLs, resource IDs, and other context a third party should not see.

## Explore the command tree

Launch the interactive terminal UI to browse every command group and execute one without leaving the shell:

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

Use it when you are not sure which subcommand to reach for or which flags a command accepts. You can filter, inspect descriptions, and jump straight into execution.

When you want a non-interactive alternative, `mka1 --usage` prints the full command schema in [KDL](https://kdl.dev/) so you can machine-process it.

## Agent mode

`--agent-mode` changes the CLI's defaults to be friendlier to AI coding tools:

* Errors are returned as structured objects instead of free-form prose.
* The default output format becomes `toon` (compact, token-efficient).

The flag is auto-enabled when the CLI detects a known agent environment — for example, when `CLAUDE_CODE` or `CURSOR_AGENT` is set. Pass `--agent-mode=false` to opt out, or set it explicitly to force it on in unknown environments:

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

## Timeouts, custom servers, and extra headers

A few more inherited flags are worth knowing about:

* `--timeout 30s` — cap the HTTP request duration. Accepts `ms`, `s`, or `m` suffixes.
* `--server-url https://custom-api.example.com` — override the base URL entirely.
* `--server <name|index>` — pick a named or indexed server from the CLI's built-in list.
* `-H 'Header-Name: value'` — attach an arbitrary header. Repeatable.
* `--no-interactive` — disable every interactive prompt (auto-prompting, explorer auto-launch, TUI forms). Use this in 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
```

## Troubleshooting recipe

When a command behaves unexpectedly, this order usually gets you to the answer fastest:

1. Run with `--dry-run` to confirm the URL, headers, and body.
2. Run `mka1 auth whoami` to confirm which credential is in effect and where it came from.
3. Re-run with `--debug 2> debug.log` to capture the full request and response.
4. If the response is non-obvious, re-run with `--include-headers --output-format json --jq '.'` so the full payload and headers are printed together.