Output and errors

Envelope

When stdout is not a terminal, every command prints one JSON document.

{ "ok": true, "command": "record show", "tool_version": "0.1.0+0123456789ab", "data": {}, "warnings": [], "elapsed_ms": 5 }

{
  "ok": false,
  "command": "record show",
  "tool_version": "0.1.0+0123456789ab",
  "error": { "code": "NOT_FOUND", "message": "...", "hint": "...", "details": {} }
}

When a command takes a value from a project file, the document also has a project field with the file and the values.

tool_version identifies the build that made the document: the version, then + and the git commit. A build from a changed source tree ends with .dirty. A build without git has the version only. esx --version prints the same data:

esx --version
# esx 0.1.0 (commit 0123456789ab, dirty)

Use --format jsonl to print list items one per line. Use --pretty to indent the JSON.

Exit codes

Code	Meaning
0	Success.
2	Usage error.
3	Not found.
4	Invalid argument or value.
5	I/O or format error.
6	Not allowed or not supported.
7	Issues found.
70	Internal error.

Command catalog

esx commands --format json

The catalog lists every command with its arguments and examples. Scripts and AI agents can read it.

Debug a record

Use these commands when a value looks wrong:

esx debug explain MyMod.esp edid:MyWeapon
esx debug subrecords MyMod.esp edid:MyWeapon
esx debug hexdump MyMod.esp edid:MyWeapon
esx debug scan MyMod.esp
esx defs show WEAP --values

debug explain is the best first step. It prints byte offsets, sizes, hex data and every union and array decision. Add --trace to record show to include the same trace.

esx debug roundtrip decodes and encodes every record in memory. It reports byte changes and writes no plugin.