Package commands

In AEL, the Agent Engineering Language, ael pack manages the packages a project uses: the manifest pack.ael, the lock file pack.lock and the installed packages in .package/. To build your own project into a package file, use ael package instead.

The commands

Command	What it does
`ael pack add <name>[@<version>]`	Add a new package to a manifest, resolve it and install it, all at once.
`ael pack install`	Install exactly what `pack.ael` and `pack.lock` already say.
`ael pack update <name>`	Move a package to another version its requirement allows.
`ael pack remove <name>`	Remove a package, keeping the packages others still need.
`ael pack list`	List declared, installed and used packages.
`ael pack why <name>`	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 <before> <after>`	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.

Add or install

add is for a package the project does not already use. It writes the new entry into pack.ael, then resolves, locks and installs it.
install sets up what is already declared and locked, such as on a new machine or in an automated build.

Never use one for the other: install never adds a package to pack.ael, and add is not how you set up an existing project on a new machine.

Scopes

Every pack.ael covers its folder and the folders below it. Each folder of a project can add its own packages without affecting the rest, and the nearest manifest that declares a package wins.

Commands that change or list packages take --scope <folder> to choose the folder whose manifest they act on. Without it, they use the manifest that covers the folder you are in.
Every command reports the scope it acted on.
A change writes only that scope's pack.ael, pack.lock and .package/, never those of a parent or sibling folder.

Using packages describes scopes in full.

Changes are atomic

Adding, installing, updating and removing packages are atomic and safe to roll back, and a package never runs an install script.

Each change is prepared and verified completely before it replaces anything.
The manifest, the lock file and the installed packages change together: a scope is always either as it was before or as it is after, never a mix.
If a change is interrupted, the next package command in that scope finishes or undoes it first, and reports what it did. ael pack repair does that on its own, then checks the scope.
Nothing in a package runs while packages are resolved, installed, verified or listed.

Every package is verified

AEL verifies every package before using it, whatever its host: its fingerprint, its contents and how it was built. Official packages also have to carry OpenEng's signature. A package that fails any check is refused before anything is written into your project.

The network

Commands	Network
`add`, `update`, `lock`, and `install` without `--offline`	May fetch package files and the registry's signed index.
Every other `ael pack` command	Works only from what is on your machine.
`check`, `compile`, `refmap`, `build`, `run`, `test`	Never fetch anything.

Access tokens for your private host stay outside your project files. One manifest and one lock file give reproducible builds that also work offline.

Output

Every package command takes --json for machine-readable output, and ends with a failure status when it refuses or fails. Machine-readable output describes both.

Packages: official and private packages.
Using packages: the manifest, folder scopes and the lock file.
Private packages: declaring a package file you host yourself.
Manifest reference: every field of pack.ael, and version requirements.