Command-line reference — AEL documentation

AEL, the Agent Engineering Language, will come with one command-line tool, ael (command names may change before launch). It will check, format, compile, build and run your code, with diagnostics that point at your source, and it will manage packages, targets, devices and deployments. This reference describes each command planned for Beta 0.0.1, one page per command.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

The command set is a preview: names, options and behaviour may change before launch, and every example is preview syntax. Commands are shown without a prompt and without their output.

Projects

Command	What it will do
`ael init`	Create a ready-to-build project.
`ael check`	Check a project, a folder or a file without running anything.
`ael fmt`	Format source files, or list the files that would change.
`ael compile`	Produce compiled AEL for every component.
`ael refmap`	Show what references what, with unused code and packages.
`ael build`	Build a native executable or a firmware image for one target.
`ael run`	Check, build and run a program in one step.
`ael test`	Run a project's tests.
`ael package`	Build a package file from your own project.

Packages

ael pack will manage the packages a project uses; ael package, above, will build a package file. Keep the two apart.

Command	What it will do
`ael pack add`	Add a new package to a manifest, and install it.
`ael pack install`	Install exactly what the manifest and lock file already say.
`ael pack update`	Move a package to another version its requirement allows.
`ael pack remove`	Remove a package, keeping the packages others still need.
`ael pack list`	List declared, installed and used packages.
`ael pack why`	Explain why a package is in the project.
`ael pack verify`	Verify installed packages against the lock file.
`ael pack lock`	Resolve and write the lock file without installing.
`ael pack graph`	Show the dependency graph the lock file records.
`ael pack lock-diff`	Compare two lock files.
`ael pack vendor`	Export the locked packages for offline builds.
`ael pack cache prune`	Remove cached packages that nothing uses.
`ael pack repair`	Finish or undo an interrupted package change.

Agents, prompts and configuration

Command	What it will do
`ael eval`	Run an evaluation suite against a prompt or model change.
`ael prompt diff`	Show how prompts changed against a released version.
`ael config explain`	Explain where each configuration value comes from.

Targets, devices and deployment

Command	What it will do
`ael doctor`	Report the toolchain, installed targets and anything missing.
`ael target install`	Set up what a target needs.
`ael devices`	List connected devices.
`ael flash`	Write a firmware image to one selected device.
`ael monitor`	Show a device's output.
`ael deploy`	Plan a staged deployment, then apply the plan you reviewed.

Common options

Option	Meaning
`--json`	Machine-readable output instead of text. See Machine-readable output.
`--help`	The command's usage.
`-o <path>`	Where to write output, for commands that write a file or a folder.
`--target <target>`	The target to check or build for: an operating system and processor, or a microcontroller board. A board will be a target of its own.

--json and --help will work with every command. Platforms and deployment lists the targets planned for the beta.

Paths and projects

Most commands will take an optional path. Without one, a command will work on the project in the current folder.
A project will be a folder with main.ael, pack.ael and metadata.ael at its root. Project layout describes the rest.
Installed packages (the .package folders) and the output AEL writes will never be read as source.
Every source file will have to stay within the size limit described in Limits. Commands that write source, such as ael fmt, will never push a file past it.

Nothing will download while you build

Checking, compiling, building and running will use only the packages that are already installed and pinned by your lock files. These commands will never look for updates, contact a registry or run package code, and a missing package will be an error that names the command that installs it. Only the package commands will fetch packages. With one manifest and one lock file, builds will repeat, even offline.

Coming without a command name yet

These capabilities are planned for the beta, and their commands will be named before launch:

Finding references, renaming safely and generating API documentation.
Debugging at source level in standard native debuggers, beyond the debugging information that ael build --debug will add.
Recording control and orchestration runs and replaying them to find the first point where behaviour diverged. See Reporting, logs and replay.
Explicit, reviewable migrations when the language or project format changes.

Reference

Diagnostics: what a diagnostic will tell you, in text and in JSON.
Machine-readable output: --json, report formats and exit status.