# CLI Debug

Low-level debugging utilities under packages/nikcli/src/cli/cmd/debug — for contributors and support, not everyday use.

## When to use

The `nikcli debug …` tree exposes internal probes: resolved config, global paths, agent tool access, LSP round-trips, and ripgrep-backed file helpers. For install health and common fixes, prefer `nikcli doctor` (see [CLI Reference](/docs/cli)).

debug config vs doctor

Use `debug config` when you need the full merged JSONC config and paths as the runtime sees them. Use `doctor` when you want guided checks (providers, MCP, disk, versions) without dumping raw internals.

Examples

bash 

```
nikcli debug config
nikcli debug agent build
nikcli debug paths
```

$ shell · paste into your terminal

## Debug Commands

<table class="doc-table"><tbody><tr><td><code>debug config</code></td><td>Print resolved configuration.</td></tr><tr><td><code>debug scrap</code></td><td>List known projects (Project.list()).</td></tr><tr><td><code>debug skill</code></td><td>List skills discovered by the runtime.</td></tr><tr><td><code>debug agent &lt;name&gt;</code></td><td>Inspect agent config and resolved tool access.</td></tr><tr><td><code>debug paths</code></td><td>Print global path locations.</td></tr><tr><td><code>debug wait</code></td><td>Sleep indefinitely (diagnostic).</td></tr></tbody></table>

## LSP Debug

These commands call the same LSP stack documented on [LSP](/docs/lsp). Use them when agent `context_diagnostics` or the `lsp` tool misbehaves for a given file.

<table class="doc-table"><tbody><tr><td><code>debug lsp diagnostics &lt;file&gt;</code></td><td>Fetch diagnostics via LSP.</td></tr><tr><td><code>debug lsp symbols &lt;query&gt;</code></td><td>Search workspace symbols.</td></tr><tr><td><code>debug lsp document-symbols &lt;uri&gt;</code></td><td>Document symbol listing.</td></tr></tbody></table>

## File + RG

Not a substitute for agent tools

These mirror file/search behavior used by tools like `read`, `glob`, and `grep`, but return JSON for scripting. Agents should still use the public tool surface.

<table class="doc-table"><tbody><tr><td><code>debug file read &lt;path&gt;</code></td><td>Read file as JSON payload.</td></tr><tr><td><code>debug file status</code></td><td>Show file status information.</td></tr><tr><td><code>debug file list &lt;path&gt;</code></td><td>List directory contents.</td></tr><tr><td><code>debug file tree [dir]</code></td><td>Tree listing via ripgrep.</td></tr><tr><td><code>debug rg search &lt;pattern&gt;</code></td><td>Run ripgrep search.</td></tr><tr><td><code>debug rg files</code></td><td>List files via ripgrep.</td></tr><tr><td><code>debug rg tree</code></td><td>Print ripgrep tree view.</td></tr></tbody></table>

## Snapshots

<table class="doc-table"><tbody><tr><td><code>debug snapshot track</code></td><td>Track current snapshot state.</td></tr><tr><td><code>debug snapshot patch &lt;hash&gt;</code></td><td>View patch for snapshot hash.</td></tr><tr><td><code>debug snapshot diff &lt;hash&gt;</code></td><td>View diff for snapshot hash.</td></tr></tbody></table>

## Related

-   [CLI Reference User-facing commands including doctor and diagnostics.](/docs/cli)
-   [LSP Language server setup and agent LSP tool behavior.](/docs/lsp)
-   [Configuration Config keys that debug config prints.](/docs/configuration)

---

Source: https://nikcli-ai.dev/docs/cli-debug