Scripting
Add scripts to workflows, custom commands, and hooks using the Atmos Automation Language, based on Starlark.
Use your Atmos stacks, cloud identities, and toolchain to build, deploy, and test. Combine built-in steps with shell commands; add scripts for conditions, loops, and shared functions. Run the same commands locally and in CI.
Choose an entry point
| Build | Use it for |
|---|---|
| A workflow | A sequence of tasks, with parallel execution, retries, and timeouts |
| A custom command | An Atmos subcommand such as atmos capacity |
| A hook | Checks or actions triggered by component, scaffold, or Git events |
| A test suite | Tests for scripts, command results, and deployed services |
| A CLI app | A standalone script with its own arguments, flags, and help |
Script step syntax
Use type: script and interpreter: starlark to add a script to a step list:
- name: report
type: script
interpreter: starlark
script: ui.info("Starting")
Workflows, custom commands, and Git hooks accept step lists. Component and scaffold hooks wrap steps with an event and a hook kind; see hook syntax.
Workflows and parallel tasks
Define a workflow in YAML, then run it with
atmos workflow <name> -f <file>.
Combine Atmos commands, shell commands, scripts, and control steps for parallel work, retries, and timeouts. The workflow guide explains how to define and run a workflow; the step reference describes the building blocks.
Use script steps for conditions, loops, and data processing.
Store shared functions in .star files and include them from YAML; load()
resolves sibling modules relative to the script file.
Inside a program, steps.task describes a function call and steps.parallel
runs independent calls with a concurrency limit. Each task can have its own
timeout and retry policy. Results retain input order, and terminal output identifies
the task that produced it.
The release-plan example loads a shared function and reads three components with at most two tasks running at once.
Use retries for operations that are safe to repeat: a retry runs the entire task function again. See task execution for the available controls and component-resolution deadline behavior.
Steps can collect user input and pass results to later steps. See prompts and step outputs.
Custom commands
Add project-specific subcommands to Atmos in atmos.yaml. Define their
arguments, flags, defaults, help, and steps. Commands can run existing tools or
Starlark scripts; Atmos parses inputs and passes them to the script.
Example: report capacity
Save this configuration as atmos.yaml. The commands: entry registers the
capacity subcommand, its flag, and the script step that implements it:
Run the command through Atmos:
It prints 3 replicas x 4 workers = 12 workers.
Register a subcommand and define its arguments, flags, and steps.
The runnable capacity example includes the complete project. See custom command configuration for command declarations, arguments, flags, and component context.
Select type: script and interpreter: starlark for the program step.
Script steps read parsed flags directly as ctx.flags["replicas"] and named
positional arguments as ctx.arguments["service"]. Values keep their declared
types.
Use error builders to report failures with explanations and recovery hints.
Lifecycle hooks
Hooks run actions when an event occurs. Use them around component operations,
scaffold generation, or Git events such as pre-commit. Component and scaffold
hooks select lifecycle events; Git hooks are configured separately in atmos.yaml.
Component hooks receive ctx.component, ctx.hook, and ctx.operation.
Scaffold hooks receive template inputs; Git hooks receive Git arguments.
See hook syntax and inputs before adding a hook.
Example: check component ownership
This example requires an owner before Terraform plans. The dev stack passes;
the unowned stack fails the check and never starts a plan. Its tiny Terraform
module has no providers or resources, so you can try it without cloud credentials.
Run scripts at component, scaffold, or Git events.
The runnable ownership example shows both outcomes. See hooks for events, failure policies, and configuration, and lifecycle context for the fields available to scripts.
Testing your automation
Use test steps to check script logic, command results, configuration, and
deployed services. In scripts, call fail() with a useful message when a check fails.
Group checks with the test step type to get a test tree and a summary of passed,
failed, skipped, and canceled checks. Successful output stays hidden by default;
failing checks show their captured output and error. Combine script checks with
HTTP checks, shell commands, and other supported step types. Use parallel or
matrix groups when checks can run independently.
Test groups work in workflows, custom commands, and lifecycle hooks.
Group assertions, command checks, and service tests.
Custom CLI apps
A CLI app is an executable with its own arguments, flags, and help. Run it as
./myapp; no extension or command registration in atmos.yaml is required.
With Atmos on your PATH, save this as myapp. The first line selects Atmos
as its interpreter. This example needs no stacks or external tools.
It prints Hello, platform!. You can also use atmos ./myapp platform,
including on systems without shebang support.
The following script uses the built-in fs and json helpers to read a service
manifest and report replica totals.
Declare arguments, flags, validation, and help.
The runnable script example includes the service manifest and executable programs.
The release example builds a container image, pushes it to a registry, and deploys it with Terraform.
Declare script arguments and flags
Declare arguments, flags, and help with cli.command, cli.arg, and cli.flag.
Atmos parses and validates inputs before calling main(args, flags).
#!/usr/bin/env atmos
def validate(args, flags):
if flags["replicas"] < 1:
fail("replicas must be positive")
def main(args, flags):
print("{}: {} replicas".format(args["service"], flags["replicas"]))
cli.command(
description = "Report a service's replica count",
args = [cli.arg("service", description="Service name")],
flags = [cli.flag("replicas", type="int", shorthand="r", default=2)],
validate = validate,
run = main,
)
Save this as replicas.star. Run atmos ./replicas.star api -r 3 (or --replicas 3),
or atmos ./replicas.star --help for generated usage. Help does not run main.
Flags support types, defaults, required values,
and choices; an optional validate callback handles checks involving multiple
inputs. Both callbacks receive parsed dictionaries directly.
See the command declaration reference and complete example.
Language overview
Atmos includes a Starlark interpreter with Python-like functions, conditions, loops, and structured data.
Write .star files for standalone tools and shared code, or select
interpreter: starlark in a YAML script step. Use load() to share functions
between tools, custom commands, workflows, and hooks.
Why Starlark?
Read why Atmos uses Starlark.
Use the same automation locally and in CI
Commit your automation to the repository and run the same command locally and in CI. Atmos supplies the interpreter; external commands still need their tools and credentials.
Keep triggers and approvals in your CI system. Add native CI for Terraform plan reporting, status checks, and planfile storage.
Built-in helpers and reference
Atmos adds helpers for files, JSON, regular expressions, processes,
component lookup, command invocation, task execution, and terminal output.
print emits data; ui reports status; log emits diagnostics at the configured
log level. Output streams while scripts run. When masking is enabled, registered secrets
and matches for configured masking patterns are masked in displayed output.
Browse syntax, helpers, execution controls, path resolution, and runtime limits.
