Command Reference
ebyte has five commands. They all use the same interpreter as the Go library, and they never guess a format: every command needs a schema. The full reference is cli.md on GitHub.
ebyte validate-schema --schema format.json
ebyte decode --schema format.json --input file.bin --output file.json
ebyte encode --schema format.json --input file.json --output new.bin
ebyte inspect --schema format.json --input file.bin --format text
ebyte diff --schema format.json --before old.bin --after new.bin --format text
Commands
validate-schema checks a schema and prints its name and SHA-256 identity as JSON. It doesn’t read any binary input.
decode reads a binary file and prints the editable JSON document. If the file doesn’t match the schema, nothing is printed on standard output; the diagnostic goes to standard error.
encode reads an edited document and writes the binary file. It checks every value again, works out derived counts, sizes, offsets and checksums, and refuses a document made with a different schema.
inspect prints a trace: every field with its path, kind, offset, length and state, plus the value of each integer. --format json is the default and --format text gives one line per field. If the file breaks the schema, inspect still prints the trace up to the failure, labelled failed, and exits with a nonzero code.
diff (since 0.5.0) decodes two files through the same schema and lists every field that differs, in schema order: changed, added or removed, with its offset and length in each file. Integers show their old and new values, derived ones are marked derived, and bytes and strings show only where they first differ, never their contents. Lists are compared by position. It exits 0 when the files are the same and 5 when they differ; if either file doesn’t match the schema, a one-line JSON message on standard error says which one.
Options
| Option | Used by | What it does |
|---|---|---|
--schema FILE |
All | The schema. Always a file, never standard input |
--input FILE or --input - |
decode, encode, inspect | The input file, or - for standard input |
--before FILE, --after FILE |
diff | The two files to compare; one of them may be - |
--output FILE or --output - |
All | A new file to create, or - for standard output, the default |
--format json or text |
inspect, diff | Output format |
--help, --version |
Print and exit without opening anything |
Both --option value and --option=value work. Unknown or repeated options are a usage error.
--output never replaces anything. EByte writes to a private temporary file, flushes it, then links it to the new name only if nothing is there. An existing file, folder or symlink of that name stops the command with destination_exists. A name that points at a folder, such as out/, is refused too. The finished file gets the usual permissions for your umask, typically 0644. This works on Linux, macOS and, since 0.6.0, Windows, where the file is an ordinary writable file and FAT drives, which lack hard links, fail without writing anything.
Limits
Each default ceiling has a flag that can lower it: --max-schema-bytes, --max-schema-fields, --max-depth, --max-input-bytes, --max-output-bytes, --max-field-bytes, --max-array-elements, --max-value-nodes, --max-trace-entries, --max-document-bytes and --max-trace-bytes. Values are whole numbers and zero is a real limit. Asking for more than the default is an error. The defaults are on the schema reference.
Exit Codes and Diagnostics
| Exit | Meaning |
|---|---|
| 0 | Done |
| 1 | I/O failure, including destination_exists and a broken output pipe |
| 2 | Usage error, or an invalid schema, document or binary file |
| 3 | Cancelled with Ctrl-C, or SIGTERM on Linux and macOS |
| 4 | A size limit was reached |
| 5 | diff only: the files differ |
A failure prints one line of JSON on standard error:
{"diagnostic_version":1,"stage":"decode","code":"truncated_input","path":"/samples","offset":1000,"field_start":44,"expected":"1600 bytes","observed":"956 bytes"}
stage is schema, decode, encode or io. path is a JSON pointer to the field. offset is the byte where things went wrong and field_start is where that field began; either is null when it isn’t known, never a made-up zero. The codes are invalid_schema, invalid_document, schema_mismatch, constraint_mismatch, truncated_input, trailing_data, invalid_encoding, value_out_of_range, count_mismatch, limit_exceeded, cancelled, read_failed, write_failed and destination_exists.
Diagnostics describe lengths and positions only. They don’t echo file contents, string values, filenames or command arguments, so they’re safe to put in a log or a bug report.