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

```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.
  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:

```python
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`](/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).