Browse the documentation

Early preview

Machine-readable output

Every command of the Compiler takes --json and then reports in JSON instead of text, so your own scripts, automated builds and tools can read the result without parsing messages meant for people. For example, oel check --json reports its diagnostics as JSON.

Usage

oel check --json
oel pack list --json
oel refmap src/api --json

--json changes the form of the report, never what the command does: the same checks run, the same files change or stay as they are, and the exit status is the same.

One document per run

  • A command with --json writes one JSON document, whether it succeeds or fails.
  • The document carries its format version, so a tool can tell which shape it is reading.
  • A failure is reported in the same document as a success would be, with what failed and the diagnostics that explain it.
  • Object keys come in a fixed order, so the same result gives the same document, and two documents can be compared as text.

Diagnostics

Every diagnostic in a JSON report follows the published diagnostic schema. Diagnostics describes its fields.

Other report formats

Each command's report, such as the package list, the reference map or a deployment plan, has its own shape.

JSON Schemas for the Compiler's project, package and agent files are published on docs.openeng.ai, each at an address that never changes. JSON Schemas lists them all.

Time and token reports

Time and token usage is reported by default on every channel, the command line included. When a program started from the command line reports on standard error, its own output on standard output stays unchanged for pipes and scripts. You can turn off each field without disabling the limits behind it. See Reporting, logs and replay.

Exit status

Every command ends with a success status when it succeeds, and a failure status when it fails, refuses or finds a problem:

CommandEnds with a failure status when
oel check, oel compile, oel buildA diagnostic reports an error.
oel fmt --checkA file would change.
oel testA test fails.
oel evalA contract or regression case fails.
oel pack verifyAn installed file does not match the lock file.
oel pack install --lockedThe lock file would have to change.
oel doctorSomething blocks the Compiler from building.

A script can rely on the status alone.

Output is bounded

Reports have fixed size limits, so a very large project or a hostile file cannot make a command print without end. A command that reaches a limit says so instead of cutting its report short without a word.