Machine-readable output
Every command of AEL, the Agent Engineering Language, will take --json and then report 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 (command names may change before launch) will report its diagnostics as JSON.
Status
Planned for AEL Beta 0.0.1. AEL is not available yet.
Usage
ael check --json
ael pack list --json
ael refmap src/api --json
--json will change the form of the report, never what the command does: the same checks will run, the same files will change or stay as they are, and the exit status will be the same.
One document per run
- A command with
--jsonwill write one JSON document, whether it succeeds or fails. - The document will carry its format version, so a tool can tell which shape it is reading.
- A failure will be reported in the same document as a success would be, with what failed and the diagnostics that explain it.
- Object keys will 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 will follow 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, will have its own shape. Those shapes will be described on each command's page when they are final.
JSON Schemas for AEL's project, package and agent files are published on docs.ael.openeng.ai, each at an address that will never change. Some of them, such as the package manifest and lock file, are still drafts. JSON Schemas lists them all.
Time and token reports
Time and token usage will be 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 will stay unchanged for pipes and scripts. You will be able to turn off each field without disabling the limits behind it. See Reporting, logs and replay.
Exit status
Every command will end 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 will be able to rely on the status alone. The exact status values will be published with the beta.
Output will be bounded
Reports will 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 will say so instead of cutting its report short without a word.
Related
- Diagnostics: the fields of a diagnostic.
- Command-line reference: every command and the options they share.