Machine-readable output

Every command of AEL, the Agent Engineering Language, 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, ael check --json reports its diagnostics as JSON.

Usage

ael check --json
ael pack list --json
ael 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 AEL's project, package and agent files are published on docs.ael.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:

Command	Ends with a failure status when
`ael check`, `ael compile`, `ael build`	A diagnostic reports an error.
`ael fmt --check`	A file would change.
`ael test`	A test fails.
`ael eval`	A contract or regression case fails.
`ael pack verify`	An installed file does not match the lock file.
`ael pack install --locked`	The lock file would have to change.
`ael doctor`	Something blocks AEL 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.

Diagnostics: the fields of a diagnostic.
Command-line reference: every command and the options they share.