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>`