Atmos Steps
Atmos steps are the shared execution DSL used by workflows, custom commands,
hooks (kind: step), and cast recordings. When a task involves steps:, step
type, working_directory, env, output, retries, or hook with: payloads,
use this skill together with the surface-specific skill (atmos-workflows,
atmos-custom-commands, or atmos-hooks).
For interpreter: starlark, also load atmos-starlark for the embedded API,
parallel functions, immutable inputs, and module loading.
Core Model
A step is a typed action with native fields. Do not treat steps as a place to
write shell scripts by default. Prefer the Atmos field that expresses the
operation directly:
- Use
working_directory instead of cd for real execution. A type: simulate child of a
mode: steps cast may display cd <directory> to narrate a directory transition, but it
never changes the working directory of later real steps.
- Use
env maps instead of inline FOO=bar command or export.
- Use
output: none instead of redirecting to /dev/null.
- Use
type: script instead of heredoc shell snippets like python3 - <<'PY'.
- Use
type: workdir with source and reset instead of mkdir, rm -rf,
and cp.
- Use
type: atmos for Atmos commands instead of shelling out to atmos ...
when the surface supports typed steps.
- Use Atmos Terraform/OpenTofu
rc configuration instead of hand-managing
temporary .terraformrc or .tofurc files.
Shell is still valid for real shell work, but it should be a conscious fallback
when no native step type or field expresses the intent.
Where Steps Run
Step fields are shared, but defaults differ by surface:
- Workflows default command steps to
type: atmos.
- Custom command string steps historically behave like shell commands; use
structured step objects when you need typed behavior.
- Hooks use an envelope plus
with:. For kind: step, the hook's type
selects the step type, while with: contains the step-specific fields.
- Cast steps can run nested steps and record their terminal output.
Always load the surface-specific skill for invocation rules, path anchoring, and
template context.
Common Fields
Most typed steps can use these fields when the step type supports them:
steps:
- name: validate
type: script
interpreter: python3
working_directory: !repo-root .
env:
ATMOS_LOGS_LEVEL: warn
output: none
retry:
max_attempts: 3
initial_delay: 2s
script: |
print("ok")
Important shared fields:
name: Stable step id for logs, dependencies, outputs, and resume behavior.
type: Registered step handler; the canonical catalog below is the source for authored YAML.
command: Command text for command-running steps.
script, source, and interpreter: Inline script body, or a local script file path (source, mutually exclusive with script), and the runtime for type: script. With source, interpreter is inferred from the extension (.star is starlark, .py is python3, .sh is sh, .bash is bash); an explicit interpreter wins.
working_directory: Directory for the subprocess or script.
env: Map of environment variables layered onto the step.
output: Output mode: raw, log, viewport, or none; test groups instead use failures or all.
retry: Retry policy around the whole step. retry.conditions (regexes, optionally /like this/, matched against stdout, stderr, and error text) is honored by every step type except http; a non-matching failure ends the loop at once, an invalid pattern errors before the step runs, and exit/abort/cancel are never retried.
identity: Atmos identity used when the step runs.
when: Declarative condition for whether the step runs.
needs: Dependency names for concurrent control steps.
timeout: Duration limit for supported steps. Every overrun reads step timed out (Step '<name>' (type <t>) did not finish within its timeout of <d>). sleep and http give timeout: their own meaning (duration, per-request limit).
tty and interactive: Terminal handoff for commands that need it.
Step Types
Use atmos.tools/steps/type and its
type-specific subpages (e.g. atmos.tools/steps/type/shell) as the canonical
reference. Current canonical step types include:
- Command and integration:
atmos, shell, script, exec, container,
emulator, http, archive, require, workdir, cast, store.
- Orchestration:
test, parallel, matrix, wait, wait-all, cancel.
- Interactive:
input, confirm, choose, filter, file, write.
- UI and output:
toast, markdown, spin, table, pager, format,
join, style, log, junit, hint, alert, say, title, clear,
linebreak, stage, sleep, env, exit.
Use webhook only as the http alias and assert only as the require alias;
document and configure the canonical names unless compatibility requires an alias.
If code and docs disagree, inspect the registered step handlers under
pkg/runner/step/ and schema constants in pkg/schema/task.go.
For smoke tests and integration checks, use atmos-tests
for test groups, assertions, parallel dependencies, and matrix cases.
Environment
Prefer map syntax:
env:
PATH: '{{ env "PWD" }}/../../.context/bin:{{ env "PATH" }}'
ATMOS_LOGS_LEVEL: warn
For custom commands, command-level env supports the same map style. Use
template expressions such as {{ env "PATH" }} or .Env where supported. Use
valueCommand only when the value genuinely must come from a command's stdout;
do not move shell string building into valueCommand.
Working Directory
Use working_directory at the narrowest useful scope:
steps:
- name: docs
type: shell
working_directory: !repo-root .
command: npm run docs:build
Do not use --chdir or cd for real workflow, custom-command, or step execution when
working_directory can express the same thing. In a mode: steps cast, a display-only
type: simulate cd <directory> is the exception: use it to keep the recorded story coherent,
and still configure working_directory on every real step. Relative paths must be checked
against the surface's base path rules.
Working-directory resolution is not one rule — it differs by surface, and getting this wrong
silently anchors relative fields (source, destination, path, files, context, ...) to the
wrong directory instead of erroring:
| Surface |
Relative working_directory resolves against |
Custom command's own working_directory: (command- or step-level) |
Atmos base_path — always, whether or not the value starts with ./ |
A workflow's own working_directory: (the workflow-level default), or a type: shell/exec/atmos step's working_directory: |
Atmos base_path — always, whether or not the value starts with ./ |
An extended/registered step type (archive, file, junit, workdir, container, ...) with its own step-level working_directory: |
The current working directory — always, whether or not the value starts with ./ |
kind: step/kind: steps hook |
The component's own working directory for a bare value or when unset; the current working directory for a dot-prefixed value (., .., ./x, ../x) — see atmos-hooks for the full Dot/Bare rule |
A workflow-level working_directory: default still reaches extended step types that leave their
own working_directory: unset — it falls back to the same base_path-anchored resolution the
workflow-level default already gets for shell/exec/atmos steps.
After working_directory is resolved, relative handler fields such as source, destination,
path, files, and context resolve against that directory. For container builds, Dockerfile
resolves relative to the resolved context, not directly to working_directory.
Output
Use output modes instead of pipe redirection:
steps:
- name: prepare
type: atmos
command: terraform generate varfile vpc -s dev
output: none
output: none is for quiet setup. raw preserves command output, log routes
through Atmos logging, and viewport is for richer terminal display.
Script Steps
Use type: script for inline scripts:
steps:
- name: validate-cast
type: script
interpreter: python3
script: |
from pathlib import Path
text = Path("path/to/your.cast").read_text()
if "All proofs passed" not in text:
raise SystemExit("cast validation failed")
Do not put command on a script step. The schema requires interpreter and
script, or source (a local script file) in place of script. Atmos infers interpreter
from the source extension when it is omitted, reads the file when the step runs, and uses it
as written, without rendering it as a template. Remote sources are not supported.
With interpreter: starlark, the script runs inside Atmos (no external interpreter) and
can call Atmos commands directly. Load atmos-starlark for the API. Step-specific rules:
- Atmos renders valid
{{ ... }} template actions in the script body (inline or !included)
before running it. Malformed or unresolved actions can fail; a lone }} is ordinary text.
Read inputs from ctx.flags, ctx.arguments, and env instead of templating values into source.
Use script: !literal | or !include.raw to run the body as written;
!literal also works on command, interpreter, working_directory, timeout, and single env values, and
fails config load on any other step field.
- Script steps default to raw output with no
[step] or completed labels, like shell
steps. Set show: {labels: true} to restore labels. Valid output: modes are raw,
log, viewport, and none; capture and stream are not modes (the error points to exec.run, whose
output is stream|capture|viewport, as for component.exec and atmos.*).
timeout: on a script, shell, or atmos step is enforced: the step is canceled and fails with
step timed out. To time an individual task, run
steps.parallel(tasks=[steps.task(name="work", function=work, timeout="30s")]). The timeout covers
work, not the surrounding script.
steps.<type>(...) in a script accepts the common fields (name, type, output, show, env, working_directory, timeout, retry, outputs, with) plus the type's own; others fail with unknown field "x" for step type "t"; valid fields: ....
- Shell and atmos steps (and every shell-runner caller: custom commands, workflows,
!exec, hook commands) end the
whole process tree on timeout or cancel; a child on a terminal stdin stays in the foreground group and only it is
signalled; Windows kills only the direct child. Shell steps print no "Total for this invocation" metrics line.
type: env / steps.env changes reach later child processes and templates, not the Starlark env global.
- Git hook shell steps get hook arguments as
"$@" and ATMOS_GIT_HOOK_ARGS; hooks that receive stdin also set
ATMOS_GIT_HOOK_STDIN (temp-file path) and the first shell step reads the data on stdin. A prompt step without
default: fails in a non-TTY hook with a hint to set default:.
- Only the values declared under a step's
env: are rendered as templates. The ambient process
environment reaches the step's processes verbatim.
- An enabled
container fails validation for embedded Starlark; set container: false.
Workdir Steps
Use type: workdir for repeatable scratch directories:
steps:
- name: stage-fixtures
type: workdir
path: .context/casts/demo
source: demo/casts/fixtures
reset: true
This replaces shell sequences that create, delete, and copy directories.
Hooks
For hooks, the hook envelope controls lifecycle behavior and with: is the
step payload. A scaffold template may use this bridge too, but only with
kind: step or kind: steps and its two generation events:
hooks:
notify:
kind: step
type: http
events: [after.terraform.apply]
on_failure: warn
retry:
max_attempts: 3
with:
url: https://example.com/hook
method: POST
Use atmos-hooks for hook events, outcome conditions, on_failure, and
preflight behavior.
Verification
When changing step YAML, verify the user-facing command from the directory where
users actually run Atmos. Prefer working_directory fields in YAML and command
tool workdir settings in tests over shell cd or --chdir.
1---2name: atmos-steps3description: "Shared Atmos step DSL for workflows, custom commands, hooks, and cast recordings: step types, env, output, working_directory, retry, and native alternatives to shell glue"4metadata:5 source: https://skillmd.com/skills/cloudposse/atmos-steps6 copyright: Copyright Cloud Posse, LLC 20267 version: "1.0.0"8 category: ci-automation9---1011# Atmos Steps1213Atmos steps are the shared execution DSL used by workflows, custom commands,14hooks (`kind: step`), and cast recordings. When a task involves `steps:`, step15`type`, `working_directory`, `env`, `output`, retries, or hook `with:` payloads,16use this skill together with the surface-specific skill (`atmos-workflows`,17`atmos-custom-commands`, or `atmos-hooks`).1819For `interpreter: starlark`, also load `atmos-starlark` for the embedded API,20parallel functions, immutable inputs, and module loading.2122## Core Model2324A step is a typed action with native fields. Do not treat steps as a place to25write shell scripts by default. Prefer the Atmos field that expresses the26operation directly:2728- Use `working_directory` instead of `cd` for real execution. A `type: simulate` child of a29 `mode: steps` cast may display `cd <directory>` to narrate a directory transition, but it30 never changes the working directory of later real steps.31- Use `env` maps instead of inline `FOO=bar command` or `export`.32- Use `output: none` instead of redirecting to `/dev/null`.33- Use `type: script` instead of heredoc shell snippets like `python3 - <<'PY'`.34- Use `type: workdir` with `source` and `reset` instead of `mkdir`, `rm -rf`,35 and `cp`.36- Use `type: atmos` for Atmos commands instead of shelling out to `atmos ...`37 when the surface supports typed steps.38- Use Atmos Terraform/OpenTofu `rc` configuration instead of hand-managing39 temporary `.terraformrc` or `.tofurc` files.4041Shell is still valid for real shell work, but it should be a conscious fallback42when no native step type or field expresses the intent.4344## Where Steps Run4546Step fields are shared, but defaults differ by surface:4748- Workflows default command steps to `type: atmos`.49- Custom command string steps historically behave like shell commands; use50 structured step objects when you need typed behavior.51- Hooks use an envelope plus `with:`. For `kind: step`, the hook's `type`52 selects the step type, while `with:` contains the step-specific fields.53- Cast steps can run nested steps and record their terminal output.5455Always load the surface-specific skill for invocation rules, path anchoring, and56template context.5758## Common Fields5960Most typed steps can use these fields when the step type supports them:6162```yaml63steps:64 - name: validate65 type: script66 interpreter: python367 working_directory: !repo-root .68 env:69 ATMOS_LOGS_LEVEL: warn70 output: none71 retry:72 max_attempts: 373 initial_delay: 2s74 script: |75 print("ok")76```7778Important shared fields:7980- `name`: Stable step id for logs, dependencies, outputs, and resume behavior.81- `type`: Registered step handler; the canonical catalog below is the source for authored YAML.82- `command`: Command text for command-running steps.83- `script`, `source`, and `interpreter`: Inline script body, or a local script file path (`source`, mutually exclusive with `script`), and the runtime for `type: script`. With `source`, `interpreter` is inferred from the extension (`.star` is `starlark`, `.py` is `python3`, `.sh` is `sh`, `.bash` is `bash`); an explicit `interpreter` wins.84- `working_directory`: Directory for the subprocess or script.85- `env`: Map of environment variables layered onto the step.86- `output`: Output mode: `raw`, `log`, `viewport`, or `none`; `test` groups instead use `failures` or `all`.87- `retry`: Retry policy around the whole step. `retry.conditions` (regexes, optionally `/like this/`, matched against stdout, stderr, and error text) is honored by every step type except `http`; a non-matching failure ends the loop at once, an invalid pattern errors before the step runs, and exit/abort/cancel are never retried.88- `identity`: Atmos identity used when the step runs.89- `when`: Declarative condition for whether the step runs.90- `needs`: Dependency names for concurrent control steps.91- `timeout`: Duration limit for supported steps. Every overrun reads `step timed out` (`Step '<name>' (type <t>) did not finish within its timeout of <d>`). `sleep` and `http` give `timeout:` their own meaning (duration, per-request limit).92- `tty` and `interactive`: Terminal handoff for commands that need it.9394## Step Types9596Use [atmos.tools/steps/type](https://atmos.tools/steps/type) and its97type-specific subpages (e.g. `atmos.tools/steps/type/shell`) as the canonical98reference. Current canonical step types include:99100- Command and integration: `atmos`, `shell`, `script`, `exec`, `container`,101 `emulator`, `http`, `archive`, `require`, `workdir`, `cast`, `store`.102- Orchestration: `test`, `parallel`, `matrix`, `wait`, `wait-all`, `cancel`.103- Interactive: `input`, `confirm`, `choose`, `filter`, `file`, `write`.104- UI and output: `toast`, `markdown`, `spin`, `table`, `pager`, `format`,105 `join`, `style`, `log`, `junit`, `hint`, `alert`, `say`, `title`, `clear`,106 `linebreak`, `stage`, `sleep`, `env`, `exit`.107108Use `webhook` only as the `http` alias and `assert` only as the `require` alias;109document and configure the canonical names unless compatibility requires an alias.110111If code and docs disagree, inspect the registered step handlers under112`pkg/runner/step/` and schema constants in `pkg/schema/task.go`.113114For smoke tests and integration checks, use [atmos-tests](../atmos-tests/SKILL.md)115for test groups, assertions, parallel dependencies, and matrix cases.116117## Environment118119Prefer map syntax:120121```yaml122env:123 PATH: '{{ env "PWD" }}/../../.context/bin:{{ env "PATH" }}'124 ATMOS_LOGS_LEVEL: warn125```126127For custom commands, command-level `env` supports the same map style. Use128template expressions such as `{{ env "PATH" }}` or `.Env` where supported. Use129`valueCommand` only when the value genuinely must come from a command's stdout;130do not move shell string building into `valueCommand`.131132## Working Directory133134Use `working_directory` at the narrowest useful scope:135136```yaml137steps:138 - name: docs139 type: shell140 working_directory: !repo-root .141 command: npm run docs:build142```143144Do not use `--chdir` or `cd` for real workflow, custom-command, or step execution when145`working_directory` can express the same thing. In a `mode: steps` cast, a display-only146`type: simulate` `cd <directory>` is the exception: use it to keep the recorded story coherent,147and still configure `working_directory` on every real step. Relative paths must be checked148against the surface's base path rules.149150Working-directory resolution is not one rule — it differs by surface, and getting this wrong151silently anchors relative fields (`source`, `destination`, `path`, `files`, `context`, ...) to the152wrong directory instead of erroring:153154| Surface | Relative `working_directory` resolves against |155|---|---|156| Custom command's own `working_directory:` (command- or step-level) | Atmos `base_path` — always, whether or not the value starts with `./` |157| A workflow's own `working_directory:` (the workflow-level default), or a `type: shell`/`exec`/`atmos` step's `working_directory:` | Atmos `base_path` — always, whether or not the value starts with `./` |158| An extended/registered step type (`archive`, `file`, `junit`, `workdir`, `container`, ...) with its own step-level `working_directory:` | The current working directory — always, whether or not the value starts with `./` |159| `kind: step`/`kind: steps` hook | The component's own working directory for a bare value or when unset; the current working directory for a dot-prefixed value (`.`, `..`, `./x`, `../x`) — see `atmos-hooks` for the full Dot/Bare rule |160161A workflow-level `working_directory:` default still reaches extended step types that leave their162own `working_directory:` unset — it falls back to the same `base_path`-anchored resolution the163workflow-level default already gets for shell/exec/atmos steps.164165After `working_directory` is resolved, relative handler fields such as `source`, `destination`,166`path`, `files`, and `context` resolve against that directory. For container builds, `Dockerfile`167resolves relative to the resolved `context`, not directly to `working_directory`.168169## Output170171Use output modes instead of pipe redirection:172173```yaml174steps:175 - name: prepare176 type: atmos177 command: terraform generate varfile vpc -s dev178 output: none179```180181`output: none` is for quiet setup. `raw` preserves command output, `log` routes182through Atmos logging, and `viewport` is for richer terminal display.183184## Script Steps185186Use `type: script` for inline scripts:187188```yaml189steps:190 - name: validate-cast191 type: script192 interpreter: python3193 script: |194 from pathlib import Path195196 text = Path("path/to/your.cast").read_text()197 if "All proofs passed" not in text:198 raise SystemExit("cast validation failed")199```200201Do not put `command` on a `script` step. The schema requires `interpreter` and202`script`, or `source` (a local script file) in place of `script`. Atmos infers `interpreter`203from the `source` extension when it is omitted, reads the file when the step runs, and uses it204as written, without rendering it as a template. Remote sources are not supported.205206With `interpreter: starlark`, the script runs inside Atmos (no external interpreter) and207can call Atmos commands directly. Load `atmos-starlark` for the API. Step-specific rules:208209- Atmos renders valid `{{ ... }}` template actions in the `script` body (inline or `!include`d)210 before running it. Malformed or unresolved actions can fail; a lone `}}` is ordinary text.211 Read inputs from `ctx.flags`, `ctx.arguments`, and `env` instead of templating values into source.212 Use `script: !literal |` or `!include.raw` to run the body as written;213 `!literal` also works on `command`, `interpreter`, `working_directory`, `timeout`, and single `env` values, and214 fails config load on any other step field.215- Script steps default to raw output with no `[step]` or `completed` labels, like shell216 steps. Set `show: {labels: true}` to restore labels. Valid `output:` modes are `raw`,217 `log`, `viewport`, and `none`; `capture` and `stream` are not modes (the error points to `exec.run`, whose218 `output` is `stream|capture|viewport`, as for `component.exec` and `atmos.*`).219- `timeout:` on a script, shell, or atmos step is enforced: the step is canceled and fails with220 `step timed out`. To time an individual task, run221 `steps.parallel(tasks=[steps.task(name="work", function=work, timeout="30s")])`. The timeout covers222 `work`, not the surrounding script.223- `steps.<type>(...)` in a script accepts the common fields (`name, type, output, show, env, working_directory,224 timeout, retry, outputs, with`) plus the type's own; others fail with `unknown field "x" for step type "t"; valid fields: ...`.225- Shell and atmos steps (and every shell-runner caller: custom commands, workflows, `!exec`, hook commands) end the226 whole process tree on timeout or cancel; a child on a terminal stdin stays in the foreground group and only it is227 signalled; Windows kills only the direct child. Shell steps print no "Total for this invocation" metrics line.228- `type: env` / `steps.env` changes reach later child processes and templates, not the Starlark `env` global.229- Git hook shell steps get hook arguments as `"$@"` and `ATMOS_GIT_HOOK_ARGS`; hooks that receive stdin also set230 `ATMOS_GIT_HOOK_STDIN` (temp-file path) and the first shell step reads the data on stdin. A prompt step without231 `default:` fails in a non-TTY hook with a hint to set `default:`.232- Only the values declared under a step's `env:` are rendered as templates. The ambient process233 environment reaches the step's processes verbatim.234- An enabled `container` fails validation for embedded Starlark; set `container: false`.235236## Workdir Steps237238Use `type: workdir` for repeatable scratch directories:239240```yaml241steps:242 - name: stage-fixtures243 type: workdir244 path: .context/casts/demo245 source: demo/casts/fixtures246 reset: true247```248249This replaces shell sequences that create, delete, and copy directories.250251## Hooks252253For hooks, the hook envelope controls lifecycle behavior and `with:` is the254step payload. A scaffold template may use this bridge too, but only with255`kind: step` or `kind: steps` and its two generation events:256257```yaml258hooks:259 notify:260 kind: step261 type: http262 events: [after.terraform.apply]263 on_failure: warn264 retry:265 max_attempts: 3266 with:267 url: https://example.com/hook268 method: POST269```270271Use `atmos-hooks` for hook events, outcome conditions, `on_failure`, and272preflight behavior.273274## Verification275276When changing step YAML, verify the user-facing command from the directory where277users actually run Atmos. Prefer `working_directory` fields in YAML and command278tool `workdir` settings in tests over shell `cd` or `--chdir`.