Atmos Steps

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).

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
      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 and interpreter: Inline script body and runtime for type: script.
• 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.
• 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.
• tty and interactive: Terminal handoff for commands that need it.

Step Types

Use atmos.tools/workflows/steps/type and its type-specific subpages (e.g. atmos.tools/workflows/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.