Skip to main content

Step library

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:

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

result = steps.run("join", options = ["api", "worker"], separator = ",")
print(result.value)  # api,worker

Each call executes immediately. Use steps.task to defer a function call, and 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. Unknown step fields and invalid values produce errors.
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.

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:

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)

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 environment used by 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 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 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 and steps.parallel.