# Authoring commands

Captured help for project generation, AWL, bytecode packaging and deployment.

Local authoring commands read or write project files. Deploy and run contact a server. Run also starts an execution and waits for its terminal result.

## new

Scaffold a new Aion workflow project from a template.

```text
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

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

```text
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)


## check

Statically check a workflow project for determinism violations.

```text
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


## input

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

```text
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

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

```text
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


## dev

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

```text
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]


## awl

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

```text
aion awl [OPTIONS] <COMMAND>
```



## awl check

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.

```text
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


## awl fmt

Reformat an AWL workflow document in place.

```text
aion awl fmt [OPTIONS] <FILE>
```

- `<FILE>`: Path to the `.awl` document, or a `.awlb` binding document


## awl emit

Emit an executable artifact from an AWL document.

```text
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]


## awl scaffold

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

```text
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


## awl schema

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

```text
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


## awl guide

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

```text
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


## awl doc

Render a document's own comments as documentation.

```text
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


## awl recipe

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

```text
aion awl recipe [OPTIONS] <COMMAND>
```



## awl recipe compose

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

```text
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


## awl recipe fire

FIRE a declared recipe against the working tree.

```text
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


## awl lsp

Run the AWL language server over stdio for editor integration

```text
aion awl lsp [OPTIONS]
```



## deploy

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

```text
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.


## run

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

```text
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.



Check and emit can refuse different source shapes. Read [the compiler boundaries](/aion/reference/awl/#compiler-boundaries). Recipe compose builds the assembly description. Fire executes its declared programs.