# First Gleam workflow

Scaffold typed Gleam workflow code, build it and deploy its package.

Choose Gleam when a workflow needs typed application code beyond AWL's declarations. Build it to BEAM bytecode, package it and deploy it to the same Aion server.

## Before you begin

Install Gleam and Erlang/OTP on the authoring machine. Have a server with the deploy surface enabled. Use the same endpoint and namespace for deployment and start.

## Build the greeting

**Terminal**

```bash
aion new hello_gleam --template hello-world
cd hello_gleam
gleam build
aion check --deterministic .
aion package .
aion deploy hello_gleam.aion
aion start hello_gleam --input '{"name":"Ada"}'
```


The scaffold's typed input and output live in the authored I/O module. Edit the typed handler for the workflow's logic. The engine entry decodes a raw JSON string inside a Dynamic, calls the handler and returns an encoded JSON string.

The package descriptor names the entry module, entry function, schemas and output archive. Build the Erlang output with Gleam before packaging it.

## Change a boundary type

After editing the I/O types, regenerate the codecs and JSON Schemas. Check mode refuses stale generated files without rewriting them.

**Terminal**

```bash
aion generate .
aion generate . --check
```


## Read the result

Use the workflow id returned by start. Describe reports completion; inspect includes the recorded result. The greeting output is an object with a greeting field.

**Terminal — copy both ids from the start receipt**

```bash
aion describe "$WORKFLOW_ID" --run-id "$RUN_ID" --pretty
aion inspect "$WORKFLOW_ID" --run-id "$RUN_ID" --pretty
aion tail "$WORKFLOW_ID" --run-id "$RUN_ID"
```


## Keep replay deterministic

Do not read a wall clock, environment, filesystem or network from workflow code. Put external effects in activities. Use the SDK's recorded time and deterministic random APIs.

The scaffold templates also include approval, saga and agent examples. Their requirements are listed in the [authoring commands](/aion/reference/cli-authoring/). Read [packages](/aion/reference/packages/) before changing an archive's entry contract.

On main, crates/aion-cli/src/new/template.rs:85–118 selects these scaffold files. The entry and typed greeting come from crates/aion-cli/templates/hello_world/project.gleam and project_io.gleam. The workflow SDK entry contract is gleam/aion_flow/src/aion/workflow.gleam:257–314.