Skip to main content
Search Documentation & Spec
Type to search all 11 pages

OmniBuf
on the command line.

Command-line inspector and converter for OmniBuf packets. Decode raw wire bytes to JSON, filter nested fields with jq expressions, or encode JSON into self-describing packets.

Install omnibuf CLI
# Homebrew (macOS & Linux)
brew install omnibuf/tap/omnibuf

# mise
mise use -g github:omnibuf/omnibuf-cli

# Shell script
curl -fsSL https://omnibuf.com/install.sh | sh

# Go
go install github.com/omnibuf/omnibuf-cli/cmd/omnibuf@latest

See actual values, not guesses.

Protobuf collapses strings, byte slices, sub-messages, maps, and packed arrays into one wire type, and shares a single varint wire type across booleans, signed integers, and unsigned integers. Inspecting a raw Protobuf packet with protoscope leaves you guessing what each field means. OmniBuf carries an explicit 4-bit wire type on every field, plus element types on arrays and maps. Running omnibuf prints the exact booleans, signed numbers, UTF-8 strings, arrays, and maps on the wire. Packets encoded with Field #0 also decode with their original field names.

protoscope vs. omnibuf cli
$ protoscope packet.pbProtobuf · guesses types
1: 1          # bool / uint / sint / enum?
2: 3          # +3 uint or -2 sint?
3: {"FRA"}    # string / bytes / sub-msg?
4: "\x0a\x14" # bytes / string / packed array?
$ omnibuf -c packet.obufOmniBuf · actual values
{"field_1": true, "field_2": -2, "field_3": "FRA", "field_4": [10, 20]}
$ omnibuf -c packet-field0.obufOmniBuf + Field #0 · actual values & names
{"active": true, "delta": -2, "city": "FRA", "peers": [10, 20]}

Query packets with jq filters.

Pass a jq filter expression as the first argument to slice, select, or reshape decoded fields in a single command. Flags such as -r (raw string output) and -c (compact single-line JSON) work the same way as jq. Hex (-x) and base64 (-b) inputs are supported directly.

jq filter expressions
# Pretty-print any OmniBuf packet as JSON
omnibuf packet.obuf

# Extract a nested field as a raw string (-r)
omnibuf -r '.location.city' packet.obuf

# Filter array elements and emit compact JSON (-c)
omnibuf -c '.neighbors[] | select(.established) | .router' packet.obuf

Convert JSON to OmniBuf and back.

omnibuf auto-detects whether its input is JSON or OmniBuf wire bytes. Piping a JSON object into omnibuf encodes it into a self-describing OmniBuf packet with Field #0 field names and deterministic field tags. Supplying --schema (-s) with a compiled FileDescriptorSet encodes or decodes against your .proto definitions.

json ↔ omnibuf
# Pipe JSON directly into omnibuf to produce self-describing wire bytes (Field #0)
echo '{"event": {"int": 10, "city": "FRA"}}' | omnibuf > event.obuf

# Round-trip back to JSON or query a field in one pipeline
echo '{"event": {"int": 10, "city": "FRA"}}' | omnibuf | omnibuf '.event.city'

# Encode or decode against a compiled Protobuf FileDescriptorSet (.pb, .pb.gz, .json)
omnibuf encode --schema descriptors.pb --type demo.v1.PeerUpdate input.json > packet.obuf
omnibuf decode --schema descriptors.pb --type demo.v1.PeerUpdate packet.obuf