Command-line reference — AEL documentation

AEL, the Agent Engineering Language, comes with one command-line tool, ael. It checks, formats, compiles, builds and runs your code, with diagnostics that point at your source, and it manages packages, targets, devices and deployments. This reference describes each command, one page per command.

Commands are shown without a prompt and without their output.

Projects

Command	What it does
`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 manages the packages a project uses; ael package, above, builds a package file. Keep the two apart.

Command	What it does
`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 does
`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 does
`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 is a target of its own.

--json and --help work with every command. Platforms and deployment lists the targets.

Paths and projects

Most commands take an optional path. Without one, a command works on the project in the current folder.
A project is 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 are never read as source.
Every source file has to stay within the size limit described in Limits. Commands that write source, such as ael fmt, never push a file past it.

Nothing downloads while you build

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

Further capabilities

The command line finds references, renames safely and generates API documentation.
You debug at source level in standard native debuggers, with the debugging information that ael build --debug adds.
You record control and orchestration runs and replay them to find the first point where behaviour diverged. See Reporting, logs and replay.
Changes to the language or project format come with explicit, reviewable migrations.

Reference

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