dotnet-diagnostics-cli 0.12.0

dotnet-diagnostics-cli

A standalone command-line tool for on-demand performance diagnostics on running .NET 10 applications — no instrumentation, no MCP client, no HTTP server, no bearer token, no daemon.

It runs the same Core diagnostics engine as the dotnet-diagnostics-mcp MCP server, but as a tool a human (or a script / CI job) drives directly. Attach to a live process, collect a window of events, walk the heap, or write a dump — then exit. A stateful session REPL keeps collected artifacts queryable across commands so you can drill in without re-collecting.

Two packages, one engine. Install this package (dotnet-diagnostics-cli) for interactive / scripted human use. Install dotnet-diagnostics-mcp instead when you want an MCP server that exposes diagnostics as tools to an LLM over HTTP or stdio.

Install

dotnet tool install -g dotnet-diagnostics-cli   # requires the .NET 10 SDK

Self-contained, per-OS binaries (no SDK required) are attached to every GitHub Release as dotnet-diagnostics-cli-<version>-<rid>. The diagnostics sidecar container image also ships the CLI on PATH, so kubectl exec … -- dotnet-diagnostics-cli … works inside the pod.

One-shot usage

# Discover attachable .NET processes
dotnet-diagnostics-cli processes

# Probe a target's capability matrix (CoreCLR vs NativeAOT, what's usable)
dotnet-diagnostics-cli capabilities --pid 1234

# Collect a 5s EventCounters window
dotnet-diagnostics-cli collect --kind counters --pid 1234 --duration 5

# Walk the managed heap (top retained types)
dotnet-diagnostics-cli inspect-heap --pid 1234 --top-types 30

# Write a heap dump to disk (preview without --confirm)
dotnet-diagnostics-cli dump --pid 1234 --dump-type WithHeap --out ./dumps --confirm

--pid is optional — it is auto-resolved when exactly one .NET process is visible. Pass --json on any command to emit the raw DiagnosticResult envelope for scripting. Run dotnet-diagnostics-cli --help or <command> --help for the full flag reference.

Commands

The session REPL

One-shot commands build the diagnostic host, run, and exit — so a drill-down query has nothing to query. session keeps the host (and every collected handle) alive across commands:

dotnet-diagnostics-cli session
diag> target 1234                       # bind a target pid once
diag(pid 1234)> collect --kind gc --duration 10
  → handle 1TA2BA7KT9PYT60WTWE0 — query --handle 1TA2BA7KT9PYT60WTWE0 --view <pauseHistogram|...>
diag(pid 1234)> query --handle 1TA2BA7KT9PYT60WTWE0 --view pauseHistogram
diag(pid 1234)> exit

• target <pid> binds a default pid so live-target commands (capabilities, collect, dump, inspect-heap --source live, get-bytes --kind module) no longer need --pid. target shows the current binding; target clear unbinds. An explicit --pid always overrides the binding.
• Handles published by collect / inspect-heap stay queryable until they expire or the target exits, so query --handle <id> --view <view> drills in without re-collecting.
• Ctrl-C cancels the running command and keeps the session alive; press it again to force-quit. An idle Ctrl-C leaves the session.

Documentation

• Full CLI reference: docs/cli-reference.md
• Project README & MCP server: github.com/pedrosakuma/dotnet-diagnostics-mcp

Linux note (ClrMD-backed tools)

inspect-heap --source live and dump attach via ptrace(2). On Debian/Ubuntu/WSL the default kernel.yama.ptrace_scope=1 blocks same-UID peer attach — run echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope (or grant CAP_SYS_PTRACE in a container). EventPipe-based tools (collect, counters, GC, exceptions) are unaffected.

License

MIT © pedrosakuma