Command-line reference
Generated from commit e8a491d6e1e2.
The complete command-line interface, generated from the option
parser. The same text is available in your terminal with
hins --help and hins <command> --help. A machine-readable version
is at cli.json.
#Synopsis
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]]
| Option | Description |
|---|---|
-h, --help |
Show this help text |
--version |
Print version and exit |
-p, --pid PID |
Attach to PID by looking up its descriptor file |
-d, --descriptor PATH |
Attach via the debuggee descriptor file at PATH (a .desc file written by the connector) |
--snapshot PATH |
Load a recorded heap snapshot from PATH |
--eventlog PATH |
Load a .eventlog file from PATH |
-r, --run PROG |
Spawn PROG with the connector preloaded, then attach. Use --run-arg ARG (repeated) to forward arguments. |
--run-arg ARG |
Argument forwarded to the spawned program; may be repeated |
--paused |
Start the spawned program in paused mode (sets HASKELL_INSPECTOR_START_PAUSED for the child) |
--attach-any |
Attach to the most-recently-published descriptor (optionally filtered by --match-prog / --match-cwd) |
--match-prog NAME |
With --attach-any: restrict to descriptors whose progname (or exe basename) equals NAME |
--match-cwd DIR |
With --attach-any: restrict to descriptors whose cwd is at or under DIR (symlinks resolved) |
--log LEVEL |
Log level: debug, info, warn, error, off (default: "error") |
--log-file PATH |
Send logs to PATH (default: stderr) |
--debug-log PATH |
Engine debug-hook log file |
--event-buffer-mb N |
Eventlog ring-buffer size in MiB |
--refresh-interval-ms N |
Engine tick period in milliseconds |
--sample-capacity N |
Per-sample ring capacity (CC / alloc / STG-stack rings). Default 10_000_000. |
--list-formats CMD |
List output formats for CMD (or pass --list-formats with no argument for all) and exit |
--list-all-formats |
List output formats for every command and exit |
--every TIME |
Re-run the command every TIME (e.g. 100ms, 5s, 2m, 1h) |
--repeat N |
Stop after N runs/ticks |
--duration T |
Stop after wall-clock T |
--until-exit |
Stop when the target program exits or detaches |
--pause-at WHEN |
Where to pause for analysis: now (default), before-gc, after-gc (the GC modes wait for the next major GC) |
--request-gc |
With --pause-at before-gc/after-gc, trigger a major GC now instead of waiting for one |
-o, --output PATH |
Write report to PATH (- for stdout). Supports {n} {ts} {cmd} placeholders. |
-f, --format FMT |
Output format. Run --list-formats to see options. |
--pretty |
Pretty-print JSON |
--no-pretty |
Don't pretty-print JSON |
--color |
Force colour |
--no-color |
Disable colour |
--dap-stdio |
DAP-over-stdio frontend only |
--web |
Web frontend |
--with-dap |
Also start DAP-over-stdio alongside web |
--port N |
Web server port (0 = let the OS pick a free port) (default: 3000) |
--web-port-file PATH |
Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable) |
--web-unix-socket PATH |
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) |
#ui
Open the interactive UI (Web / DAP). Default when no command is given.
Usage: hins ui [--dap-stdio | [--web] [--with-dap]] [--port N] [--web-port-file PATH] [--web-unix-socket PATH]
| Option | Description |
|---|---|
--dap-stdio |
DAP-over-stdio frontend only |
--web |
Web frontend |
--with-dap |
Also start DAP-over-stdio alongside web |
--port N |
Web server port (0 = let the OS pick a free port) (default: 3000) |
--web-port-file PATH |
Write the actual bound web port to PATH (useful with --port 0 when stdout is unavailable) |
--web-unix-socket PATH |
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) |
-h, --help |
Show this help text |
#fragmentation
Block / MBlock fragmentation report. Implicitly pauses.
Usage: hins fragmentation [--include-pinned]
| Option | Description |
|---|---|
--include-pinned |
Include pinned blocks in the breakdown |
-h, --help |
Show this help text |
#consistency
Heap consistency check. Exits non-zero on violations. Implicitly pauses.
Usage: hins consistency
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#closure
Inspect a single closure by id. Implicitly pauses.
Usage: hins closure ID
| Option | Description |
|---|---|
ID |
Closure id (hex address) |
-h, --help |
Show this help text |
#mvars
MVar inventory (paused).
Usage: hins mvars
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#tvars
TVar inventory (paused).
Usage: hins tvars
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#blackholes
Blackhole inventory (paused).
Usage: hins blackholes
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#weaks
Weak reference inventory (paused).
Usage: hins weaks
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#cc-stacks
Cost-centre stack census (target compiled with -prof).
Usage: hins cc-stacks
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#pinned
Pinned-block inventory.
Usage: hins pinned
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#blocks
MBlock / block allocation map.
Usage: hins blocks
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#ticky
Dump ticky-ticky counters (target compiled with -ticky).
Usage: hins ticky
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#heql
Run HEQL (the Heap Exploration Query Language) over the paused heap. Implicitly pauses.
Usage: hins heql [--source TEXT] [--file PATH] [--tag TAG] [--print] [--ast] [--stdlib] [--explain] [--arg NAME=EXPR] [--expand-depth N]
| Option | Description |
|---|---|
--source TEXT |
Inline query catalog (DSL text). Overrides --file and the built-in defaults. |
--file PATH |
Read the query catalog from PATH instead of the built-in default catalog. |
--tag TAG |
Run only the query whose tag matches TAG. |
--print |
Parse the catalog and report each query without attaching (surfaces parse errors). |
--ast |
heql: parse the catalog and print each declaration's parse tree; no typechecking, no debuggee. |
--stdlib |
heql: print the standard library reference (names, types, grades, descriptions); no debuggee. |
--explain |
heql: print each query's intermediate representations (HEQL Core, FLAX Plan, FLAX bytecode); no debuggee. |
--arg NAME=EXPR |
heql: override a view parameter (repeatable). EXPR is HEQL expression text, checked against the parameter's type. |
--expand-depth N |
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. |
-h, --help |
Show this help text |
#threads
Print thread states. Combine with --every for live monitoring.
Usage: hins threads
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#eventlog
Stream eventlog messages. Filter by event kind.
Usage: hins eventlog [--type LIST] [--exclude LIST] [--type-regex RE] [--list-types]
| Option | Description |
|---|---|
--type LIST |
Comma-separated event-kind names to include (e.g. GC,HeapAllocated) |
--exclude LIST |
Comma-separated event-kind names to exclude |
--type-regex RE |
Power-user escape hatch: regex over event-kind names |
--list-types |
Print the event kinds the target supports and exit |
-h, --help |
Show this help text |
#metrics
Stream live time-series metrics.
Usage: hins metrics [--series NAME]
| Option | Description |
|---|---|
--series NAME |
Restrict to the given metric series; may be repeated |
-h, --help |
Show this help text |
#sample
Sampling subcommands.
Usage: hins sample COMMAND
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#sample stacks
Run the STG stack sampler and emit raw samples.
Usage: hins sample stacks [--period US] [--budget N] [--no-resolve | --resolve]
| Option | Description |
|---|---|
--period US |
Sampler period in microseconds |
--budget N |
Max samples per tick |
--no-resolve |
Keep frame names as raw hex info-table pointers |
--resolve |
Resolve info-table pointers to Module.Label names (default) |
-h, --help |
Show this help text |
#sample native
Run the signal-driven native C-stack sampler and emit raw PC samples.
Usage: hins sample native [--period US] [--budget N] [--backend auto|signal|external] [--off-cpu] [--min-block US]
| Option | Description |
|---|---|
--period US |
Sampler period in microseconds |
--budget N |
Max OS threads signalled per tick |
| `--backend auto | signal |
--off-cpu |
eBPF off-CPU profiling: sample where threads block and for how long (Linux, needs the eBPF engine) |
--min-block US |
off-CPU: ignore blocks shorter than US microseconds (default 1000) |
-h, --help |
Show this help text |
#bp
Add a software code breakpoint on a function and stream hits (Linux/x86-64, trace mode).
Usage: hins bp FUNCTION
| Option | Description |
|---|---|
FUNCTION |
Function name to break on (matched against the IPE map) |
-h, --help |
Show this help text |
#exceptions
Capture raised exceptions and aggregate them by type x raise site (live stream).
Usage: hins exceptions [--sync] [--async] [--message] [--deep] [--top N]
| Option | Description |
|---|---|
--sync |
Capture synchronous exceptions (throw / stg_raisezh) |
--async |
Capture asynchronous exceptions (throwTo / killThread) |
--message |
Extract a bounded UTF-8 exception message |
--deep |
Force exceptions via the RTS hook to recover the real type and message |
--top N |
Show only the top N groups by count |
-h, --help |
Show this help text |
#stm-stats
Capture STM transaction outcomes (commit vs conflict re-run) and break down by thread / era / site (live stream, opt-in).
Usage: hins stm-stats [--top N]
| Option | Description |
|---|---|
--top N |
Show only the top N conflict sites by count |
-h, --help |
Show this help text |
#record
Capture to disk: snapshot / eventlog / samples / metrics / all.
Usage: hins record COMMAND
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#record snapshot
Pause, write a heap snapshot, resume.
Usage: hins record snapshot OUT [--format FMT]
| Option | Description |
|---|---|
--format FMT |
Snapshot format: hins (default, re-open with --snapshot) or ghc-debug (ghc-debug-brick/-client) |
-h, --help |
Show this help text |
#record eventlog
Drain the eventlog ring buffer to a .eventlog file.
Usage: hins record eventlog OUT [--buffer-mb N] [--type LIST]
| Option | Description |
|---|---|
--buffer-mb N |
Ring buffer size |
--type LIST |
Restrict to given event kinds |
-h, --help |
Show this help text |
#record samples
Run the stack sampler and write samples (default format: speedscope).
Usage: hins record samples OUT [--period US]
| Option | Description |
|---|---|
--period US |
Sampler period in microseconds |
-h, --help |
Show this help text |
#record metrics
Write a metrics file (default format: csv).
Usage: hins record metrics OUT [--series NAME]
| Option | Description |
|---|---|
--series NAME |
Restrict to the given metric series |
-h, --help |
Show this help text |
#record stack-growth
Arm the threadStackOverflow trap and summarise growth snapshots.
Usage: hins record stack-growth
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#record all
Write snapshot + eventlog + samples + metrics into DIR.
Usage: hins record all DIR
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#report
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.
Usage: hins report [--stack-traces] [--exceptions] [--top N]
| Option | Description |
|---|---|
--stack-traces |
Include the backtrace captured at each stack-growth event |
--exceptions |
Include exception messages and backtraces (otherwise just counts) |
--top N |
Cap the per-thread tables and leaderboards to the top N entries |
-h, --help |
Show this help text |
#list
List live inspectable processes (descriptors published by the connector).
Usage: hins list [--available]
| Option | Description |
|---|---|
--available |
Only show non-locked processes; in text format, output tab-separated <pid><TAB><prog> lines with no header for easy scripting (awk/cut/xargs). |
-h, --help |
Show this help text |
#batch
Run multiple commands against a single pause cycle.
Usage: hins batch [--script PATH]
| Option | Description |
|---|---|
--script PATH |
Read script from PATH (default: stdin) |
-h, --help |
Show this help text |
#list-formats
List available output formats for CMD, or every command if omitted.
Usage: hins list-formats [CMD]
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#help-examples
Print worked examples for the common CLI workflows.
Usage: hins help-examples
| Option | Description |
|---|---|
-h, --help |
Show this help text |
#Environment variables
Variables the inspector and its bundled connector read, discovered by scanning the source. Follow a read site for the surrounding context.
| Variable | Read at |
|---|---|
APPDATA |
auto_init.c:180 |
FLAX_BC |
bc.c:16 |
FLAX_BENCH_OUT |
Main.hs:95, Main.hs:135 |
FLAX_BENCH_PLAN |
Main.hs:83 |
FLAX_BENCH_SRC |
Main.hs:76, Main.hs:108 |
FLAX_BMAP |
heap.c:175 |
FLAX_COLLPAR |
morsel.c:101 |
FLAX_COLPAR |
nodes.c:444 |
FLAX_DIAG |
driver.c:1039 |
FLAX_DOMFAST |
ops.c:936 |
FLAX_DRIVER |
driver.c:113 |
FLAX_MAX_ALLOC_MB |
flax_main.c:44 |
FLAX_MSBFS |
graph.c:756 |
FLAX_MSB_MB |
graph.c:762 |
FLAX_NOMEMGATE |
hgroup.c:374 |
FLAX_OHEXTEND |
ffi.c:705 |
FLAX_OHPAR |
objhash.c:41 |
FLAX_PAR_MIN |
nodes.c:351 |
FLAX_SHAPE_CHECK |
link.c:547 |
FLAX_SKIP |
vec.c:94 |
FLAX_SYMIDX |
heap.c:572 |
FLAX_TRIM |
Main.hs:136 |
FLAX_VEC |
vec.c:50 |
FLAX_WALKPAR |
nodes.c:1546 |
FLAX_WALL_MS |
flax_main.c:43 |
FLAX_WORKERS |
morsel.c:386, ops.c:26, graph.c:116, nodes.c:340, objhash.c:28 |
FLAX_WORLDPAR |
ops.c:41 |
FLAX_WORLDS_PUSH |
pushdown.c:65 |
HASKELL_INSPECTOR_BPF_HELPER |
ebpf_sampler.c:250 |
HASKELL_INSPECTOR_CAPTURE |
capture.c:30 |
HASKELL_INSPECTOR_CONNECTOR_LIB |
EmbeddedConnector.hs:87, Spawn.hs:98 |
HASKELL_INSPECTOR_CONNECTOR_RESOLVE |
Symbolize.hs:123 |
HASKELL_INSPECTOR_DISABLE |
auto_init.c:669 |
HASKELL_INSPECTOR_EBPF_OFFCPU |
external_sampler.c:1459 |
HASKELL_INSPECTOR_EBPF_OFFCPU_MIN_BLOCK_US |
external_sampler.c:1461 |
HASKELL_INSPECTOR_FORCE |
auto_init.c:672 |
HASKELL_INSPECTOR_HEARTBEAT_MS |
commands.c:274 |
HASKELL_INSPECTOR_LATENCY_ACTIVE_PROBE |
latency_monitor.c:887 |
HASKELL_INSPECTOR_LATENCY_ENABLE |
latency_monitor.c:883 |
HASKELL_INSPECTOR_LATENCY_HEARTBEAT_NS |
latency_monitor.c:877 |
HASKELL_INSPECTOR_LATENCY_PERIOD_NS |
latency_monitor.c:868 |
HASKELL_INSPECTOR_LATENCY_THRESHOLD_NS |
latency_monitor.c:859 |
HASKELL_INSPECTOR_LATENCY_TRACE |
latency_monitor.c:891 |
HASKELL_INSPECTOR_NATIVE_BACKEND |
ebpf_sampler.c:525 |
HASKELL_INSPECTOR_NATIVE_SAMPLE_SIGNAL_OFFSET |
signal_sampler.c:1530 |
HASKELL_INSPECTOR_PAUSE_WATCHDOG_MS |
listen.c:55 |
HASKELL_INSPECTOR_SAMPLER_TRACE |
sampler.c:2000 |
HASKELL_INSPECTOR_SOCKET |
auto_init.c:698 |
HASKELL_INSPECTOR_START_PAUSED |
auto_init.c:638 |
HASKELL_INSPECTOR_TRACE_CMDS |
commands.c:2278, eventlog.c:1977, listen.c:30 |
HASKELL_INSPECTOR_WRITE_TIMEOUT_MS |
hi_os_transport.c:161 |
HI_DEREF_STATS |
HeapAlloced.hs:154 |
HI_FLAX_TIMING |
FlaxDump.hs:348 |
HI_HEAP_TIMING |
NodeTable.hs:976, Debuggee.hs:480 |
HI_HEAP_TIMING_LIVE |
Debuggee.hs:503 |
HI_HEQL_BENCH |
BenchMetrics.hs:46 |
HI_IPE_IDLE_TICKS |
Base.hs:2186 |
HI_IPE_TIMING |
Base.hs:2194 |
HI_NODETABLE_MC |
Debuggee.hs:648 |
HOME |
auto_init.c:188 |
TMPDIR |
auto_init.c:311 |
USERPROFILE |
auto_init.c:182 |
XDG_DATA_HOME |
auto_init.c:186 |