AEL Docs
Follow updates
Menu
Follow updates
Browse the documentation

Preview documentation for AEL Beta 0.0.1 — launching soon

Package commands

In AEL, the Agent Engineering Language, ael pack (command names may change before launch) will manage 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.

Status

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

The commands

CommandWhat it will do
ael pack add <name>[@<version>]Add a new package to a manifest, resolve it and install it, all at once.
ael pack installInstall 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 listList declared, installed and used packages.
ael pack why <name>Explain why a package is in the project.
ael pack verifyVerify installed packages against the lock file.
ael pack lockResolve and write the lock file without installing.
ael pack graphShow the dependency graph the lock file records.
ael pack lock-diff <before> <after>Compare two lock files.
ael pack vendorExport the locked packages for offline builds.
ael pack cache pruneRemove cached packages that nothing uses.
ael pack repairFinish or undo an interrupted package change.

Add or install

  • add will be for a package the project does not use yet. It will write the new entry into pack.ael, then resolve, lock and install it.
  • install will set 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 will never add a package to pack.ael, and add will not be how you set up an existing project on a new machine.

Scopes

Every pack.ael will cover its folder and the folders below it. Each folder of a project will be able to add its own packages without affecting the rest, and the nearest manifest that declares a package will win.

  • Commands that change or list packages will take --scope <folder> to choose the folder whose manifest they act on. Without it, they will use the manifest that covers the folder you are in.
  • Every command will report the scope it acted on.
  • A change will write 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 will be atomic

Adding, installing, updating and removing packages will be atomic and safe to roll back, and a package will never run an install script.

  • Each change will be prepared and verified completely before it replaces anything.
  • The manifest, the lock file and the installed packages will change together: a scope will always be 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 will finish or undo it first, and report what it did. ael pack repair will do that on its own, then check the scope.
  • Nothing in a package will run while packages are resolved, installed, verified or listed.

Every package will be verified

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

The network

CommandsNetwork
add, update, lock, and install without --offlineMay fetch package files and the registry's signed index.
Every other ael pack commandWill work only from what is on your machine.
check, compile, refmap, build, run, testWill never fetch anything.

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

Output

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