Authoring commands

Scaffold a new Aion workflow project from a template.

aion new [OPTIONS] <NAME>

<NAME>

Project name; becomes the directory and the AWL workflow or Gleam entry module. Must be lowercase `snake_case`: a lowercase letter followed by lowercase letters, digits, or underscores

--template <TEMPLATE>

Scaffold template Possible values: - awl: AWL-first typed workflow with no activities or external worker - hello-world: Minimal typed workflow with no activities: start → complete - approval-flow: Approval signal raced against a durable timeout, with a stage query and every outcome path - saga: Worker-served payment activity with workflow-driven retries, an approval race, a status query, and refund compensation - dev-pipeline: The durable dev pipeline: an agent develops a brief, a scoped verify-fix loop, a workspace gate, human review by signal, land — three composed workflows plus a CLI-shelling worker. Workflow-level I/O codecs and schemas are generated from the authored types module by `aion generate`. Requires `--worker rust` - agent: A durable agent loop: scout → act → verify → signal-gated human review, parameterised by prompts and a review deadline. The three agent steps are worker-served activities; the human approval pause is a durable `workflow.receive` with a timeout. Bundles no agent runtime — the driver stays worker-side. Workflow I/O codecs and schemas are generated from the authored types module by `aion generate`. Requires `--worker rust` [default: awl]

--worker <WORKER>

Additionally scaffold an activity worker crate under `worker/` serving the template's activities. Only templates that dispatch activities (saga, dev-pipeline) accept this; dev-pipeline requires it Possible values: - rust: A Rust crate under `worker/` built on the `aion-worker` SDK

Generate every derived artifact from a package's authored Gleam types.

aion generate [OPTIONS] [PATH]

[PATH]

Workflow project root containing `gleam.toml`, `workflow.toml`, and `src/<package>_io.gleam` [default: .]

--check

Verify every generated file on disk is current instead of writing; exits non-zero naming the drifted file (CI gate)

Statically check a workflow project for determinism violations.

aion check [OPTIONS] [PATH]

[PATH]

Workflow project root containing `workflow.toml` and `src/` [default: .]

--deterministic

Run the determinism gate. Required: `check` performs the determinism analysis only

Emit a valid input skeleton derived from a workflow's input type.

aion input [OPTIONS] <WORKFLOW_TYPE> [PATH]

<WORKFLOW_TYPE>

Workflow type (the workflow's `entry_module`)

[PATH]

Workflow project root containing `workflow.toml` and `schemas/` [default: .]

Package an already-built Gleam workflow project into `.aion` archives.

aion package [OPTIONS] [PATH]

[PATH]

Workflow project root containing `workflow.toml` [default: .]

--out <OUT>

Archive output path, resolved against the current directory. Only valid when the project declares exactly one workflow

--build

Run `gleam build` in the project before packaging

The instant authoring loop: watch a workflow project and hot-load on save.

aion dev [OPTIONS] --gleam-path <GLEAM_PATH> [PATH]

[PATH]

Workflow project root containing `gleam.toml` and `workflow.toml`. The project's `src/` tree is watched for changes [default: .]

--gleam-path <GLEAM_PATH>

Required path to the Gleam compiler used for rebuilding the project.

--debounce-ms <DEBOUNCE_MS>

Optional milliseconds to combine changes before rebuilding. When omitted, each change triggers a rebuild; duplicate content hashes reuse the loaded version.

--message-format <MESSAGE_FORMAT>

How the loop reports what it does. `human` (the default) prints prose for an author at a terminal. `json` prints JSON Lines on stdout — one object per event (`priming`, `watching`, `reloaded`, `rebuild_failed`), tagged by its `event` field and flushed as it happens — for a program driving the loop to wait on Possible values: - human: Prose for an author at a terminal: progress on stdout, a failed rebuild on stderr - json: JSON Lines on stdout: one [`DevEvent`] object per line, tagged by its `event` field, flushed as each is written [default: human]

Author AWL workflow documents (rev-2 surface): check, format, emit Gleam, derive JSON Schema, and read the language's own guide.

aion awl [OPTIONS] <COMMAND>

Parse and typecheck a rev-2 AWL workflow document: declarations, binding flow along the step graph, `after`/route targets, outcome exhaustiveness, and both schema doors.

aion awl check [OPTIONS] <FILE>

<FILE>

Path to the `.awl` document, or a `.awlb` binding document

--bind <BIND>

Venue binding to compose `file` with before checking. Repeatable

Reformat an AWL workflow document in place.

aion awl fmt [OPTIONS] <FILE>

<FILE>

Path to the `.awl` document, or a `.awlb` binding document

Emit an executable artifact from an AWL document.

aion awl emit [OPTIONS] <FILE>

<FILE>

Path to the `.awl` document

-o, --output <OUTPUT>

Path to write the emitted artifact. Optional for `--target gleam` (defaults to stdout); REQUIRED for `--target beam`

--target <TARGET>

Output form: `gleam` source (default) or `beam` bytecode Possible values: - gleam: Gleam source (the stopgap execution target until AWL bytecode is the only path). Writes to `--output` or stdout - beam: Direct BEAM bytecode via `aion_awl::compile` — the same seam the ops console's deploy path uses. Requires `--output` [default: gleam]

Generate a compiling Rust worker crate for the document's declared worker(s).

aion awl scaffold [OPTIONS] --out <OUT> <FILE>

<FILE>

Path to the `.awl` document

--out <OUT>

Directory the generated crate(s) are written into

--worker <WORKER>

Scaffold only this `worker` block; omitted, every block is scaffolded

--aion-crates <AION_CRATES>

Path to a local aion checkout's `crates/` directory. Given, the generated crate depends on the aion SDK BY PATH; omitted, it depends on the published crates at this binary's own version

Emit JSON Schema draft 2020-12 for a declared AWL type

aion awl schema [OPTIONS] <FILE>

<FILE>

Path to the `.awl` document

--type <TYPE>

Declared type to derive; omitted, emits the workflow's start contract (its inputs)

--queries

Emit the read-only surface instead: every declared `query` name with the schema of the answer an operator receives

--outcomes

Emit the outcome envelope instead: which declared outcome fired, with the payload it carries — the shape a run's end has, and the one a board reads its card outputs out of

Print what a word of AWL means, with a checked example and where it is explained in full.

aion awl guide [OPTIONS] [WORD]

[WORD]

The word to explain; omitted, every word of the language is printed

--json

Emit the glossary as JSON instead of as text

--reference

Print the full embedded AWL language reference and exit

Render a document's own comments as documentation.

aion awl doc [OPTIONS] <FILE>

<FILE>

Path to the `.awl` document or `.aion` archive

--format <FORMAT>

Which rendering to write Possible values: - html: A self-contained HTML page: prose, declarations, types, the contract, and an inline SVG of the step graph - json: The model's canonical JSON — the documentation site's input contract - markdown: Markdown, for a README or a wiki - plain: The plain step view: the step graph as a numbered list in reading order, for a reader who is asking what happens rather than what the shape is [default: html]

--output <OUTPUT>

Write to this file instead of stdout

Compose or FIRE a declared recipe — the executing verb of the assembly surface.

aion awl recipe [OPTIONS] <COMMAND>

Compose a declared recipe against the values a dispatch supplies, WITHOUT running anything.

aion awl recipe compose [OPTIONS] --name <NAME> <FILE>

<FILE>

Path to the `.awl` document

--name <NAME>

The declared recipe to compose

--fill <SLOT=VALUE>

One `slot=value` binding. Repeat for each slot

FIRE a declared recipe against the working tree.

aion awl recipe fire [OPTIONS] --name <NAME> <FILE>

<FILE>

Path to the `.awl` document

--name <NAME>

The declared recipe to fire

--fill <SLOT=VALUE>

One `slot=value` binding. Repeat for each slot

--met <PRECONDITION>

Mark a declared precondition as met. Repeat for every required precondition.

--root <ROOT>

The root the artifact addresses resolve against; omitted, the document's own directory

--receipt <RECEIPT>

Write the generated receipt here as well as to stdout

Run the AWL language server over stdio for editor integration

aion awl lsp [OPTIONS]

Deploy `.awl` documents and `.aion` archives, singly or in batches (operator API).

aion deploy [OPTIONS] <PATH>...

<PATH>...

`.awl` documents, `.aion` archives, or directories (walked recursively for both). At least one

--bind <BINDING.awlb>

Compose each AWL source with this venue binding before deployment. Archives cannot be bound; every local refusal precedes upload

--dry-run

Prepare everything locally, ask the server what it already holds, and report what the batch would change. Uploads nothing

--fail-fast

Stop at the first archive the server refuses; later entries are reported as not attempted. Without it every archive is attempted. An unreachable server always stops the batch

--max-inflated-bytes <BYTES>

Optional byte ceiling for each locally expanded archive, including archives built from AWL. An archive above the ceiling is refused before upload. Omitted means unbounded local expansion.

Compile, deploy, start, and await an AWL workflow in one motion.

aion run [OPTIONS] --input <INPUT> <FILE>

<FILE>

Path to an `.awl` workflow document

--input <INPUT>

JSON input payload, validated before deployment

--timeout <TIMEOUT>

Optional bound on how long this command waits for the run's terminal event, written as an AWL duration literal (`30s`, `5m`, `3h`, `2d`). There is NO default: absent, the wait is bounded only by the document's own `timeout` declaration, which the engine enforces as a deadline. A document declaring no timeout and no `--timeout` here waits indefinitely. Reaching this bound stops the WAIT, never the run — the workflow continues on the server.