0003 — prototext CLI design

Status: implemented App: prototext Implemented in: 2026-03-10

Problem

A standalone Rust binary (prototext) is needed that exercises prototext-core end-to-end. Before implementation can start, the CLI surface must be precisely specified.

Goals

• Define all CLI flags with short and long forms.
• Define input/output routing for single-file, multi-file (glob/directory), and in-place batch modes.
• Define schema flag semantics including the embedded-descriptor fast path.
• Shell completion: dynamic, DIR-aware, using clap + clap_complete (unstable-dynamic feature), same model as Cargo.
• Be precise enough that implementation can proceed without further design discussion.

Non-goals

• MPM archive traversal.
• Python module schemas (.pb descriptors only).
• Kernel selection: always protoc.
• Self-test (--self-test), lax mode, --force, --debug.
• Lossless round-trip verification on decode (may be added later).
• Static pre-generated completion scripts (dynamic completion replaces them).

Specification

Flags

Mode

-d and -e are mandatory and mutually exclusive: exactly one must be given. Omitting both or supplying both is an error.

Schema

Rules:

• -D and -t must be both given or both absent. One without the other is an error.
• When -t is given without -D, the binary's embedded descriptor is used as the schema source. This covers all google.protobuf.* types (notably google.protobuf.FileDescriptorProto) without requiring a file on disk.
• When both are absent, schemaless mode: fields are rendered by wire-type and field number only, with no field names.
• The same schema applies to all inputs in a single invocation.

Summary:

Output

Input

Other

Positional arguments

prototext -d|-e [OPTIONS] [PATH...]

Each positional PATH may be:

• A file path — processed as a single input file.
• A glob pattern — expanded by the binary against the filesystem, yielding zero or more input files. Uses standard glob syntax (*, **, ?, [...]). A glob that matches zero files is an error.
• A directory path — all files under the directory are included recursively.

When -I DIR is given:

• Positional PATHs are resolved relative to DIR.
• Glob patterns are expanded relative to DIR.
• Absolute positional paths are an error.

When -I is absent, all of the above are relative to cwd.

No positional arguments — read from stdin. -i and -O are errors when reading from stdin (no path to write back to).

Output routing

Exclusive flag constraints (enforced at startup, before any I/O)

• -o and -O are mutually exclusive.
• -i and -O are mutually exclusive.
• -I DIR and -O DIR resolving to the same directory is an error (use -i instead).
• Absolute positional paths with -I given is an error.
• Two input files resolving to the same output path is an error.

Single input (stdin or exactly one resolved file)

Output goes to stdout unless -o PATH is given, in which case output goes to PATH. -O with a single input is an error.

Batch mode (two or more resolved files)

Batch mode requires either -i or -O. Neither with multiple inputs is an error.

Each input file has a relative path:

• If -I DIR is given: the file's path relative to DIR.
• If -I is absent: the path as given on the CLI (or as expanded from the glob/directory).

The output path for each file is:

• -O DIR: DIR/<relative-path>, creating parent directories as needed.
• -i: the file's original absolute path. Each file is read fully into memory before its output is written (sponge semantics — safe even when input and output are the same path).

Extension is never changed in batch mode.

Error handling

• Unknown flags, conflicting flags, or invalid flag combinations → stderr + exit 2.
• Input file not found, or glob matches zero files → stderr + exit 1.
• Schema parse failure → stderr + exit 1.
• Decode or encode failure → stderr + exit 1.
• Output write failure → stderr + exit 1.

In batch mode, a failure on one file does not abort processing of subsequent files. All errors are collected and printed to stderr at the end. Exit code is 1 if any file failed, 0 if all succeeded.

Shell completion

Dynamic completion using clap + clap_complete with the unstable-dynamic feature enabled — the same model used by Cargo today (CARGO_COMPLETE=bash cargo).

Activation:

# bash (with workaround for path-completion bugs in clap_complete)
source <(PROTOTEXT_COMPLETE=bash prototext | sed \
  -e '/^\s*) )$/a\    compopt -o filenames 2>/dev/null' \
  -e 's|words\[COMP_CWORD\]="$2"|local _cur="${COMP_LINE:0:$COMP_POINT}"; _cur="${_cur##* }"; words[COMP_CWORD]="$_cur"|')

Completion behaviour:

• All flags and their value types complete correctly.
• Positional PATH arguments complete relative to -I DIR when -I has already been typed; otherwise relative to cwd. Implemented via a custom ArgValueCompleter (complete_input_paths) that reads -I from the already-parsed partial args.
• -D PATH completes .pb files only (custom complete_pb_files).
• -t NAME completes known message names: from the descriptor at -D if -D has already been typed, or from the embedded descriptor otherwise (complete_type_names).

Bash word-split fix for dotted type names. Bash uses . as a COMP_WORDBREAKS character, so google.protobuf.F is split and the binary only receives F as the current token. The generated completion script is patched with two sed substitutions at load time (see activation command above):

1. compopt -o filenames — tells readline candidates are filesystem paths, suppressing bash's tendency to strip the dotted prefix.
2. Word reassembly from COMP_LINE/COMP_POINT — reconstructs the full token (e.g. google.protobuf.F) so the prefix filter in complete_type_names works correctly.

Implementation notes

• Argument parsing: clap (derive API).
• Shell completion: clap_complete with unstable-dynamic feature.
• Glob expansion: globset crate.
• Embedded descriptor: compiled into the binary via include_bytes!.

Examples

# Decode foo.pb to stdout (schemaless)
prototext -d foo.pb

# Decode foo.pb with schema (annotations on by default)
prototext -d -D knife.pb -t SwissArmyKnife foo.pb

# Decode foo.pb with schema, suppress annotations (protoc-compatible output)
prototext -d -D knife.pb -t SwissArmyKnife --no-annotations foo.pb

# Decode a FileDescriptorProto using the embedded descriptor
prototext -d -t google.protobuf.FileDescriptorProto foo.pb

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

# Batch decode all .pb files under src/, write results under out/
prototext -d -D knife.pb -t SwissArmyKnife -I src/ -O out/ '**/*.pb'

# In-place batch encode (read fully, then overwrite)
prototext -e -i '**/*.txtpb'

# Read from stdin, decode schemalessly
cat foo.pb | prototext -d

# Enable bash completion
source <(PROTOTEXT_COMPLETE=bash prototext | sed \
  -e '/^\s*) )$/a\    compopt -o filenames 2>/dev/null' \
  -e 's|words\[COMP_CWORD\]="$2"|local _cur="${COMP_LINE:0:$COMP_POINT}"; _cur="${_cur##* }"; words[COMP_CWORD]="$_cur"|')

Open questions

• stdin in batch: - as explicit stdin placeholder in the positional list would enable scripting convenience (e.g. prototext -d - foo.pb to mix stdin with files). Disallow -i when - is in the list. Deferred.

References

• docs/annotation-format.md — annotation grammar
• fixtures/index.toml — shared fixture set