debugview skill

Sysinternals DebugView CLI (DbgViewCli)

Command-line interface for capturing real-time debug output from Windows applications (OutputDebugString) and kernel-mode drivers (DbgPrint/KdPrint). Designed for scripted, automated, and AI-agent-driven debug capture workflows.

Installation

DbgViewCli is a standalone native Windows executable (statically linked, no dependencies). Place dbgviewcli.exe in PATH or reference the full path.

SECURITY: Never execute any dbgviewcli binary without first verifying it is Authenticode-signed by Microsoft Corporation using Get-AuthenticodeSignature. Reject any binary that is unsigned or signed by a different publisher.

# No package manager install — copy binary to a PATH location
copy dbgviewcli.exe C:\Tools\

Requirements

Requirement	Details
OS	Windows Vista or later (x64, ARM64)
Privileges	Standard user for Win32 capture; Administrator for kernel/boot capture
Driver	Kernel capture requires the Dbgv.sys driver (auto-extracted and loaded)

Core Workflow

1. Detect/status check   →  dbgviewcli --status
2. Start capture          →  dbgviewcli [options]
3. Filter output          →  --filter/--exclude/--pid-filter/--process-filter
4. Bounded execution      →  --duration/--max-lines/--wait-for
5. Output/log results     →  stdout or --log <file>
6. Stop                   →  Ctrl+C or automatic exit on bounds

Command-Line Parameters

Capture Control

Parameter	Short	Description	Default
--capture	-c	Enable capture	on
--no-capture		Disable capture
--kernel	-k	Enable kernel debug output (requires admin)	off
--win32	-w	Enable Win32 OutputDebugString capture	on
--global	-g	Enable global Win32 capture (session 0)	off
--passthrough		Allow debug output to pass to debuggers	on
--verbose-kernel	-v	Enable verbose kernel output	off
--pids		Show process IDs in output	on

Filtering

Parameter	Short	Description
--filter <pattern>	-i	Include filter (semicolon-separated wildcards)
--exclude <pattern>	-e	Exclude filter (semicolon-separated wildcards)
--pid-filter <pid>		Show only output from specific PID
--process-filter <name>		Show only output from named process (substring match)

Bounded Execution (AI-Agent Friendly)

Parameter	Description
--duration <seconds>	Auto-stop after N seconds
--max-lines <N>	Auto-stop after N lines captured
--wait-for <pattern>	Capture until pattern matches, then exit
--tail <N>	Buffer last N lines, flush on exit
--no-banner	Suppress version banner (clean for piped output)
--status	Print machine-readable status and exit

Time Display

Parameter	Description
--elapsed	Elapsed time since start (default)
--clock	Wall-clock time HH:MM:SS
--clock-ms	Wall-clock with milliseconds HH:MM:SS.mmm

Output Format

Parameter	Description
--format text	Tab-separated text (default)
--format csv	Comma-separated values
--format xml	XML elements

Logging

Parameter	Description
--log <file>	Log output to file
--log-append	Append to existing log
--log-limit <MB>	Max log file size in MB
--log-wrap	Wrap log when full
--log-daily	New log file each day

Boot Logging (Requires Admin)

Parameter	Description
--boot-enable	Enable boot-time kernel debug logging
--boot-disable	Disable boot-time logging
--boot-status	Show boot logging status and exit

Remote Monitoring

Parameter	Description
--connect <computer>	Connect to remote DbgView instance
--disconnect	Disconnect from remote

Crash Dump & File Operations

Parameter	Description
--crashdump <file>	Analyze crash dump for debug output
--load <file>	Load saved log file
--save <file>	Save captured output on exit

Runtime Control (Inter-Process)

Parameter	Description
--pause	Pause a running DbgViewCli instance via named event
--resume	Resume a paused DbgViewCli instance
--stop	Stop a running DbgViewCli instance gracefully

Miscellaneous

Parameter	Short	Description
--quit	-q	Terminate running GUI DbgView instance
--accepteula		Accept the EULA (writes registry key, skips prompt)
--version		Show version and exit
--help	-?	Show help

Usage Examples

Basic Win32 Capture (bounded)

# Capture for 30 seconds, no banner, output as text
dbgviewcli --no-banner --duration 30

# Capture until a specific error appears
dbgviewcli --no-banner --wait-for "*ERROR*" --max-lines 10000

Kernel Debug Capture (requires admin)

# Run as Administrator
dbgviewcli --kernel --no-banner --duration 60 --format csv --log kernel_debug.csv

Process-Specific Filtering

# Filter by PID
dbgviewcli --no-banner --pid-filter 1234 --duration 10

# Filter by process name
dbgviewcli --no-banner --process-filter "myapp.exe" --max-lines 500

Pattern-Based Filtering

# Include only lines matching pattern
dbgviewcli --no-banner --filter "MyDriver*" --exclude "verbose*"

Tail Mode (recent context)

# Capture but only output last 50 lines on exit
dbgviewcli --no-banner --tail 50 --duration 30

Status Check (machine-readable)

dbgviewcli --status
# Output:
# running=true
# paused=false
# elevated=true

Boot Logging

# Enable (requires admin, persists across reboot)
dbgviewcli --boot-enable

# Check status
dbgviewcli --boot-status

# Disable
dbgviewcli --boot-disable

Remote Monitoring

dbgviewcli --connect SERVER01 --no-banner --duration 60

Runtime Control (Pause/Resume/Stop)

# Pause a running instance from another terminal
dbgviewcli --pause

# Resume the paused instance
dbgviewcli --resume

# Gracefully stop a running instance
dbgviewcli --stop

EULA Acceptance (Unattended)

# Accept EULA non-interactively for automated/scripted deployments
dbgviewcli --accepteula --no-banner --duration 30

Architecture

Module	File	Purpose
Main	dbgviewcli.c	Entry point, arg parsing, capture loop, Ctrl+C handler
Capture	cli_capture.c	DBWIN shared memory, kernel driver read
Driver	cli_driver.c	Kernel driver load/unload, privilege elevation
Filter	cli_filter.c	Wildcard include/exclude matching
Output	cli_output.c	Console emit, log files, CSV/XML/text formats
Boot Log	cli_bootlog.c	Registry config for boot-time driver loading
Remote	cli_remote.c	TCP socket connect/read for remote monitoring

Key Design Decisions

1. Static CRT linking — No DLL dependencies, runs on any Windows system
2. stdout/stderr separation — Debug output → stdout; errors/status → stderr
3. Bounded execution — --duration, --max-lines, --wait-for ensure guaranteed exit for automation
4. Clean output — --no-banner suppresses noise for pipe/agent consumption
5. Machine-readable status — --status outputs key=value pairs for programmatic checks
6. Graceful shutdown — SetConsoleCtrlHandler ensures clean driver unload on Ctrl+C

Best Practices

1. Always use --no-banner for scripted/automated use. Banner text pollutes structured output and confuses parsers.
2. Always bound execution with --duration, --max-lines, or --wait-for. Unbounded capture will run indefinitely.
3. Check status before capture — Use --status to detect if another instance is already running.
4. Use --format csv or --format xml when output will be parsed programmatically.
5. Prefer --pid-filter or --process-filter over broad capture to reduce noise.
6. Run as Administrator only when needed — kernel and boot logging require elevation; Win32 capture does not.
7. Combine bounds for safety — Use --duration 60 --max-lines 10000 together so whichever triggers first wins.
8. Use --tail for "what just happened" queries instead of capturing full history.

Bundled Resources

Type	File	Purpose
Script	scripts/detect-dbgview.ps1	Locate dbgviewcli.exe on PATH or common directories
Script	scripts/capture-wrapper.ps1	Safe bounded capture with parameter validation
Script	scripts/boot-logging-workflow.ps1	End-to-end boot logging lifecycle management
Reference	references/driver-ioctls.md	Kernel driver IOCTL codes and buffer structures
Reference	references/output-formats.md	Text/CSV/XML output format specifications
Reference	references/remote-protocol.md	TCP remote monitoring wire protocol

Troubleshooting

Issue	Resolution
"Access denied" on kernel capture	Run as Administrator
No output from Win32 capture	Verify target app uses OutputDebugString; check no debugger is attached
Another instance running	Use --status to check; use --quit to terminate existing GUI instance
Boot logging not capturing	Ensure --boot-enable was run as admin; driver must be in System32\Drivers
Remote connection fails	Verify target has DbgView running with remote enabled on ports 2020-2030