Command Reference
ebyte has four 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
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, 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.
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 |
--output FILE or --output - |
All | A new file to create, or - for standard output, the default |
--format json or text |
inspect | Trace 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 and macOS; on Windows --output FILE is switched off for now, so use standard output.
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 |
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.