Binary Structure CLI Tool

Decodes and encodes binary data with any binstruct package, reading stdin and writing stdout so it drops into a pipeline. Decoded structures leave as JSON5 — quoted-where-needed keys, 0x byte literals and // |ascii| comments — which is what encode reads back.

The argument list is a prefix chain, and every prefix of it is a valid invocation (ADR 0001):

binstruct [--] [<package> [<coder> [<command>]]] [options]

A prefix that stops short prints guidance for the missing word — what it means, the values it may take, and a paste-ready command one step further along — to stderr, and exits 1. --help prints the same material to stdout and exits 0. Stdout otherwise carries the payload and nothing else, so a half-typed binstruct png > out.json5 leaves out.json5 empty instead of filling it with a help screen.

A bare package name means the @binstruct scope on JSR (ADR 0004), and a package exposing exactly one zero-argument coder may omit the <coder> word (ADR 0005).

The PACKAGES block is JSR's own scope listing, fetched and cached for a day (./scope.ts, ADR 0006), so it names what is published rather than what was published when this CLI was released. That costs --allow-net=jsr.io; the listing is a hint, so without the permission, without a network, or against a JSR that will not answer, the block is omitted and the screen still says how to name a package. Listing the coders of a package costs --allow-run=deno in the same way (ADR 0002) — but that listing is not only a hint, since it also says how many arguments each factory takes. Without it a coder you name is accepted, and then refused unless its factory takes no arguments at runtime: the CLI has none to pass, and calling one that wanted some lets the argument default silently.

binstruct png pngFile decode < input.png > struct.json5

binstruct arp decode < arp.bin > arp.json5

binstruct ./my-package/mod.ts decode < input.bin > output.json5

binstruct -- -dash/mod.ts decode < input.bin > output.json5