Introducing Atmos Automation Language
Build, ship, and deploy containers the same way locally and in CI. The Atmos Automation Language is a Python-like DSL based on Starlark for writing that process as reusable, testable code. Compose image builds, registry pushes, deployments, and checks using your existing Atmos stacks, identities, and toolchain.
Install pinned tool dependencies, assume configured identities, call Atmos commands and external tools, and parallelize work with retries and timeouts. Combine scripts with native prompt steps, pass structured results between steps, and give users Atmos's formatted output and actionable errors.
Keep the release logic in your project and have developers and CI invoke the same command. Atmos supplies structured data, command execution, parallel tasks, and test steps, reducing the shell plumbing you maintain as Bash scripts grow.
For standalone .star apps with their own arguments and help, see the
Atmos interpreter announcement.
Keep your release process in one place
Release logic often ends up spread across Bash scripts and CI configuration. Changing it means following environment variables, parsing command output, and reproducing failures from pipeline logs. With Atmos, you can put that logic in functions, pass structured values between them, and test their behavior locally. CI invokes the process you already use during development.
Use custom commands for your team's entry points, workflows to compose the process, and lifecycle hooks for checks tied to component operations. They all run the same language and can load shared functions.
Run scripts inside Atmos
Set type: script and interpreter: starlark on a step inside a custom command,
workflow, or hook. The interpreter is included in Atmos.
Why Starlark?
See why Atmos uses Starlark for the language's syntax, built-in capabilities, and execution model.
How to Use It
Add an Atmos subcommand
Save this configuration as atmos.yaml. It defines a capacity command with a
--replicas flag and a script that calculates total worker capacity:
With Atmos installed, run from the directory containing that file:
atmos capacity --replicas 3
The command prints 3 replicas x 4 workers = 12 workers. The script reads
ctx.flags["replicas"], converts it to an integer, and rejects counts below one.
Run atmos capacity --help for the command's generated help. This example needs
no stacks or external tools.
Guard an operation with a hook
A lifecycle hook runs automatically when Atmos reaches a component event.
The owner-check example reads ctx.component.vars
before a Terraform plan and requires the component to have an owner.
With Atmos and Terraform installed, run these commands from the example's directory:
atmos terraform plan api -s dev
atmos terraform plan api -s unowned
The dev stack passes the check and Terraform reports no changes. The unowned
stack fails with Set an owner before planning api, stopping the plan. The
example module has no providers or resources and needs no cloud credentials.
Share functions between scripts
Move shared code into .star files. Include a script in a YAML step with
script: !include scripts/plan.star, and use load() inside the script to import
functions from other files. Imports resolve relative to the file containing
the load() statement. See files and shared code.
The release-plan example loads a shared function and reads three components with at most two tasks running at once. It prints their configuration without deploying anything:
Next steps
Follow the custom command guide, workflow guide, or hook guide to add a script to your project. Use the testing guide to check its behavior and report failures.
