MercuryToolbox/skills/mercury-toolbox/references/command-catalog.md

Mercury Toolbox Command Catalog

Use this catalog when choosing among nearby Mercury commands. Keep output compact, prefer --json for machine handoff, prefer --toon for model-facing structured output, and use toon for external JSON producers.

Code and Context

fileprobe

Use: Classify files as text, binary, generated, minified, test, vendor, and more, including encoding, BOM, and newline diagnostics. Better than: blindly opening files when you need a fast read-worthiness, encoding, or newline check first. Usage: fileprobe [OPTIONS] [PATH...] Example: fileprobe .\dist\bundle.min.js --json | ConvertFrom-Json Guided answer: Answer whether a path is text, binary, generated, minified, vendor, or worth opening. Trust basis: Trust bounded sniffing, encoding, newline, and classification diagnostics. Next actions: Use outline or chunkcat for readable text. | Use binmeta or stringscan for binary files. TOON example: fileprobe .\dist\bundle.min.js --toon

outline

Use: List top-level code or config structure. Better than: scrolling whole files when you only need the structure. Usage: outline [OPTIONS] <PATH...> Example: outline <PATH> Guided answer: Answer top-level structure of source or config files. Trust basis: Trust parser-supported outlines and explicit unsupported-file diagnostics. Next actions: Use defsnip for exact definitions. | Use refs or codeshape for broader symbol maps. TOON example: outline --toon <PATH>

codeshape

Use: Map a codebase into files plus AST-backed declarations and signatures from the shared codeindex engine. Better than: plain tree output when you need internal declarations and signatures without dumping full source files. Usage: codeshape [OPTIONS] [PATH...] Example: codeshape --max-depth 1 --limit-per-file 8 . --json | ConvertFrom-Json Guided answer: Answer repository file/declaration shape with AST-backed summaries. Trust basis: Trust codeindex parser results and skipped-file diagnostics. Next actions: Use defsnip to extract definitions. | Use refs to find use sites. TOON example: codeshape --max-depth 1 --limit-per-file 8 . --toon

refs

Use: Find exact symbol references or caller definitions through the shared codeindex engine with text fallback. Better than: falling back to raw rg when you need exact use-sites or caller summaries for a known symbol. Usage: refs [OPTIONS] <SYMBOL> [PATH...] | refs [OPTIONS] --at <PATH:LINE[:COL]> [PATH...] Example: refs helper <PATH> Guided answer: Answer symbol references or callers across source files. Trust basis: Trust codeindex hits and caller grouping under the selected roots. Next actions: Use hitsnip to expand hit context. | Use defsnip for definition bodies. TOON example: refs --toon helper <PATH>

snip

Use: Extract precise snippets from files or stdin. Better than: dumping whole files when you only need exact lines, matches, or symbols. Usage: snip [OPTIONS] [PATH...] Example: snip --lines 16:27 <PATH> Guided answer: Answer exact bounded source/text snippets by line, match, or symbol. Trust basis: Trust line numbers and bounded extraction; binary or missing paths are rejected. Next actions: Use hitsnip after rg for multiple hits. | Use ctxpack to bundle snippets. TOON example: snip --toon --lines 16:27 <PATH>

defsnip

Use: Extract full AST-backed definitions by exact symbol name through the shared codeindex engine. Better than: line-number snippets when you need the full function, class, or method body even after nearby edits move the lines. Usage: defsnip [OPTIONS] <SYMBOL> [PATH...] Example: defsnip build_report . --json | ConvertFrom-Json Guided answer: Answer full AST-backed definition blocks for symbols. Trust basis: Trust codeindex definitions and language support; no match means broaden symbol/root. Next actions: Use refs for callers/use sites. | Use ctxpack to package the definition with nearby context. TOON example: defsnip build_report . --toon

ctxpack

Use: Pack files, snippets, hits, diagnostics, or definition JSON into compact context blocks. Better than: hand-assembling ad-hoc prompt context from files, hits, diagnostics, and definitions. Usage: ctxpack [OPTIONS] [INPUT...] Example: ctxpack <PATH> Guided answer: Answer compact prompt-ready context from files, snippets, hits, and diagnostics. Trust basis: Trust included path and byte/line caps; review omitted/truncated sections for scope. Next actions: Use fileprobe/codeshape before packing broad roots. | Use diagpick or hitsnip to feed focused evidence. TOON example: ctxpack --toon <PATH>

chunkcat

Use: Read large text files in bounded chunks, including quick tail-style log windows. Better than: huge file dumps when you need deterministic windows. Usage: chunkcat [OPTIONS] [PATH...] Example: chunkcat .\BepInEx\LogOutput.log --max-lines 20 --tail Guided answer: Answer a bounded chunk or inventory of a large text file. Trust basis: Trust chunk indices, line ranges, and binary detection. Next actions: Use snip when you know the exact line range. | Use hitsnip to expand search hits into chunks. TOON example: chunkcat --toon .\BepInEx\LogOutput.log --max-lines 20 --tail

hitsnip

Use: Turn search hits into compact snippets or promote them to enclosing definitions. Better than: raw rg hit lists when you need merged readable context or the enclosing definition instead of a tiny window. Usage: hitsnip [OPTIONS] [HIT...] Example: rg -nH "helper" <PATH> | hitsnip --def Guided answer: Answer merged snippets around rg-style search hits. Trust basis: Trust hit parsing and merge ranges; malformed hit lines are reported. Next actions: Use rg -nH to feed hits. | Use defsnip when the hit is inside a known symbol. TOON example: rg -nH "helper" <PATH> | hitsnip --toon --def

diagpick

Use: Extract compiler or runtime diagnostics from noisy logs, with optional snippets and enclosing definitions. Better than: reading full logs when you need the actionable errors first and want direct source or definition context. Usage: diagpick [OPTIONS] [PATH...] Example: diagpick <PATH> --def Guided answer: Answer actionable diagnostics extracted from compiler/build/log text. Trust basis: Trust recognized diagnostic formats and preserved source context. Next actions: Use snip on referenced files/lines. | Use runprobe to capture the failing command reproducibly. TOON example: diagpick --toon <PATH> --def

gitshape

Use: Summarize Git status or diff shape into concise AI-friendly file, line, and touched-symbol reports. Better than: reading raw git status and diff noise when you first need compact status counters or changed-file summaries. Usage: gitshape [OPTIONS] [PATH] | gitshape [OPTIONS] status [PATH] | gitshape [OPTIONS] diff [REVISION_A] [REVISION_B] Example: gitshape status --repo C:\src\repo --json | ConvertFrom-Json Guided answer: Answer git status, branch, diff, and repository change shape. Trust basis: Trust git command output and explicit revision/path filters. Next actions: Use reposhape to connect git changes to ecosystems. | Use ctxpack or hitsnip for changed-file handoff. TOON example: gitshape status --repo C:\src\repo --toon

reposhape

Use: Detect repository ecosystems, manifests, command entrypoints, and CI hints in one pass. Better than: manually browsing an unfamiliar repo when you first need the ecosystems, manifests, commands, and CI entrypoints. Usage: reposhape [OPTIONS] [PATH] Example: reposhape . --json | ConvertFrom-Json Guided answer: Answer repository ecosystems, manifests, entrypoints, and project layout. Trust basis: Trust manifest detection under depth/hidden filters and parse diagnostics. Next actions: Use codeshape for source declarations. | Use dotnetshape/sqlshape/gitshape for ecosystem-specific detail. TOON example: reposhape . --toon

dotnetshape

Use: Inspect .csproj, Directory.Build.props/targets, Directory.Packages.props, project references, package versions, and .NET-specific project graph diagnostics. Better than: opening a .NET repo one file at a time when you first need project graph shape, shared MSBuild inheritance, package references, and build-shape warnings. Usage: dotnetshape [OPTIONS] [PATH] Example: dotnetshape . --json | ConvertFrom-Json Guided answer: Answer .NET project graph, inherited MSBuild properties, package references, and diagnostics. Trust basis: Trust static XML parsing without invoking MSBuild; generated/effective values are labeled. Next actions: Use asmref diagnose on built assemblies. | Use config to inspect Directory.Build or props files directly. TOON example: dotnetshape . --toon

Data and Config

cjson

Use: Compact JSON or JSONL before piping, diffing, or model input. Better than: pretty multi-line JSON when you need compact stable output and optional key sorting. Usage: cjson [OPTIONS] [PATH] Example: cjson <PATH> Guided answer: Answer whether JSON/JSONL can be compacted cleanly and deterministically. Trust basis: Trust the JSON parser result and document count; invalid JSON is reported before compaction. Next actions: Run jsonshape on the compacted payload when you need schema shape. | Pipe to jq or toon for projection/model handoff. TOON example: cjson --toon <PATH>

ison

Use: Convert between JSON and ISON records for compact structured handoff. Better than: verbose JSON when a deterministic compact ISON representation is easier to scan or diff. Usage: ison [OPTIONS] [PATH] Example: ison <PATH> Guided answer: Answer whether JSON can round-trip through compact ISON for handoff. Trust basis: Trust successful parser/encoder output; use JSON mode when a tool must consume it next. Next actions: Use isonl for line-oriented streams. | Use toon when the next consumer is an AI model. TOON example: ison --toon <PATH>

isonl

Use: Convert between JSONL and ISONL line records. Better than: manual JSONL splitting when line-oriented ISON records are better for streaming or model input. Usage: isonl [OPTIONS] [PATH] Example: isonl --from jsonl --to isonl <PATH> Guided answer: Answer whether JSONL/ISONL records can be converted as a stream. Trust basis: Trust per-line parser diagnostics and document counts; malformed lines stop the conversion. Next actions: Pipe into jsonlgrep for filtering. | Use cjson or toon for downstream compact handoff. TOON example: isonl --toon --from jsonl --to isonl <PATH>

zon

Use: Convert JSON or JSONL to Zero Overhead Notation and back. Better than: hand-written compact table encodings when you need Zero Overhead Notation interop without Node tooling. Usage: zon [OPTIONS] [PATH] Example: zon <PATH> Guided answer: Answer whether JSON/JSONL can convert to or from Zero Overhead Notation. Trust basis: Trust parser diagnostics and wrapper metadata for document count and target format. Next actions: Use jsonshape after decoding to validate shape. | Use toon for model-facing structured summaries. TOON example: zon --toon <PATH>

tonl

Use: Encode, decode, query, validate, index, stream-query, and ETL JSON-backed TONL data. Better than: one-off scripts for compact JSON ETL, validation, query, indexing, or streaming filters. Usage: tonl <COMMAND> [OPTIONS] [PATH] | tonl index <build|query> [OPTIONS] | tonl stream query [OPTIONS] [PATH] Example: tonl query --where active=true <PATH> Guided answer: Answer filtered TONL records, validation status, indexes, or ETL conversion results. Trust basis: Trust explicit validation/query diagnostics; streaming mode reports record-level failures. Next actions: Use jsonlgrep for simple JSONL filtering before TONL conversion. | Use cjson or toon for compact handoff. TOON example: tonl query --toon --where active=true <PATH>

jsonlgrep

Use: Filter JSONL logs, single-line JSON arrays, or structured event streams by field. Better than: ad-hoc jq for simple field filters, projections, counts, and regex matches. Usage: jsonlgrep [OPTIONS] <QUERY> [PATH...] Example: recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json Guided answer: Answer which JSONL records match field, regex, or projection filters. Trust basis: Trust parsed JSON records and explicit malformed-line diagnostics. Next actions: Use jsonshape on matched records to inspect structure. | Use toon or cjson for compact AI handoff. TOON example: recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --toon

jsonshape

Use: Summarize JSON or JSONL into path/type stats, or diff two shape reports. Better than: opening raw payloads when you first need the shape, key paths, or a schema diff. Usage: jsonshape [OPTIONS] [PATH...] | jsonshape [OPTIONS] diff <BEFORE> <AFTER> Example: jsonshape diff before.json after.json --json | ConvertFrom-Json Guided answer: Answer the key paths, types, counts, and shape differences in JSON/JSONL. Trust basis: Trust reported path/type counts when parsing succeeds; review diff diagnostics for drift. Next actions: Use jsonlgrep to isolate records before reshaping. | Use cjson to normalize payloads before comparing. TOON example: jsonshape diff before.json after.json --toon

mhash

Use: Compute local file hashes across the OpenHashTab-class matrix, list algorithms, hash with --all or explicit multi-algorithm sets, produce JSONL manifests, verify manifests, or benchmark hash throughput. Better than: PowerShell Get-FileHash loops, GUI hash tabs, ad-hoc checksum scripts, or manual benchmark harnesses when you need OpenHashTab-class algorithm coverage, manifests, verification, JSON/JSONL, and throughput telemetry in one local CLI. Usage: mhash [OPTIONS] [PATH...] | mhash verify [OPTIONS] <MANIFEST> | mhash list-algorithms [--json] | mhash bench [OPTIONS] [PATH...] Example: mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip --json | ConvertFrom-Json Guided answer: Answer file identity, checksum, manifest verification, or hash throughput questions. Trust basis: Trust algorithm labels, manifest verification status, and per-file error rows. Next actions: Use fileprobe first when the file type is unknown. | Use jsonlgrep or jq to filter manifest rows. TOON example: mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip --toon

toon

Use: Convert between JSON and TOON. Better than: verbose JSON when you want a denser structured text form. Usage: toon [OPTIONS] [PATH] Example: '{"ok":true}' | toon Guided answer: Answer compact model-readable TOON from JSON/JSONL or decode TOON back. Trust basis: Trust parser/encoder diagnostics and document wrapper metadata. Next actions: Use native --toon on Mercury producers when available. | Use cjson/jsonshape before converting questionable JSON.

csvshape

Use: Summarize large CSV or TSV files into compact schema/bounded stats, or diff two CSV shapes. Better than: opening huge CSV or TSV files when you first need the columns, rough types, blanks, example values, or a shape diff. Usage: csvshape [OPTIONS] [PATH...] | csvshape [OPTIONS] diff <BEFORE> <AFTER> Example: csvshape diff before.csv after.csv --json | ConvertFrom-Json Guided answer: Answer CSV/TSV delimiter, columns, row counts, and schema differences. Trust basis: Trust parsed rows under the detected or requested delimiter. Next actions: Use jsonshape after converting CSV to JSON externally. | Use config or sqlshape when CSV describes configuration/data imports. TOON example: csvshape diff before.csv after.csv --toon

sqliteshape

Use: Inspect SQLite databases read-only with compact schema/table summaries, or diff two SQLite shapes. Better than: dropping into an interactive SQLite shell when you only need schema, sample rows, light table stats, or a shape diff. Usage: sqliteshape [OPTIONS] [PATH...] | sqliteshape [OPTIONS] diff <BEFORE> <AFTER> Example: 'C:\data\events.db' | sqliteshape --input-format lines --json | ConvertFrom-Json Guided answer: Answer SQLite tables, columns, indexes, triggers, and schema diffs. Trust basis: Trust SQLite catalog queries against the selected database file. Next actions: Use sqlshape for normalized cross-engine reports. | Use jsonshape/csvshape on exported data samples. TOON example: 'C:\data\events.db' | sqliteshape --input-format lines --toon

sqlshape

Use: Inspect PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, or DuckDB schemas read-only with redacted connection sources and normalized cross-engine diffs. Better than: hand-writing per-engine catalog queries or exposing raw connection strings when you need a normalized cross-database schema report or diff. Usage: sqlshape [OPTIONS] --url <CONNECTION> | sqlshape [OPTIONS] diff --before-url <CONNECTION> --after-url <CONNECTION> Example: sqlshape --engine sqlite --url <PATH> --json | ConvertFrom-Json Guided answer: Answer normalized SQL schema across SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, or DuckDB. Trust basis: Trust engine-specific introspection and redacted connection reporting. Next actions: Use sqliteshape for SQLite-specific detail. | Use config to inspect connection/config files safely. TOON example: sqlshape --engine sqlite --url <PATH> --toon

config

Use: Read, inspect, list, set, or delete config values in JSON, YAML, TOML, env, and INI files. Better than: fighting jq or hand-editing config files when you need safe slash-pointer reads or edits across common formats. Usage: config [OPTIONS] [PATH] | config [OPTIONS] <get|inspect|ls|set|delete> <PATH> [POINTER] [VALUE] Example: config get .\package.json /version Guided answer: Answer get/set/delete operations over JSON/YAML/TOML/env/INI config paths. Trust basis: Trust parser-specific diagnostics and structured edit reports. Next actions: Use fileprobe before editing unknown config files. | Use jsonshape after JSON config changes. TOON example: config --toon get .\package.json /version

Logs, Process, and Waiting

logshape

Use: Group recurring log lines into templates. Better than: reading repetitive logs line by line when you need the dominant patterns. Usage: logshape [OPTIONS] [PATH...] Example: logshape <PATH> Guided answer: Answer repeated log templates, incidents, and message clusters. Trust basis: Trust grouping counts and examples; rare lines may stay as individual templates. Next actions: Use diagpick for actionable errors. | Use jsonlgrep when logs are structured JSONL. TOON example: logshape --toon <PATH>

envdiff

Use: Snapshot, diff, or run commands while reporting environment-variable changes. Better than: hand-comparing environment variables before and after a script, especially around PATH pollution and batch wrappers. Usage: envdiff [OPTIONS] run --shell cmd|pwsh|raw -- <COMMAND...> Example: envdiff run --shell cmd -- .\scripts\set-env.cmd Guided answer: Answer environment variable changes before/after a command or between snapshots. Trust basis: Trust captured before/after maps and PATH segment deltas. Next actions: Use pathshadow after PATH changes. | Use sysshape for broader shell/tool inventory. TOON example: envdiff --toon run --shell cmd -- .\scripts\set-env.cmd

proctree

Use: Inspect whole-system, rooted, matched, or command-run Windows process trees in AI-friendly form; use --match to filter by image name or command line. Better than: flat process lists when you need parent-child context, short command lines, and lingering orphan hints. Usage: proctree [OPTIONS] system|root <PID>|run -- <COMMAND...> Example: proctree system --match 'pwsh|Mercury' --include-cmdline Guided answer: Answer process trees, rooted processes, and command ancestry. Trust basis: Trust OS process snapshots at capture time; short-lived processes may disappear. Next actions: Use portunlock for port owners. | Use runprobe to capture command execution shape. TOON example: proctree --toon system --match 'pwsh|Mercury' --include-cmdline

sysshape

Use: Capture a compact local system and tool inventory for AI-friendly triage, including shell hints, path-like duplication, and probe status. Better than: asking users ad-hoc setup questions or checking versions one tool at a time when you need a compact local machine inventory first. Usage: sysshape [OPTIONS] Example: sysshape --json --env safe --group shell | ConvertFrom-Json Guided answer: Answer machine, shell, environment, and tool inventory shape. Trust basis: Trust detected command paths/versions and grouped environment metadata. Next actions: Use pathshadow for a specific executable winner. | Use envdiff around commands that mutate the environment. TOON example: sysshape --toon --env safe --group shell

runprobe

Use: Run one command and capture exit code, duration, timeout status, and bounded output tails. Better than: reading fragile shell text when what you really need is the stable result object for one command run. Usage: runprobe [OPTIONS] -- <COMMAND...> Example: runprobe --json --shell pwsh -- '& { Write-Error boom; exit 9 }' | ConvertFrom-Json Guided answer: Answer command exit code, duration, stdout/stderr tails, and timeout behavior. Trust basis: Trust captured process result and bounded output tails. Next actions: Use diagpick on captured stderr/stdout. | Use envdiff run when environment mutation matters. TOON example: runprobe --toon --shell pwsh -- '& { Write-Error boom; exit 9 }'

await

Use: Wait for a path, TCP target, HTTP endpoint, or command condition with bounded polling. Better than: writing ad-hoc polling loops for files, ports, HTTP endpoints, or repeat-until-success commands. Usage: await [OPTIONS] path <PATH> [--state exists|missing] | await [OPTIONS] port <TARGET> | await [OPTIONS] http <URL> [--status <CODE>] | await [OPTIONS] run [--shell <MODE>] [--cwd <PATH>] [--exit-code <CODE>] [--tail-bytes <COUNT>] -- <COMMAND...> Example: await path .\target\ready.flag Guided answer: Answer whether a path, port, HTTP endpoint, or command became ready before timeout. Trust basis: Trust polling attempts, final state, and timeout status. Next actions: Use portping for one-shot endpoint detail. | Use runprobe for command readiness probes. TOON example: await --toon path .\target\ready.flag

argv

Use: Quote argv for pwsh or cmd, or inspect what a shell actually passed to a native process. Better than: guessing how PowerShell or cmd really passed arguments to a native process. Usage: argv quote --shell <pwsh|cmd|raw> [VALUE...] | argv inspect [--json] --shell <pwsh|cmd|raw> [VALUE...] Example: '["tool.exe","two words"]' | argv quote --shell cmd Guided answer: Answer how arguments should be quoted or how a shell actually passes them. Trust basis: Trust helper round-trips for the selected shell/platform. Next actions: Use runprobe to execute the quoted command. | Use msudo status before privileged shell wrapping. TOON example: '["tool.exe","two words"]' | argv --toon quote --shell cmd

recent

Use: List recently changed files or directories. Better than: manual directory scans when you just need the freshest files and .gitignore awareness. Usage: recent [OPTIONS] Example: recent --root . --since 2h --ext rs --name '^(lib|main)$' Guided answer: Answer which files or directories changed recently. Trust basis: Trust timestamp filters and gitignore-aware discovery within the selected root. Next actions: Pipe paths into fileprobe or outline. | Use hitsnip or ctxpack after narrowing files. TOON example: recent --toon --root . --since 2h --ext rs --name '^(lib|main)$'

pathshadow

Use: Show which executable wins and which ones are shadowed. Better than: guessing PATH order when the wrong executable is being picked. Usage: pathshadow [OPTIONS] [COMMAND...] Example: pathshadow python npm --shell powershell --summary --json | ConvertFrom-Json Guided answer: Answer which executable wins on PATH and which candidates are shadowed. Trust basis: Trust resolved filesystem candidates and shell-aware summary rows. Next actions: Use sysshape --group shell for broader environment context. | Use argv quote when command invocation quoting is suspicious. TOON example: pathshadow python npm --shell powershell --summary --toon

Network and Locks

portping

Use: Probe ports or health endpoints with timings. Better than: jumping between multiple network tools for quick TCP and HTTP reachability checks. Usage: portping [OPTIONS] [TARGET...] Example: 'https://example.com/health' | portping --json | ConvertFrom-Json Guided answer: Answer whether a TCP/HTTP/HTTPS endpoint is reachable and how long it took. Trust basis: Trust direct connection/status timing; failures distinguish DNS, connect, and HTTP states. Next actions: Use portunlock when a local port is unexpectedly occupied. | Use await port/http to wait for readiness. TOON example: 'https://example.com/health' | portping --toon

portunlock

Use: Show and free local TCP or UDP port owners on Windows. Better than: guessing which process owns a port or hand-writing netstat and kill loops when a local listener refuses to go away. Usage: portunlock [OPTIONS] who <PORT...> | portunlock [OPTIONS] free <PORT...> Example: portunlock who --json --protocol any 3000 8080 | ConvertFrom-Json Guided answer: Answer which process owns a local TCP/UDP port and optionally free it. Trust basis: Trust OS port snapshots and post-action verification rows. Next actions: Use proctree on the owning PID before freeing. | Use portping after freeing or restarting a listener. TOON example: portunlock who --toon --protocol any 3000 8080

msudo

Use: Top-level high-risk command: inspect Windows elevation relay status, token state, active session state, and host availability before any privileged launch. Better than: guessing whether Windows elevation relay support is available, or hand-writing Start-Process -Verb RunAs wrappers when you first need the current privilege status. Usage: msudo [OPTIONS] [--] <COMMAND...> | msudo run [OPTIONS] [--] <COMMAND...> | msudo status [OPTIONS] | msudo [OPTIONS] --shell <PRESET> Example: msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated Guided answer: Answer Windows elevation, token, relay, and launch-shape questions. Trust basis: Trust status discovery before launch; treat run actions as high risk and explicit. Next actions: Start with msudo status --json. | Use argv quote before privileged shell wrapping. TOON example: msudo status --toon

unlock

Use: Identify file lockers and perform unlock-aware file actions on Windows. Better than: ad-hoc PowerShell probing when a file is busy, locked, or refuses delete, move, rename, or copy. Usage: unlock [OPTIONS] who <PATH...> | unlock [OPTIONS] free <PATH...> | unlock [OPTIONS] move <PATH> <DEST> | unlock [OPTIONS] rename <PATH> <NEW_NAME> | unlock [OPTIONS] delete <PATH...> | unlock [OPTIONS] copy <PATH> <DEST> Example: unlock who .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results Guided answer: Answer which processes lock files and perform unlock-aware copy/move/delete actions. Trust basis: Trust restart-manager/handle-scan evidence and post-action filesystem checks. Next actions: Use proctree on blocker PIDs. | Use recent after cleanup to confirm generated artifacts. TOON example: unlock who .\target\debug\jsonlgrep.exe --toon

Managed, Unity, and Binary Inspection

asmtype

Use: List managed assembly types and filter them by name, namespace, base type, interface, or matching members, with optional user-code-only screening. Better than: manual reflection or ad-hoc PowerShell when you first need the type map from a managed assembly. Usage: asmtype [OPTIONS] [ASSEMBLY...] Example: asmtype <PATH> --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --json | ConvertFrom-Json Guided answer: Answer which managed types match name, inheritance, interface, or member intent. Trust basis: Trust metadata enumeration from the target assembly; broaden filters when no matches return. Next actions: Pipe JSONL into asmmember. | Use asmflow find/xref when behavior matters. TOON example: asmtype <PATH> --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --toon

asmmember

Use: Inspect managed type members with binding filters and compact signatures, including JSONL handoff from asmtype and user-code-only filtering. Better than: long reflection scripts when you need methods, fields, and properties from a known managed type. Usage: asmmember [OPTIONS] <TYPE...> Example: asmtype <PATH> --intent unity-spacecraft-workflow --json | asmmember --assembly <PATH> --input-format jsonl --intent unity-spacecraft-workflow --pick type_name,name,visibility,signature --json | ConvertFrom-Json Guided answer: Answer which methods, fields, and properties exist on selected managed types. Trust basis: Trust assembly metadata and binding filters; use non-public filters intentionally. Next actions: Use asmflow body for IL details. | Use asmapi diff when comparing versions. TOON example: asmtype <PATH> --intent unity-spacecraft-workflow --json | asmmember --assembly <PATH> --input-format jsonl --intent unity-spacecraft-workflow --pick type_name,name,visibility,signature --toon

asmref

Use: Inspect managed assembly references, check whether they resolve from local directories, or run diagnose to report closure risks such as missing references, same-name version/token conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad hazards. Better than: guessing missing managed dependencies when you need a fast reference, resolution, or Unity/Rocket plugin closure diagnosis pass. Usage: asmref [OPTIONS] [ASSEMBLY...] | asmref diagnose [OPTIONS] [ASSEMBLY...] Example: asmref diagnose <PATH> --resolve-dir <PATH> --format toon Guided answer: Answer managed references, resolution status, and dependency closure risks. Trust basis: Trust resolved candidates and risk tiers; explicit resolve dirs define the runtime universe. Next actions: Run asmref diagnose for closure risks. | Use asmapi diff on risky version changes. TOON example: asmref --toon diagnose <PATH> --resolve-dir <PATH> --format toon

asmapi

Use: Compare two managed assemblies for added or removed public types, removed methods, signature changes, and MissingMethodException risks, with optional internal/all visibility. Better than: manual reflection diffs or brittle spreadsheet comparisons when you need to know what managed API changed between two DLL versions. Usage: asmapi [OPTIONS] <SUBCOMMAND> [ARGS...] Example: asmapi diff .\old\0Harmony.dll .\new\0Harmony.dll --json | ConvertFrom-Json Guided answer: Answer public API differences between managed assemblies. Trust basis: Trust metadata comparison under the chosen visibility scope. Next actions: Use asmref diagnose to connect API drift to dependency closure. | Use asmmember on removed or changed types. TOON example: asmapi diff .\old\0Harmony.dll .\new\0Harmony.dll --toon

asmflow

Use: Inspect managed method bodies, IL summaries, and cross-references for Unity and general .NET reverse-engineering flows. Better than: ad-hoc IL dump scripts or manual dnSpy browsing when you need callers, callees, field access, or string literals from a managed method quickly. Usage: asmflow [OPTIONS] <SUBCOMMAND> [ARGS...] Example: asmflow xref --assembly <PATH> 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --json | ConvertFrom-Json Guided answer: Answer managed IL bodies, callers, callees, field access, and string references. Trust basis: Trust method-body metadata when the target method resolves; unknown bodies are reported. Next actions: Use asmtype/asmmember to find exact targets. | Use ctxpack to hand off IL evidence. TOON example: asmflow xref --assembly <PATH> 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --toon

llvmobjdump

Use: Inspect object sections, symbol labels, and disassembly through LLVM backend discovery. Better than: raw llvm-objdump text when you need compact section, symbol, and disassembly shape for COFF/PE or object files. Usage: llvmobjdump [OPTIONS] [PATH...] Example: llvmobjdump .\target\release-fast\binmeta.exe --json | ConvertFrom-Json Guided answer: Answer object sections, symbols, and disassembly shape through LLVM. Trust basis: Trust LLVM backend output plus parser warnings/raw blocks for unsupported regions. Next actions: Use llvmreadobj for headers/imports/debug hints. | Use pecalls or pesig for PE-focused call/function triage. TOON example: llvmobjdump .\target\release-fast\binmeta.exe --toon

llvmreadobj

Use: Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM backend discovery. Better than: heavy binary viewers or raw llvm-readobj output when you need a bounded COFF/PE header, import/export, and debug/PDB summary. Usage: llvmreadobj [OPTIONS] [PATH...] Example: llvmreadobj .\target\release-fast\binmeta.exe --json | ConvertFrom-Json Guided answer: Answer COFF/PE headers, sections, imports, exports, and debug hints through LLVM. Trust basis: Trust LLVM backend exit status and parsed blocks; raw blocks preserve unparsed details. Next actions: Use peimports/peexports for PE-focused grouping. | Use llvmobjdump when code layout or disassembly is needed. TOON example: llvmreadobj .\target\release-fast\binmeta.exe --toon

llvmnm

Use: List and classify object symbols through LLVM nm output. Better than: raw symbol-table dumps when you need stable symbol rows with kind, address, size, object/archive prefix, and source-line hints. Usage: llvmnm [OPTIONS] [PATH...] Example: llvmnm .\target\release-fast\binmeta.exe --defined-only --json | ConvertFrom-Json Guided answer: Answer defined/undefined symbols with stable LLVM nm rows. Trust basis: Trust POSIX-format symbol parsing and backend stderr tails. Next actions: Use llvmobjdump for disassembly around symbols. | Use llvmreadobj for object headers and debug hints. TOON example: llvmnm .\target\release-fast\binmeta.exe --defined-only --toon

peexports

Use: Inspect export surfaces, spot forwarded symbols, filter by name or ordinal, and use report_quality/next_actions to decide the next PE pass. Better than: manual PE export-table browsing when you want names, ordinals, RVA/VA, forwarders, and guided follow-up commands without opening a heavy PE debugger. Usage: peexports [OPTIONS] [PATH...] Example: peexports C:\Windows\System32\kernel32.dll --forwarders-only --json | ConvertFrom-Json Guided answer: Answer PE export names, ordinals, RVAs/VAs, forwarders, and entrypoint hints. Trust basis: Trust PE export table parsing plus report_quality evidence and limitations. Next actions: Use peimports to inspect dependencies. | Use llvmreadobj --exports to cross-check LLVM output. TOON example: peexports C:\Windows\System32\kernel32.dll --forwarders-only --toon

peimports

Use: Inspect imports by library, name, or category, quickly separate filesystem, registry, device I/O, NT, and network APIs, then follow emitted next_actions. Better than: ad-hoc import-table triage when you need API families grouped into human-friendly categories with immediate callsite and role follow-ups. Usage: peimports [OPTIONS] [PATH...] Example: peimports .\target\release-fast\portping.exe --category device_io --json | ConvertFrom-Json Guided answer: Answer imported APIs grouped by library and API category. Trust basis: Trust PE import table parsing plus report_quality evidence and limitations. Next actions: Use pecalls on interesting categories. | Use drvshape for driver-like/native profiles. TOON example: peimports .\target\release-fast\portping.exe --category device_io --toon

pecalls

Use: Extract callsites for one or more imported APIs or API categories from LLVM objdump text and inspect report_quality.limitations before treating it as exhaustive. Better than: guessing import callsites from raw disassembly when you want direct IAT matches plus trust metadata around best-effort disassembly parsing. Usage: pecalls [OPTIONS] [PATH...] Example: pecalls .\target\release-fast\portping.exe --api WSAStartup --json | ConvertFrom-Json Guided answer: Answer direct imported API callsites found through LLVM disassembly. Trust basis: Trust direct IAT-target matches; report_quality limitations mark disassembly truncation or gaps. Next actions: Use peimports to choose categories. | Use pesig to place callsites inside functions. TOON example: pecalls .\target\release-fast\portping.exe --api WSAStartup --toon

pesig

Use: Infer function boundaries, source hints, and calling conventions from PE text and metadata, then pivot to imports, callsites, or raw objdump via next_actions. Better than: manual function-boundary and calling-convention inference when you need a quick v1 signal with explicit confidence and next-step context. Usage: pesig [OPTIONS] [PATH...] Example: pesig .\target\release-fast\portping.exe --min-confidence medium --json | ConvertFrom-Json Guided answer: Answer likely PE function boundaries and calling-convention hints. Trust basis: Trust confidence/evidence per function and report_quality for parse completeness. Next actions: Use pecalls to connect functions to APIs. | Use llvmobjdump for raw disassembly context. TOON example: pesig .\target\release-fast\portping.exe --min-confidence medium --toon

pestrrefs

Use: Scan ASCII or UTF-16LE strings, report direct references from LLVM disassembly, and use next_actions to connect strings to imports, callsites, or IOCTL constants. Better than: opening a disassembler and a string viewer separately when you need string hits with direct xrefs and a clear next triage command. Usage: pestrrefs [OPTIONS] [PATH...] Example: pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json Guided answer: Answer strings and direct code references in PE files. Trust basis: Trust direct VA/range xrefs; unresolved counts are not guessed. Next actions: Use peimports to connect strings to APIs. | Use ioctlscan for device-control constants. TOON example: pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --toon

drvshape

Use: Summarize likely WDM, KMDF, NDIS, minifilter, or native driver traits, surface heuristic driver hints, and treat report_quality as the trust boundary. Better than: guessing the driver role from imports and exports when you want a compact Windows driver profile with IOCTL/import/callsite follow-ups already suggested. Usage: drvshape [OPTIONS] [PATH...] Example: drvshape C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json Guided answer: Answer likely Windows driver role, subsystem, imports, exports, and heuristic hints. Trust basis: Trust role hints as heuristics, not vulnerability conclusions; report_quality shows evidence. Next actions: Use ioctlscan to decode CTL_CODE candidates. | Use pecalls --category device_io for dispatch/callsite evidence. TOON example: drvshape C:\Windows\System32\drivers\ndis.sys --toon

ioctlscan

Use: Scan PE bytes and disassembly-adjacent data for likely IOCTL constants, decode their fields, and use report_quality to separate strong hits from heuristic candidates. Better than: searching for Windows IOCTL constants by hand when you want decoded CTL_CODE fields, code locations, and suggested role/callsite/string follow-ups. Usage: ioctlscan [OPTIONS] [PATH...] Example: ioctlscan C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json Guided answer: Answer probable IOCTL constants and decoded CTL_CODE fields. Trust basis: Trust confidence/evidence per candidate; raw byte hits are heuristic until tied to code context. Next actions: Use drvshape to confirm driver role. | Use pestrrefs or pecalls for surrounding evidence. TOON example: ioctlscan C:\Windows\System32\drivers\ndis.sys --toon

unityasset

Use: Inspect Unity serialized assets, bundles, and YAML objects, then trace refs, dump fields, or extract payloads such as TextAsset, MonoScript, AudioClip, and VideoClip. Better than: opening a heavy Unity GUI tool when you first need an index, object refs, field dump, or a quick extraction path for assets, scripts, audio, or video. Usage: unityasset [OPTIONS] index [PATH...] | unityasset [OPTIONS] refs <OBJECT_ID> [PATH...] | unityasset [OPTIONS] dump <OBJECT_ID> [PATH...] | unityasset [OPTIONS] extract <OBJECT_ID> [PATH...] [--output-dir <DIR>] Example: unityasset index 'C:\game\Game_Data' --class MonoBehaviour --script 'MarketOffer|LaunchVehicle' Guided answer: Answer Unity asset indexes, object dumps, references, and extraction writes. Trust basis: Trust parsed serialized files/bundles and explicit unresolved reference rows. Next actions: Use unitydiag for runtime/log symptoms. | Use asmtype/asmflow for managed script assemblies. TOON example: unityasset --toon index 'C:\game\Game_Data' --class MonoBehaviour --script 'MarketOffer|LaunchVehicle'

unityprobe

Use: Install and query a read-only BepInEx bridge for live scenes, objects, and static state in a running Mono Unity game on Windows. Better than: hand-writing BepInEx reflection plugins or one-off named-pipe helpers when you only need a read-only runtime snapshot from a Mono Unity game. Usage: unityprobe [OPTIONS] <SUBCOMMAND> [ARGS...] Example: unityprobe --json scenes | ConvertFrom-Json Guided answer: Answer read-only Unity runtime bridge status, object search, and inspection. Trust basis: Trust explicit bridge install/status and Windows named-pipe reachability. Next actions: Use unitydiag when runtime logs explain bridge issues. | Use unityasset for offline assets. TOON example: unityprobe --toon scenes

unitydiag

Use: Summarize Unity Player.log and BepInEx logs into grouped incidents, normalized messages, and domain-aware failure summaries. Better than: reading raw Player.log and BepInEx logs end to end when you need the repeated incidents, top frames, and mod-vs-framework blame split first. Usage: unitydiag [OPTIONS] [PATH...] Example: unitydiag --game-root 'C:\game' --json | ConvertFrom-Json Guided answer: Answer Unity/BepInEx log incidents, grouped frames, and mod/runtime warnings. Trust basis: Trust discovered log paths, grouping counts, and preserved stack snippets. Next actions: Use asmref diagnose for plugin dependency issues. | Use unityprobe when live object state is needed. TOON example: unitydiag --game-root 'C:\game' --toon

binmeta

Use: Inspect file metadata, Windows PE basics, version/company/product identity, embedded Authenticode certificate tables, WinTrust status, catalog signing, signer certificate subjects, chains, timestamps, and expiry hints. Better than: opening heavy PE tooling or shelling out to signature utilities when you first need binary identity, PE basics, version resources, and Windows signing status. Usage: binmeta [OPTIONS] [PATH...] Example: binmeta .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json Guided answer: Answer file identity, PE basics, version resource fields, company/product names, signature status, embedded-vs-catalog signing, signer subject, certificate chain, timestamp, and expiry fields before deeper binary analysis. Trust basis: Trust goblin PE/resource parsing for local structure and Windows WinTrust/catalog status on Windows; signature failures are reported as metadata, not command failures. On non-Windows, trust only embedded certificate table presence and treat WinTrust fields as unsupported. Next actions: Use peimports or llvmreadobj for deeper PE detail after identity is known. | Use drvshape or ioctlscan for signed drivers and native/system binaries. | Use stringscan or pestrrefs when identity/version metadata is missing or suspicious. TOON example: binmeta .\target\debug\jsonlgrep.exe --toon

stringscan

Use: Extract and classify high-signal strings from binaries or blobs. Better than: a full reverse-engineering pass when you first need identity clues from strings. Usage: stringscan [OPTIONS] [PATH...] Example: stringscan <PATH> Guided answer: Answer strings and classified hints from arbitrary blobs. Trust basis: Trust extracted string offsets and classification labels; encoding limits are explicit. Next actions: Use binmeta first for binary identity. | Use pestrrefs for PE strings with xrefs. TOON example: stringscan --toon <PATH>