Atmos Automation Functions
Automation functions are the helpers Atmos supplies to scripts written in the Atmos Automation Language. Use them to declare a program's command line, run Atmos and external commands, resolve component configuration, install tool dependencies, use configured identities, run work in parallel, and give users formatted progress and actionable errors.
Automation functions run when a script executes: in a standalone program, a custom command, a workflow step, or a lifecycle hook. They are separate from YAML functions and template functions, which Atmos evaluates while it loads stack manifests.
Every function and value on these pages is available without an import. Atmos
predeclares the names cli, atmos, components, exec, steps, fs, json,
regex, dependencies, ui, log, errors, env, and ctx, and the script's top-level
output variable sets its result. The language itself, including statements,
operators, and the universal built-ins, is described in the
language reference.
Function categories
| Category | Functions |
|---|---|
| Command line | cli.command, cli.arg, cli.flag |
| Atmos commands | atmos.run, atmos.terraform, atmos.helm, atmos.toolchain, and one wrapper for each built-in command |
| Components | components.get, component.exec |
| Processes | exec.run, dependencies.tools |
| Concurrency | steps.task, steps.parallel |
| Files and data | fs.read_file, json.encode, json.decode, json.indent, json.encode_indent |
| Text | regex.search, regex.findall, regex.replace |
| Messages | ui.info, ui.success, ui.warning, log.trace, log.debug, log.info, log.warn, log.error, print |
| Errors | errors.build |
| Built-in values | ctx, env, output, load |
Step library
Call steps.input, steps.http, steps.container, and the other step functions
with the same fields used in YAML. Each call returns a value, metadata, and named
outputs. Use steps.run(type, **fields) when the step type is selected at runtime.
Atmos command wrappers
Use a command wrapper such as atmos.vendor("pull") to run the matching Atmos
command. See atmos.run for
shared signatures, flag translation, process options, and results.
The built-in commands each have a reference page: about, ai, ansible, atlantis, auth, aws, azure, cast, ci, completion, composition, config, container, describe, devcontainer, docs, emulator, env, gcp, git, helmfile, help, init, kubernetes, list, lsp, mcp, packer, pro, profile, sbom, scaffold, secret, stack, store, support, theme, validate, vendor, version, workflow.
The module reflects the commands registered in the running Atmos, so it also includes the aliases of those commands
(an, c, emu, hf, k8s, pk, and tf) and every custom command defined in atmos.yaml. A custom command named
capacity is callable as atmos.capacity(...). A command name that contains a hyphen cannot be written as an attribute,
so call it with atmos.run, for example atmos.run(["my-command"]).
All automation functions
Run atmos about from a script to print the Atmos overview.
Run an atmos ai command, such as ask or exec, from a script.
Run an atmos ansible command, such as playbook or version, from a script.
Run an atmos atlantis command, such as generate repo-config, from a script.
Run an atmos auth command, such as login, env, or exec, from a script.
Run an atmos aws command, such as eks update-kubeconfig or ecr login, from a script.
Run an atmos azure command, such as aks update-kubeconfig or acr login, from a script.
Run an atmos cast command, such as play or render, from a script.
Run an atmos ci command, such as status, validate, or cache, from a script.
Run atmos completion from a script to generate a shell completion script.
Run an atmos composition command, such as list, validate, or up, from a script.
Run an atmos config command, such as get, set, or validate, from a script.
Run an atmos container command, such as build, up, or exec, from a script.
Run an atmos describe command, such as component, stacks, or affected, from a script.
Run an atmos devcontainer command, such as start, exec, or stop, from a script.
Run an atmos docs command, such as generate, from a script.
Run an atmos emulator command, such as up, down, or exec, from a script.
Run atmos env from a script to read the environment variables configured in atmos.yaml.
Run an atmos gcp command, such as gke token, from a script.
Run an atmos git command, such as clone, status, or commit, from a script.
Run an Atmos Helm command for a component and stack from a script.
Run an atmos helmfile command, such as diff or apply, from a script.
Run atmos help from a script to capture the help text of a command.
Run atmos init from a script to scaffold a new Atmos project from a template.
Run an atmos kubernetes command, such as render, diff, or apply, from a script.
Run an atmos list command, such as stacks or components, from a script.
Run atmos lsp start from a script to launch the Atmos Language Server.
Run an atmos mcp command, such as list, test, or tools, from a script.
Run an atmos packer command, such as init or build, from a script.
Run an atmos pro command, such as lock, unlock, or commit, from a script.
Run an atmos profile command, such as list or show, from a script.
Run any Atmos command, including custom commands, from a script.
Run an atmos sbom command, such as generate, from a script.
Run an atmos scaffold command, such as generate or list, from a script.
Run an atmos secret command, such as list, get, set, or validate, from a script.
Run an atmos stack command, such as get, set, or validate, from a script.
Run an atmos store command, such as get, set, delete, or list, from a script.
Run the atmos support command from a script.
Run an Atmos Terraform or OpenTofu command for a component and stack from a script.
Run an atmos theme command, such as list or show, from a script.
Run an Atmos toolchain command, such as install or which, from a script.
Run an atmos validate command, such as stacks, component, or schema, from a script.
Run an atmos vendor command, such as pull or verify, from a script.
Run an atmos version command, such as list, show, or track, from a script.
Run an atmos workflow, or list workflows, from a script.
Declare a positional argument for a standalone program.
Declare a standalone program's command line, validate its inputs, and call its entry function.
Declare a typed flag for a standalone program.
Run a program in a component's directory with the component's environment.
Resolve a component's configuration for a stack and return a read-only component handle.
The read-only context a script receives about how and where it runs.
The raw command-line arguments passed to a standalone script.
The parsed named arguments of a custom command.
The component a custom command or lifecycle hook is scoped to.
The parsed flags of a custom command, or the flags a workflow supplies.
The name and event of the lifecycle hook that runs the script.
The parent operation a lifecycle hook is attached to, and its outcome.
The path and directory of the script file that is running.
Install a pinned tool through the Atmos toolchain and add it to the script's PATH.
Read the environment values declared for the step.
Build actionable errors with Atmos's standard titles, explanations, hints, examples, context, and exit codes.
Run an external program from an argument list and capture its result.
Check whether a filesystem path resolves.
Find files matching a pattern.
Read a local file as a string.
Read the target stored in a symbolic link.
Inspect file types and byte sizes without reading file contents.
Parse a JSON string into dictionaries, lists, and scalar values.
Convert a value to a compact JSON string.
Convert a value to indented, human-readable JSON.
Pretty-print an existing JSON string.
Import functions and values from another Atmos Automation Language file.
Write a debug-level diagnostic message to the Atmos log.
Write an error-level diagnostic message to the Atmos log.
Write an info-level diagnostic message to the Atmos log.
Write a trace-level diagnostic message to the Atmos log.
Write a warning-level diagnostic message to the Atmos log.
Set the result of a script by assigning the top-level output variable.
Write data to the script's standard output.
Return every non-overlapping match of a regular expression.
Replace every match of a regular expression with literal text.
Test whether a regular expression matches anywhere in a string.
Run functions or tasks concurrently with a concurrency limit and collect their results in order.
Call Atmos step handlers from a script and use their values, metadata, and named outputs.
Describe a deferred function call with arguments, a retry policy, and a timeout.
Show a status or progress message to the person running the program.
Show a success message to the person running the program.
Show a warning message to the person running the program.
