aion-cli

The Aion command line. The crate is named aion-cli; the installed binary is aion — the one user-facing binary for running the server, packaging workflows, deploying packages, and operating workflow executions over gRPC.

Install

cargo install aion-cli --locked

Subcommands

Authoring AWL (.awl documents)

AWL is Aion's workflow language. These run entirely locally and never connect to a server:

• aion awl check <FILE.awl> parses and typechecks a document. Prints ok: <file> (N steps), or compiler-style <file>:<line>:<column>: error: <message> diagnostics on stderr.
• aion awl fmt <FILE.awl> rewrites the document in place with the canonical printer. The printer is the formatter — there is no --check mode.
• aion awl emit <FILE.awl> [--output <PATH>] [--target gleam|beam] emits an executable artifact. --target gleam (the default) writes Gleam source to --output or stdout; --target beam compiles direct BEAM bytecode through the same seam the server's deploy path uses and requires --output, writing a <output>.json sidecar alongside it.
• aion awl schema <FILE.awl> [--type <Type>] [--queries] derives JSON Schema (draft 2020-12). With neither flag it emits the workflow's start contract; --type emits a declared type; --queries emits the read-only surface.
• aion awl scaffold <FILE.awl> --out <DIR> [--worker <name>] [--aion-crates <DIR>] generates a compiling Rust worker crate per worker block, with every wire descriptor taken from the compiled contract.
• aion awl lsp runs the AWL language server over stdio for editor integration.

Deploying and running an .awl document needs no Gleam build, no workflow.toml, and no aion package step:

• aion deploy <FILE.awl> direct-compiles and deploys the document.
• aion run <FILE.awl> --input '<json>' [--timeout <30s|5m|3h|2d>] compiles, validates the input locally against the derived start contract, deploys, starts, and awaits the run in one motion. --timeout has no default: absent, the wait is bounded only by the document's own timeout declaration, and a document declaring neither waits indefinitely. Reaching the bound stops the wait, never the run — the workflow continues on the server.

Server, workers, and Gleam packaging

• aion server --config aion.toml runs the Aion server (the aion-server crate is the library it embeds). --workflow-package <path> preloads .aion archives at boot.
• aion worker shell --manifest worker.toml --awl <FILE.awl> serves strict manifest-wired host commands on a task queue.
• aion worker agent <FILE.awl> --liminal-address <HOST:PORT> --identity <NAME> serves an agent harness compiled into this binary on the queue an .awl document declares — an agent worker without writing a crate. The LAUNCH is the document's, in the worker block's harness section (kind, concurrency, reconnect policy, environment pass-through, and the agent's command and arguments); the command line carries only where this worker connects and who it says it is. --check prints the exact action surface, resolved harness, and intervention controls, then exits without connecting.
• aion new <name> [--template <t>] [--worker rust] scaffolds a workflow project — a checked, runnable AWL document by default, or one of five buildable Gleam templates.
• aion dev --gleam-path <path> watches a Gleam workflow project and hot-loads each save into a running server.
• aion generate [PATH] [--check] derives codecs, schemas, and worker plumbing from a Gleam package's authored types.
• aion check [PATH] --deterministic statically flags wall-clock and entropy calls reachable from Gleam workflow code.
• aion input <workflow-type> [PATH] prints a valid input skeleton derived from the workflow's input schema.
• aion package [PATH] [--out <FILE>] [--build] packages a Gleam workflow project into a .aion archive. Local-only; never connects to a server.
• aion deploy <archive> deploys a .aion archive to a running server (requires the server's [deploy] surface to be enabled).

Versions and run operations

• aion versions [--workflow-type <name>] lists loaded workflow versions with routing flags.
• aion route <workflow-type> <content-hash> re-points routing to an already-loaded version (rollback / roll-forward).
• aion unload <workflow-type> <content-hash> unloads a non-routed, unpinned version.
• aion start <workflow-type> --input '<json>' starts a workflow execution.
• aion signal <workflow-id> <signal-name> --payload '<json>' [--run-id <id>] sends a signal.
• aion query <workflow-id> <query-name> [--run-id <id>] performs a live read-only query.
• aion cancel <workflow-id> [--reason <text>] [--run-id <id>] requests cancellation.
• aion pause <workflow-id> [--reason <text>] [--run-id <id>] durably holds new activity dispatch; aion resume <workflow-id> [--run-id <id>] releases the hold.
• aion reopen <workflow-id> [--run-id <id>] reopens a terminal-reopenable (Failed or Cancelled) run and re-drives it.
• aion list [--status <status>] and aion describe <workflow-id> [--run-id <id>] [--raw] cover visibility and history.
• aion inspect <workflow-id> [--run-id <id>] [--from <seq> --mock <json>] time-travels over a recorded run's oplog, and with --from/--mock (required together) runs a read-only what-if re-run from a chosen event.

Global flags: --endpoint (default 127.0.0.1:50051), --namespace (default default), --subject (default cli-user), --token (overrides the AION_TOKEN environment variable), and --pretty.

Minimal usage

aion --endpoint 127.0.0.1:50051 \
  start hello_world --input '{"name":"Ada"}'

Error reporting

Every operational failure prints one report to stderr and exits with code 1 (CLI usage mistakes exit 2); stdout stays reserved for the JSON result document. Failures that carry the client taxonomy render as

error[<class>]: <operation>: <server detail message>
  server error type: <ErrorType>   # when the wire carried one
  hint: <actionable next step>     # for classes with a known remedy

where <class> is aligned with the wire error codes: not_found, already_exists, query_failed, query_timeout, unknown_query, not_running, cancelled, unavailable, unauthenticated, namespace_denied, invalid_input, backend, and — on the deploy surface — deploy_denied and version_pinned. Local failures without a taxonomy class render their full cause chain on one error: line. The full taxonomy is documented in the repository's errors reference.