Atmos Automation Language

The Atmos Automation Language is based on Starlark, a Python-like language for scripts. Its interpreter and built-in functions ship with Atmos.

Use scripts in workflows, custom commands, lifecycle hooks, scaffold hooks, and Git hooks. Scripts can also run as standalone apps with an Atmos shebang. For complete syntax and data types, see the language reference.

Syntax and values

Write functions, conditions, loops, lists, and dictionaries using familiar Python-like syntax:

def capacity(replicas, workers_per_replica):
    if replicas < 1:
        fail("replicas must be positive")
    return replicas * workers_per_replica

print("Total workers: {}".format(capacity(3, 4)))

This prints Total workers: 12. Use fail(message) to stop a script with an error. Atmos reports the source location and traceback. Use defer(fn) to register cleanup that runs when the script finishes, even after a failure. Use sum() to total numbers and round() to round a result.

The runtime supports top-level conditionals and loops, while, set(), and recursive functions. It does not run arbitrary Python programs or import Python packages. Use the built-in modules below and load() for shared Starlark code.

Module-level names cannot be reassigned. Compute a changing value inside a function or mutate a list or dictionary before dispatching parallel work. Values reachable by parallel tasks become immutable when dispatched. See the detailed language behavior.

Inputs depend on the entry point

Where the program runs	How it receives inputs
Custom Atmos command	ctx.flags and ctx.arguments contain parsed inputs from the command's YAML declarations.
Workflow step	ctx.flags contains available workflow flags. ctx.arguments is empty for YAML workflows, including parallel and matrix children. env contains explicitly declared step inputs.
Component lifecycle hook	ctx.component, ctx.hook, and ctx.operation describe the component and parent operation.
Scaffold hook	Template values such as .Answers and .TargetPath, passed through the script step's env.
Git hook	Git's positional arguments in ctx.args; stdin follows the Git hook's input contract.
Custom CLI app	cli.command calls main(args, flags) with parsed inputs; scripts without it read raw ctx.args.

ctx.flags and ctx.arguments are read-only dictionaries. Use parsed inputs directly instead of interpolating them into script source or mapping each flag to an environment variable.

Why Starlark?

Starlark provides functions, loops, and structured data without a separate Python or Node.js installation. It does not run Python packages. Module globals are assigned once, and values shared with parallel tasks are frozen.

Pure calculations are repeatable; file reads and external commands still depend on their environment. The interpreter is not a sandbox for untrusted scripts. See Starlark's design principles.

Built-in helpers

Helper	Purpose
cli.command, cli.arg, cli.flag	Declare arguments, flags, and help; validate inputs and run the app.
atmos.run, atmos.terraform, atmos.helm, atmos.toolchain, and one wrapper per command, such as atmos.vendor	Invoke registered Atmos commands, including Terraform, Helm, and project commands through atmos.run.
components.get	Resolve component configuration for a named component and stack.
exec.run	Run an external program with an argument list and capture its result.
steps.task, steps.parallel	Describe function calls, execute concurrent work, and apply retries and timeouts.
defer	Register cleanup that runs when the script or task finishes, even after a failure or cancellation.
fs.read_file	Read a local file as text.
json.encode, json.decode	Convert between structured values and JSON text.
regex.search, regex.findall, regex.replace	Match and transform text using regular expressions.
digest.sha256, digest.sha512, digest.sha1, digest.md5	Compute digests of strings and file contents.
exec.which	Find the executable that exec.run would start.
dependencies.tools	Request tools through Atmos's toolchain integration.
ui.info, ui.success, ui.warning	Write status messages for the person running the program.
errors.build	Raise actionable errors with Atmos's explanations, hints, examples, context, and exit codes.
log.trace, log.debug, log.info, log.warn, log.error	Emit diagnostics at the configured Atmos log level.

The automation functions reference documents every helper and built-in value with its signature, arguments, return value, and examples. The script API reference also details call signatures, return values, and failure behavior. The Atmos command reference explains command arguments and flags.

Data, status, and diagnostics

Use print() for data on stdout, ui.info(), ui.success(), and ui.warning() for status on stderr, and log.debug() or other log levels for diagnostics.

Assign the top-level output variable to return a step value. Strings are used as written; other values must be JSON-encodable. Without output, a script step uses captured stdout as its value. Status and diagnostic output do not become the step value.

Output streams while the program runs. When masking is enabled, Atmos masks registered secrets and matches for configured masking patterns in displayed output. Log messages respect the configured log level and can include structured fields. See output and logging.

Use errors.build to give failures the same presentation as Atmos's own errors. Add an explanation, recovery hints, and an example before calling .fail(). These errors follow Atmos's normal reporting path, including Sentry when configured.

Call the step library directly from scripts: steps.input(prompt = "Service?", default = "api").value returns an input value. The same module exposes choice and confirmation prompts, HTTP requests, container operations, archives, and the other registered step handlers. Calls return values, metadata, and named outputs that you can pass to the next operation.

You can also combine YAML prompts and script steps in a workflow or custom command. See prompts and step outputs.

Files and shared code

Use load("helpers.star", "function_name") to load reusable functions. For a program read from a file, module paths resolve relative to that file. For an inline YAML script, they resolve relative to the step's working directory.

fs.read_file and exec.run use the step's working directory. A component's exec method defaults to the component directory. See file resolution for YAML includes, symlinks, and source paths.

Execution controls

Use steps.task to attach arguments, retries, and a timeout to a function call. Use steps.parallel to run a collection of tasks with a concurrency limit. Results retain input order. A retry runs the entire function again, so use it for operations that are safe to repeat.

Workflow dry runs parse embedded script steps without executing their code, starting child processes, or installing tools. The embedded interpreter runs inside Atmos; script steps using interpreter: starlark cannot run inside an enabled container. See workflow integration and execution restrictions.

Test program behavior

Use conditions and fail() to express assertions in the same language as your automation. With exec.run(..., check=False, output="capture"), inspect a command's exit code, stdout, and stderr before deciding whether it met the expectation. A process that cannot start still raises an error.

Put these checks in a test step to collect results and display failures. See testing automation for a runnable suite.

Build with the language

• Custom CLI apps: declare arguments, flags, and help for an executable.
• Custom commands: add project-specific subcommands to Atmos.
• Workflows: combine programs and other step types into a runbook.
• Lifecycle hooks: attach checks and actions to component operations.

Compute stack configuration

Use !starlark in stack manifests to compute typed values from the merged component context. These blocks use return and a read-only ctx object; see the YAML function reference for the available builtins and evaluation order.