Quick Start

EByte reads a binary file through a schema you write, turns it into JSON you can edit, and writes it back. This page goes from download to your first round trip in a few minutes, using the example that ships in every archive.

1. Get the Tool

Download the archive for your system from the download page and unpack it. On Linux or macOS:

tar -xzf ebyte-linux-amd64.tar.gz
cd ebyte
./ebyte --version

That prints the version, such as ebyte 0.2.0. The folder also holds examples/, the manual and the license files.

2. Look Inside a File

examples/packet.bin is a 21-byte file in a small made-up format. On its own it’s just bytes. With its schema, inspect lists every field with its offset and length:

./ebyte inspect --schema examples/packet.schema.json --input examples/packet.bin --format text

EByte trace state=complete schema_sha256=126bf06f...
"" struct offset=0 length=21 state=complete
"/magic" bytes offset=0 length=2 state=complete
"/version" u8 offset=2 length=1 state=complete value=1
"/record_count" u8 offset=3 length=1 state=complete value=2
"/flags" u8 offset=4 length=1 state=complete value=1
"/label" string offset=5 length=4 state=complete
"/reserved" bytes offset=9 length=2 state=complete
"/records" array offset=11 length=8 state=complete
...
"/note" bytes offset=19 length=2 state=complete

Leave out --format text and you get the same trace as JSON.

3. Decode, Edit, Encode

decode turns the file into an editable document:

./ebyte decode --schema examples/packet.schema.json --input examples/packet.bin --output packet.json

Integers come out as decimal strings, so 64-bit values never lose precision in JSON. Raw bytes come out as lowercase hex. record_count isn’t in the document at all, because the schema says it’s derived from the records array. Add a record in any editor:

{"id": "3", "temperature": "-1"}

Then encode:

./ebyte encode --schema examples/packet.schema.json --input packet.json --output edited.bin

edited.bin is 25 bytes. The count byte went from 2 to 3 on its own, and the note field moved from offset 19 to 23. Encode the unchanged packet.json instead and you get the original 21 bytes back, every one of them.

--output only ever creates a new file. If the name already exists, EByte stops with destination_exists and leaves the old file alone. On Windows, --output to a file isn’t supported yet: leave it off and redirect standard output from cmd.exe.

4. See a Failure

Cut the file short and decode it:

head -c 16 examples/packet.bin > short.bin
./ebyte decode --schema examples/packet.schema.json --input short.bin

{"diagnostic_version":1,"stage":"decode","code":"truncated_input","path":"/records/1/id","offset":16,"field_start":15,"expected":"2 bytes","observed":"1 bytes"}

The diagnostic names the field, where it starts, and where the bytes ran out. It never prints the file’s contents, only lengths and positions. The exit code tells a script what kind of problem it was: 0 done, 1 an I/O failure, 2 invalid input, 3 cancelled, 4 a size limit.

5. Write Your Own Schema

A schema is a JSON file with a name, a byte order and a list of fields. Here’s the start of one for a WAV audio header:

{
  "schema_version": 1,
  "name": "pcm_wav",
  "endian": "little",
  "fields": [
    {"name": "riff", "type": "bytes", "length": 4, "expect": "52494646"},
    {"name": "riff_size", "type": "u32"},
    {"name": "wave", "type": "bytes", "length": 4, "expect": "57415645"}
  ]
}

Check it before pointing it at a file:

./ebyte validate-schema --schema wav.schema.json

Ready-made schemas for WAV, BMP and ZIP, including ones that read every chunk of a WAV and every entry of a ZIP, are in the schema library. The schema reference lists every field type and option. The command reference covers the flags, limits and exit codes. For a full worked example on a real file, read the WAV case study.

From Go

The command-line tool is a thin layer over the library, so the same steps work in a Go program:

plan, err := ebyte.Compile(schemaBytes, ebyte.DefaultLimits())
if err != nil {
    return err
}
doc, trace, err := plan.Decode(ctx, file)
// edit doc.Values, then:
err = plan.Encode(ctx, doc, out)

Install it with go get github.com/softdevstudio/ebyte. It needs Go 1.27.3 or later and pulls in nothing outside the standard library. A compiled plan is safe to share between goroutines.