# Step library import Intro from '@site/src/components/Intro' Call Atmos steps directly from the Atmos Automation Language. Collect input, build containers, make HTTP requests, package files, and format output with the same handlers used by YAML workflows, custom commands, and hooks. ## Usage Call a step by its type, using its documented fields as keyword arguments: ```python service = steps.input(prompt = "Service name?", default = "api").value selection = steps.choose(prompt = "Environment?", options = ["dev", "prod"], default = "dev").value ui.info("Selected " + service + " in " + selection) ``` For a type selected at runtime, use `steps.run(type, **fields)`: ```python result = steps.run("join", options = ["api", "worker"], separator = ",") print(result.value) # api,worker ``` Each call executes immediately. Use [`steps.task`](/functions/automation/steps.task) to defer a function call, and [`steps.parallel`](/functions/automation/steps.parallel) to run functions concurrently. ## Arguments

`type`: The registered step type, passed as the first positional argument to `steps.run`. A named function such as `steps.http` selects its type for you and accepts only keyword arguments.
`**fields`: The fields from the corresponding step reference, with the same types and defaults as YAML. Use dictionaries for nested blocks. Invalid values produce errors. See Field validation for the accepted field names.
`with_`, `for_`, `continue_`: Spellings for fields that conflict with language keywords. For example, pass a container's YAML `with:` block as `with_ = {"image": "..."}`. Dictionary expansion also accepts the original spelling, such as `**{"with": settings}`.

Hyphens in type names become underscores in function names: `wait-all` is `steps.wait_all`. The existing `steps.parallel` function continues to run AAL functions. To execute a YAML-style parallel group, use `steps.run("parallel", steps = [...])` with child step dictionaries. ## Field validation {#field-validation} Each step type accepts the common fields (`name`, `type`, `output`, `show`, `env`, `working_directory`, `timeout`, `retry`, `outputs`, and `with`) plus the fields of its own reference page. A field outside that set is an error that lists what the type accepts: ```text unknown field "seperator" for step type "join"; valid fields: ... ``` A step type that does not declare its own field list is checked against the fields of any step type and reports `unknown step field "x"` instead. The same check applies to the child steps of a YAML-style `steps.run("parallel", steps = [...])` group. ## Output modes The `output` field of a step call chooses how the step shows what it produced: `raw`, `log`, `viewport`, or `none`. The values `capture` and `stream` belong to [`exec.run`](/functions/automation/exec.run#arguments) and the `atmos.*` wrappers, not to step calls. A step call that passes either one fails, and the error points to [`exec.run`](/functions/automation/exec.run), whose `output = "capture"` captures a command's output. Every step result already carries its output in `value`. ## Timeouts A step call honors `timeout:`. An overrun reads `step timed out` and names the step and its type, for example `Step 'build' (type shell) did not finish within its timeout of 30s`. The `sleep` step uses `timeout` as its duration, and the `http` step uses it for each request, so neither is bounded again as a whole. A script's own `timeout` bounds the entire script step. ## Results A call returns an immutable result with these attributes:

`data`: The JSON decoded from `value` on first access, with read-only lists and dictionaries. For example, an HTTP step can return a JSON response body. The original `value` remains available. Empty or invalid JSON raises only when you access `data`.
`value`: The step's primary result as a string. For example, input text, an HTTP response body, or an archive path. A confirmation returns `"true"` or `"false"`; compare the value explicitly.
`values`: A list of strings for handlers that return multiple selections; otherwise an empty list.
`metadata`: A dictionary of handler-specific details. For example, HTTP steps return `status_code` and command steps return `stdout`, `stderr`, and `exit_code`. See the individual step reference.
`outputs`: A dictionary of named strings evaluated from the step's `outputs` declarations.
`skipped`, `error`: The handler's skipped flag and diagnostic string. Execution failures raise an error and stop the script rather than returning a successful result.

Metadata, selections, and named outputs already have their documented dictionary or list types; `data` decodes only the primary `value`. Use `json.decode(result.value)` when you need a mutable copy. Serializing a whole result preserves its original fields without accessing `data`. ### Pass results between calls Use ordinary variables to pass results to the next operation. Named steps also publish their results to subsequent step templates in the same script thread: ```yaml steps: - name: report type: script interpreter: starlark script: !literal | joined = steps.join( name = "services", options = ["api", "worker"], separator = ",", outputs = {"names": "{{ .value }}"}, ) print(joined.outputs["names"]) summary = steps.join(content = "Services: {{ .steps.services.outputs.names }}") print(summary.value) ``` Atmos renders Go templates in `script:` before the interpreter runs, so a `{{ .value }}` meant for the step library must be protected with [`!literal`](/functions/yaml/literal). Without it, Atmos renders the template first and the expression no longer reaches the script. Omitting `name` uses the step type as its name; another call with that name replaces its stored result. Assign the script's top-level `output` to publish a value to an enclosing workflow or command. ## Execution context Calls inherit the script's working directory, child-process environment, and installed tool paths. A relative `working_directory` resolves against the script's working directory. They use the current Atmos configuration and component resolvers supplied by the enclosing command, workflow, or hook. Step state belongs to the script invocation. Calls to `steps.env` update the templates and child processes of later **step-library calls**, not the script's immutable `env` dictionary or the environment used by `exec.run` and `atmos.*`. Use their `env` argument when those calls need an override. Step state does not modify the enclosing YAML runner's variables. Each parallel task inherits a snapshot of its parent's step state. Its changes stay in that task, including during nested parallel work. A task retry starts with a fresh snapshot. Return values from tasks to share results with the parent. ### Prompts and terminal ownership Prompts retain the existing step behavior: they use a terminal when available, fall back to a configured default without a terminal, or report that a terminal is required. Prompts, terminal sessions, casts, line clearing, process replacement, and viewport output cannot run in parallel script tasks. Collect input before starting parallel work. Command output uses the script's streams and task prefixes. With script-owned streams, command output modes stream through those writers; `output = "none"` suppresses display while preserving captured results. The handlers' terminal interaction and cast recording retain their own terminal requirements. ### Workflow-only features A function call does not create a workflow job. Put `needs`, `when`, `continue`, `identity`, asynchronous `background`, and freshness policies (`inputs`, `artifacts`, `preconditions`) on enclosing YAML steps. Supplying them to a direct call is an error. Use language conditionals and function calls for script control flow, and [`steps.parallel`](/functions/automation/steps.parallel) for concurrent work. The `wait`, `wait-all`, and `cancel` handlers require the workflow runner's background-job context. Calling them directly from AAL reports that requirement. A non-container step's container override also belongs on the enclosing YAML step; use `steps.container` for explicit container operations. The `matrix`, `test`, and YAML-style `parallel` handlers use their existing runners and child-type restrictions. The `exec` step replaces the Atmos process on Unix; use [`exec.run`](/functions/automation/exec.run) when the script should continue after the command finishes. ## Available step functions The module reflects the registered step library. Each entry links to the fields, prerequisites, and result details shared with YAML steps.

`steps.alert`: Ring the terminal bell and optionally print a message. See the alert step reference.
`steps.archive`: Create or extract an archive. See the archive step reference.
`steps.atmos`: Run an Atmos command through the step handler. See the atmos step reference.
`steps.cancel`: Cancel named background jobs; requires workflow background-job context. See the cancel step reference.
`steps.cast`: Record a terminal session or a sequence of steps. See the cast step reference.
`steps.choose`: Prompt for a choice from a list. See the choose step reference.
`steps.clear`: Clear the current terminal line. See the clear step reference.
`steps.confirm`: Prompt for confirmation and return the string "true" or "false". See the confirm step reference.
`steps.container`: Build, run, push, or inspect containers using an action and a with_ dictionary. See the container step reference.
`steps.emulator`: Manage an emulator component. See the emulator step reference.
`steps.env`: Set variables for subsequent step-library calls in this thread. See the env step reference.
`steps.exec`: Replace the Atmos process with a command. See the exec step reference.
`steps.exit`: Stop execution with an exit code. See the exit step reference.
`steps.file`: Prompt for a file path. See the file step reference.
`steps.filter`: Select items using a searchable list. See the filter step reference.
`steps.format`: Format structured content. See the format step reference.
`steps.hint`: Display a hint. See the hint step reference.
`steps.http`: Make an HTTP request; steps.webhook is an alias. See the http step reference.
`steps.input`: Prompt for a line of text. See the input step reference.
`steps.join`: Combine strings and return the result. See the join step reference.
`steps.junit`: Summarize JUnit XML reports. See the junit step reference.
`steps.linebreak`: Print blank lines. See the linebreak step reference.
`steps.log`: Emit a structured log message. See the log step reference.
`steps.markdown`: Render Markdown content. See the markdown step reference.
`steps.matrix`: Run child step dictionaries over a matrix. See the matrix step reference.
`steps.pager`: Display content in a pager. See the pager step reference.
`steps.require`: Check preconditions. The alias assert is available through steps.run("assert", **fields). See the require step reference.
`steps.say`: Speak a message using an available voice. See the say step reference.
`steps.script`: Run a nested script with an explicit interpreter. See the script step reference.
`steps.shell`: Run a shell command. See the shell step reference.
`steps.sleep`: Pause for a duration, honoring cancellation. See the sleep step reference.
`steps.spin`: Display a spinner while a command runs. See the spin step reference.
`steps.stage`: Display a stage marker. See the stage step reference.
`steps.store`: Write a value to a configured store. See the store step reference.
`steps.style`: Apply terminal styling to content. See the style step reference.
`steps.table`: Render tabular data. See the table step reference.
`steps.test`: Run a group of check steps. See the test step reference.
`steps.tflint`: Run TFLint against a Terraform component. See the tflint step reference.
`steps.title`: Display a title. See the title step reference.
`steps.toast`: Display a notification. See the toast step reference.
`steps.wait`: Wait for named background jobs; requires workflow background-job context. See the wait step reference.
`steps.wait_all`: Wait for all background jobs; requires workflow background-job context. See the wait-all step reference.
`steps.workdir`: Provision a working directory from a source. See the workdir step reference.
`steps.write`: Prompt for multiline input. See the write step reference.

For function-based concurrency, see [`steps.task`](/functions/automation/steps.task) and [`steps.parallel`](/functions/automation/steps.parallel).