{"command":"hins","commands":[{"command":"hins ui","description":"Open the interactive UI (Web / DAP). Default when no command is given.","options":[{"flags":["--dap-stdio"],"help":"DAP-over-stdio frontend only","kind":"flag","metavar":""},{"flags":["--web"],"help":"Web frontend","kind":"flag","metavar":""},{"flags":["--with-dap"],"help":"Also start DAP-over-stdio alongside web","kind":"flag","metavar":""},{"flags":["--port"],"help":"Web server port (0 = let the OS pick a free port) (default: 3000)","kind":"option","metavar":"N"},{"flags":["--web-port-file"],"help":"Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable)","kind":"option","metavar":"PATH"},{"flags":["--web-unix-socket"],"help":"Serve HTTP over an AF_UNIX socket at PATH instead of a TCP port (overrides --port; reaches clients across a sandbox network namespace via a socat bridge)","kind":"option","metavar":"PATH"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins ui [--dap-stdio | [--web] [--with-dap]] [--port N] [--web-port-file PATH] [--web-unix-socket PATH]"},{"command":"hins fragmentation","description":"Block / MBlock fragmentation report. Implicitly pauses.","options":[{"flags":["--include-pinned"],"help":"Include pinned blocks in the breakdown","kind":"flag","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins fragmentation [--include-pinned]"},{"command":"hins consistency","description":"Heap consistency check. Exits non-zero on violations. Implicitly pauses.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins consistency"},{"command":"hins closure","description":"Inspect a single closure by id. Implicitly pauses.","options":[{"flags":["ID"],"help":"Closure id (hex address)","kind":"argument","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins closure ID"},{"command":"hins mvars","description":"MVar inventory (paused).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins mvars"},{"command":"hins tvars","description":"TVar inventory (paused).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins tvars"},{"command":"hins blackholes","description":"Blackhole inventory (paused).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins blackholes"},{"command":"hins weaks","description":"Weak reference inventory (paused).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins weaks"},{"command":"hins cc-stacks","description":"Cost-centre stack census (target compiled with -prof).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins cc-stacks"},{"command":"hins pinned","description":"Pinned-block inventory.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins pinned"},{"command":"hins blocks","description":"MBlock / block allocation map.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins blocks"},{"command":"hins ticky","description":"Dump ticky-ticky counters (target compiled with -ticky).","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins ticky"},{"command":"hins heql","description":"Run HEQL (the Heap Exploration Query Language) over the paused heap. Implicitly pauses.","options":[{"flags":["--source"],"help":"Inline query catalog (DSL text). Overrides --file and the built-in defaults.","kind":"option","metavar":"TEXT"},{"flags":["--file"],"help":"Read the query catalog from PATH instead of the built-in default catalog.","kind":"option","metavar":"PATH"},{"flags":["--tag"],"help":"Run only the query whose tag matches TAG.","kind":"option","metavar":"TAG"},{"flags":["--print"],"help":"Parse the catalog and report each query without attaching (surfaces parse errors).","kind":"flag","metavar":""},{"flags":["--ast"],"help":"heql: parse the catalog and print each declaration's parse tree; no typechecking, no debuggee.","kind":"flag","metavar":""},{"flags":["--stdlib"],"help":"heql: print the standard library reference (names, types, grades, descriptions); no debuggee.","kind":"flag","metavar":""},{"flags":["--explain"],"help":"heql: print each query's intermediate representations (HEQL Core, FLAX Plan, FLAX bytecode); no debuggee.","kind":"flag","metavar":""},{"flags":["--arg"],"help":"heql: override a view parameter (repeatable). EXPR is HEQL expression text, checked against the parameter's type.","kind":"option","metavar":"NAME=EXPR"},{"flags":["--expand-depth"],"help":"heql: auto-run each row's lazy `expand` handles to depth N, splicing sub-tables into the result as `expanded` entries. Handles beyond the ceiling stay listed unexpanded; a handle revisiting a node on its own descent path is marked skipped.","kind":"option","metavar":"N"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins heql [--source TEXT] [--file PATH] [--tag TAG] [--print] [--ast] [--stdlib] [--explain] [--arg NAME=EXPR] [--expand-depth N]"},{"command":"hins threads","description":"Print thread states. Combine with --every for live monitoring.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins threads"},{"command":"hins eventlog","description":"Stream eventlog messages. Filter by event kind.","options":[{"flags":["--type"],"help":"Comma-separated event-kind names to include (e.g. GC,HeapAllocated)","kind":"option","metavar":"LIST"},{"flags":["--exclude"],"help":"Comma-separated event-kind names to exclude","kind":"option","metavar":"LIST"},{"flags":["--type-regex"],"help":"Power-user escape hatch: regex over event-kind names","kind":"option","metavar":"RE"},{"flags":["--list-types"],"help":"Print the event kinds the target supports and exit","kind":"flag","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins eventlog [--type LIST] [--exclude LIST] [--type-regex RE] [--list-types]"},{"command":"hins metrics","description":"Stream live time-series metrics.","options":[{"flags":["--series"],"help":"Restrict to the given metric series; may be repeated","kind":"option","metavar":"NAME"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins metrics [--series NAME]"},{"command":"hins sample","commands":[{"command":"hins sample stacks","description":"Run the STG stack sampler and emit raw samples.","options":[{"flags":["--period"],"help":"Sampler period in microseconds","kind":"option","metavar":"US"},{"flags":["--budget"],"help":"Max samples per tick","kind":"option","metavar":"N"},{"flags":["--no-resolve"],"help":"Keep frame names as raw hex info-table pointers","kind":"flag","metavar":""},{"flags":["--resolve"],"help":"Resolve info-table pointers to Module.Label names (default)","kind":"flag","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins sample stacks [--period US] [--budget N] [--no-resolve | --resolve]"},{"command":"hins sample native","description":"Run the signal-driven native C-stack sampler and emit raw PC samples.","options":[{"flags":["--period"],"help":"Sampler period in microseconds","kind":"option","metavar":"US"},{"flags":["--budget"],"help":"Max OS threads signalled per tick","kind":"option","metavar":"N"},{"flags":["--backend"],"help":"Native-stack sampler to drive: 'signal' (in-handler walk), 'external' (walk the target from outside it; on Linux the eBPF snapshot engine when the debuggee has CAP_BPF+CAP_PERFMON, falling back to the signal sampler otherwise; thread-suspend on macOS/Windows), or 'auto' (default: signal where available)","kind":"option","metavar":"auto|signal|external"},{"flags":["--off-cpu"],"help":"eBPF off-CPU profiling: sample where threads block and for how long (Linux, needs the eBPF engine)","kind":"flag","metavar":""},{"flags":["--min-block"],"help":"off-CPU: ignore blocks shorter than US microseconds (default 1000)","kind":"option","metavar":"US"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins sample native [--period US] [--budget N] [--backend auto|signal|external] [--off-cpu] [--min-block US]"}],"description":"Sampling subcommands.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins sample COMMAND"},{"command":"hins bp","description":"Add a software code breakpoint on a function and stream hits (Linux/x86-64, trace mode).","options":[{"flags":["FUNCTION"],"help":"Function name to break on (matched against the IPE map)","kind":"argument","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins bp FUNCTION"},{"command":"hins exceptions","description":"Capture raised exceptions and aggregate them by type x raise site (live stream).","options":[{"flags":["--sync"],"help":"Capture synchronous exceptions (throw / stg_raisezh)","kind":"flag","metavar":""},{"flags":["--async"],"help":"Capture asynchronous exceptions (throwTo / killThread)","kind":"flag","metavar":""},{"flags":["--message"],"help":"Extract a bounded UTF-8 exception message","kind":"flag","metavar":""},{"flags":["--deep"],"help":"Force exceptions via the RTS hook to recover the real type and message","kind":"flag","metavar":""},{"flags":["--top"],"help":"Show only the top N groups by count","kind":"option","metavar":"N"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins exceptions [--sync] [--async] [--message] [--deep] [--top N]"},{"command":"hins stm-stats","description":"Capture STM transaction outcomes (commit vs conflict re-run) and break down by thread / era / site (live stream, opt-in).","options":[{"flags":["--top"],"help":"Show only the top N conflict sites by count","kind":"option","metavar":"N"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins stm-stats [--top N]"},{"command":"hins record","commands":[{"command":"hins record snapshot","description":"Pause, write a heap snapshot, resume.","options":[{"flags":["--format"],"help":"Snapshot format: hins (default, re-open with --snapshot) or ghc-debug (ghc-debug-brick/-client)","kind":"option","metavar":"FMT"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record snapshot OUT [--format FMT]"},{"command":"hins record eventlog","description":"Drain the eventlog ring buffer to a .eventlog file.","options":[{"flags":["--buffer-mb"],"help":"Ring buffer size","kind":"option","metavar":"N"},{"flags":["--type"],"help":"Restrict to given event kinds","kind":"option","metavar":"LIST"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record eventlog OUT [--buffer-mb N] [--type LIST]"},{"command":"hins record samples","description":"Run the stack sampler and write samples (default format: speedscope).","options":[{"flags":["--period"],"help":"Sampler period in microseconds","kind":"option","metavar":"US"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record samples OUT [--period US]"},{"command":"hins record metrics","description":"Write a metrics file (default format: csv).","options":[{"flags":["--series"],"help":"Restrict to the given metric series","kind":"option","metavar":"NAME"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record metrics OUT [--series NAME]"},{"command":"hins record stack-growth","description":"Arm the threadStackOverflow trap and summarise growth snapshots.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record stack-growth"},{"command":"hins record all","description":"Write snapshot + eventlog + samples + metrics into DIR.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record all DIR"}],"description":"Capture to disk: snapshot / eventlog / samples / metrics / all.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins record COMMAND"},{"command":"hins report","description":"Run a program to completion (or attach until it exits) and print an end-of-run summary: per-thread max stack + allocations, GC/heap, exceptions, stack growth, and contention.","options":[{"flags":["--stack-traces"],"help":"Include the backtrace captured at each stack-growth event","kind":"flag","metavar":""},{"flags":["--exceptions"],"help":"Include exception messages and backtraces (otherwise just counts)","kind":"flag","metavar":""},{"flags":["--top"],"help":"Cap the per-thread tables and leaderboards to the top N entries","kind":"option","metavar":"N"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins report [--stack-traces] [--exceptions] [--top N]"},{"command":"hins list","description":"List live inspectable processes (descriptors published by the connector).","options":[{"flags":["--available"],"help":"Only show non-locked processes; in text format, output tab-separated <pid><TAB><prog> lines with no header for easy scripting (awk/cut/xargs).","kind":"flag","metavar":""},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins list [--available]"},{"command":"hins batch","description":"Run multiple commands against a single pause cycle.","options":[{"flags":["--script"],"help":"Read script from PATH (default: stdin)","kind":"option","metavar":"PATH"},{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins batch [--script PATH]"},{"command":"hins list-formats","description":"List available output formats for CMD, or every command if omitted.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins list-formats [CMD]"},{"command":"hins help-examples","description":"Print worked examples for the common CLI workflows.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""}],"usage":"Usage: hins help-examples"}],"description":"Drive the inspector engine from the shell. Three flag groups are orthogonal: --pid/--descriptor/--snapshot/--eventlog/--run select the target; --every/--repeat/--duration/--until-exit control when and how often the command runs; --output/--format select what the output looks like. Run 'haskell-inspector help-examples' for worked examples, or 'haskell-inspector <command> --help' for command-specific options. Run 'haskell-inspector --list-formats [CMD]' to see which output formats a command supports.","options":[{"flags":["-h","--help"],"help":"Show this help text","kind":"flag","metavar":""},{"flags":["--version"],"help":"Print version and exit","kind":"flag","metavar":""},{"flags":["-p","--pid"],"help":"Attach to PID by looking up its descriptor file","kind":"option","metavar":"PID"},{"flags":["-d","--descriptor"],"help":"Attach via the debuggee descriptor file at PATH (a .desc file written by the connector)","kind":"option","metavar":"PATH"},{"flags":["--snapshot"],"help":"Load a recorded heap snapshot from PATH","kind":"option","metavar":"PATH"},{"flags":["--eventlog"],"help":"Load a .eventlog file from PATH","kind":"option","metavar":"PATH"},{"flags":["-r","--run"],"help":"Spawn PROG with the connector preloaded, then attach. Use --run-arg ARG (repeated) to forward arguments.","kind":"option","metavar":"PROG"},{"flags":["--run-arg"],"help":"Argument forwarded to the spawned program; may be repeated","kind":"option","metavar":"ARG"},{"flags":["--paused"],"help":"Start the spawned program in paused mode (sets HASKELL_INSPECTOR_START_PAUSED for the child)","kind":"flag","metavar":""},{"flags":["--attach-any"],"help":"Attach to the most-recently-published descriptor (optionally filtered by --match-prog / --match-cwd)","kind":"flag","metavar":""},{"flags":["--match-prog"],"help":"With --attach-any: restrict to descriptors whose progname (or exe basename) equals NAME","kind":"option","metavar":"NAME"},{"flags":["--match-cwd"],"help":"With --attach-any: restrict to descriptors whose cwd is at or under DIR (symlinks resolved)","kind":"option","metavar":"DIR"},{"flags":["--log"],"help":"Log level: debug, info, warn, error, off (default: \"error\")","kind":"option","metavar":"LEVEL"},{"flags":["--log-file"],"help":"Send logs to PATH (default: stderr)","kind":"option","metavar":"PATH"},{"flags":["--debug-log"],"help":"Engine debug-hook log file","kind":"option","metavar":"PATH"},{"flags":["--event-buffer-mb"],"help":"Eventlog ring-buffer size in MiB","kind":"option","metavar":"N"},{"flags":["--refresh-interval-ms"],"help":"Engine tick period in milliseconds","kind":"option","metavar":"N"},{"flags":["--sample-capacity"],"help":"Per-sample ring capacity (CC / alloc / STG-stack rings). Default 10_000_000.","kind":"option","metavar":"N"},{"flags":["--list-formats"],"help":"List output formats for CMD (or pass --list-formats with no argument for all) and exit","kind":"option","metavar":"CMD"},{"flags":["--list-all-formats"],"help":"List output formats for every command and exit","kind":"flag","metavar":""},{"flags":["--every"],"help":"Re-run the command every TIME (e.g. 100ms, 5s, 2m, 1h)","kind":"option","metavar":"TIME"},{"flags":["--repeat"],"help":"Stop after N runs/ticks","kind":"option","metavar":"N"},{"flags":["--duration"],"help":"Stop after wall-clock T","kind":"option","metavar":"T"},{"flags":["--until-exit"],"help":"Stop when the target program exits or detaches","kind":"flag","metavar":""},{"flags":["--pause-at"],"help":"Where to pause for analysis: now (default), before-gc, after-gc (the GC modes wait for the next major GC)","kind":"option","metavar":"WHEN"},{"flags":["--request-gc"],"help":"With --pause-at before-gc/after-gc, trigger a major GC now instead of waiting for one","kind":"flag","metavar":""},{"flags":["-o","--output"],"help":"Write report to PATH (- for stdout). Supports {n} {ts} {cmd} placeholders.","kind":"option","metavar":"PATH"},{"flags":["-f","--format"],"help":"Output format. Run --list-formats to see options.","kind":"option","metavar":"FMT"},{"flags":["--pretty"],"help":"Pretty-print JSON","kind":"flag","metavar":""},{"flags":["--no-pretty"],"help":"Don't pretty-print JSON","kind":"flag","metavar":""},{"flags":["--color"],"help":"Force colour","kind":"flag","metavar":""},{"flags":["--no-color"],"help":"Disable colour","kind":"flag","metavar":""},{"flags":["--dap-stdio"],"help":"DAP-over-stdio frontend only","kind":"flag","metavar":""},{"flags":["--web"],"help":"Web frontend","kind":"flag","metavar":""},{"flags":["--with-dap"],"help":"Also start DAP-over-stdio alongside web","kind":"flag","metavar":""},{"flags":["--port"],"help":"Web server port (0 = let the OS pick a free port) (default: 3000)","kind":"option","metavar":"N"},{"flags":["--web-port-file"],"help":"Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable)","kind":"option","metavar":"PATH"},{"flags":["--web-unix-socket"],"help":"Serve HTTP over an AF_UNIX socket at PATH instead of a TCP port (overrides --port; reaches clients across a sandbox network namespace via a socat bridge)","kind":"option","metavar":"PATH"}],"usage":"Usage: hins [--version] [(-p|--pid PID) | (-d|--descriptor PATH) | --snapshot PATH | --eventlog PATH | (-r|--run PROG) [--run-arg ARG] [--paused] | --attach-any [--match-prog NAME] [--match-cwd DIR]] [--log LEVEL] [--log-file PATH] [--debug-log PATH] [--event-buffer-mb N] [--refresh-interval-ms N] [--sample-capacity N] [--list-formats CMD | --list-all-formats] [--every TIME] [--repeat N] [--duration T] [--until-exit] [--pause-at WHEN] [--request-gc] [-o|--output PATH] [-f|--format FMT] [--pretty | --no-pretty] [--color | --no-color] [COMMAND | [--dap-stdio | [--web] [--with-dap]] [--port N] [--web-port-file PATH] [--web-unix-socket PATH]]"}