PROTOTEXT(1)

📦 version 0.3.6, in nixpkgs unstable

💅 PROTOTEXT(1) — the manual page, but make it cute 💅

Okay bestie, welcome to the PROTOTEXT(1) page from the General Commands Manual — this is all about prototext, the Lossless protobuf ↔ enhanced-textproto converter, and it's about to be your new favorite command. No cap. ✨

🌸 NAME 🌸

prototext — Lossless protobuf ↔ enhanced-textproto converter. That's it, that's the name, and honestly it ate. 💖

✨ SYNOPSIS ✨

Okay so the whole thing goes like this, don't skip a single bracket bestie:

prototext [--descriptor-set] [-o|--output] [-O|--output-root]
[-I|--input-root] [-q|--quiet] [-h|--help] [-V|--version] <subcommands>

💜 DESCRIPTION 💜

Bestie, it's literally the same energy as the NAME: prototext is a Lossless protobuf ↔ enhanced-textproto converter. They really said "if it ain't broke" and honestly? Respect. 😭 But lowkey it's worth repeating because that's the whole entire point — converting between protobuf and enhanced textproto without losing a single thing. Iconic behavior. ✨

🎀 OPTIONS 🎀

  • --descriptor-set <DESCRIPTOR_SET_FILE> — the FileDescriptorSet for type lookup and scoring, and honestly it's the backbone of the whole schema vibe 📋

The file may be a raw binary FileDescriptorSet, a #@ prototext-format FileDescriptorSet, or a single FileDescriptorProto. If a sibling <stem>/hopcroft.rkyv file exists it is loaded automatically and enables scoring and auto-inference. That's the magic right there. ✨

Resolution order (iykyk): (1) this flag, (2) the PROTOTEXT_DESCRIPTOR_SET env var — and yes, PROTOTEXT_DEFAULT_DESCRIPTOR is accepted with a deprecation warning, so it's giving "still works but don't @ me" energy 💀 — (3) the built-in google.protobuf.* fallback. May also be specified with the PROTOTEXT_DESCRIPTOR_SET environment variable.

  • -o, --output <PATH> — write output to PATH, but bestie this is single input only, and it's exclusive with --output-root, so you can't have both, pick a struggle 💅📝
  • -O, --output-root <DIR> — write output files under DIR, mirroring the input tree, which is honestly such a neat vibe 🌳 (exclusive with --output and --in-place, so again, choose wisely bestie)
  • -I, --input-root <DIR> — resolve positional paths and globs relative to DIR. And bestie, if you set this and then use an absolute positional path, that's an error, so don't do it. 🙈
  • -q, --quiet — suppress warnings on stderr, because sometimes you just want peace and quiet 🤫 (errors are always printed though, so you'll never miss those, periodt)
  • -h, --help — print help (and you can see a summary with just -h, cute right? 🎀)
  • -V, --version — print version. That's it. It's giving minimal but necessary. 💅

👑 SUBCOMMANDS 👑

  • prototext-decode(1) — decode binary protobuf to prototext, the classic glow-up from binary to readable text 💅✨
  • prototext-encode(1) — encode prototext to binary protobuf, the reverse icon behavior, we love a two-way street 🫶
  • prototext-list-schemas(1) — score input(s) against the DB and list candidate types, score-descending. It's giving "who fits this blob best" energy 👑
  • prototext-score(1) — score input(s) against a known schema type and report the match breakdown, so you get the receipts 📊
  • prototext-is-canonical(1) — report, per file, whether the blob is canonically encoded (spec 0396): a canonical/anomalous verdict and, when anomalous, each anomaly kind and its count. Exit 0 if all files are canonical, 1 if any is anomalous, 2 on an operational error. The details are detailed, fr fr. 🔍
  • prototext-help(1) — print this message or the help of the given subcommand(s), the "help me help you" of it all 😭

🌈 EXTRA 🌈

Okay bestie here are the extra examples, and they're giving range:

       Examples:
         # Decode to stdout (schemaless)
         prototext decode foo.pb

         # Decode with schema; annotations included by default
         prototext --descriptor-set my.desc decode --type com.example.Foo
       foo.pb

         # Suppress annotations (protoc-compatible output)
         prototext --descriptor-set my.desc decode --type com.example.Foo \
             --no-annotations foo.pb

         # Identify the schema of an unknown binary
         prototext --descriptor-set my.desc list-schemas foo.pb

         # Encode prototext back to binary
         prototext encode foo.txtpb -o foo.pb

🦋 VERSION 🦋

v0.3.6 — that's the version, bestie. It's giving current. 💅

🧚 ENVIRONMENT 🧚

  • PROTOTEXT_COMPLETE — when set to bash, zsh, or fish, it prints a shell completion script to stdout and exits. This is used by the shell completion setup described below, so like, it's the plug for your tab-complete dreams 🐚✨
  • PROTOTEXT_GEN_MAN — when set to a directory, it writes this man page there as prototext.1 and exits. Meta? Maybe. Iconic? Absolutely. 📄💅

💖 EXAMPLES 💖

Okay bestie, this is the part where we get into the examples, and honestly it's giving tutorial energy. Let's go. 💖

Decode a binary protobuf file (schemaless) 🌸

prototext decode message.binpb

Decode with a schema 💜

prototext --descriptor-set descriptor.pb decode --type pkg.MyMessage message.binpb

Decode with inline annotations (on by default; use --no-annotations for clean output) ✨

prototext --descriptor-set descriptor.pb decode --type pkg.MyMessage message.binpb

Encode text back to binary 🎀

prototext encode message.pb > message.binpb

Pipe from protoc 🌈

protoc --encode=pkg.MyMessage descriptor.proto < input.txt | prototext --descriptor-set descriptor.pb decode --type pkg.MyMessage

Decode without annotations but still show unknown fields (default since spec 0103) 🦋

prototext --descriptor-set my.desc decode --type pkg.MyMessage --no-annotations message.binpb

Suppress unknown fields for protoc-compatible output 🧚

prototext --descriptor-set my.desc decode --type pkg.MyMessage --no-annotations --hide-unknown-fields message.binpb

Suppress MessageSet expansion only (Any fields still expand) 💅

prototext --descriptor-set my.desc decode --type pkg.MyMessage --no-expand-message-set message.binpb

Enable bash completion 🌟

source <(PROTOTEXT_COMPLETE=bash prototext)

🫶 SEE ALSO 🫶

protoc(1) — the classic, the OG, the one and only. Check it out if you haven't. 💖

And that's the whole entire page, bestie. This was prototext, from the User Commands manual, PROTOTEXT(1) edition — catch you in the next one. Mwah. 💋✨

📦 where this page comes from