Custom Commands
Add a subcommand such as atmos capacity by defining it in atmos.yaml.
YAML declares its arguments, flags, help, and steps. Atmos loads the command
when you run it from your project.
Give your team a command for a task it repeats: checking a deployment, reporting capacity, or preparing a release. Declare the inputs and defaults once in YAML; Atmos provides parsing and help, while your script implements the work. The command lives with your project and runs the same way locally and in CI.
Install Atmos and put it on your PATH. This example needs no stacks,
components, or external tools.
Define your subcommand
Save this configuration as atmos.yaml:
The YAML defines the command name, description, --replicas flag, default, and
step to run. The embedded Atmos Automation Language program implements the
calculation and checks that the replica count is positive.
The step selects the Atmos Automation Language, a Python-like language based on
Starlark, with type: script and interpreter: starlark. The interpreter ships
with Atmos, so this command needs no separate language runtime.
Run the command
Run from the directory containing atmos.yaml:
atmos capacity --replicas 3
✓ 3 replicas x 4 workers = 12 workers
Atmos discovers the custom command, parses its flag, and runs the script. Your team uses the same command locally and in CI.
Omit the flag to use the default of two replicas:
atmos capacity
✓ 2 replicas x 4 workers = 8 workers
Run atmos capacity --help to see the command description and generated flag help:
--replicas string Number of service replicas (default 2)
Use inputs in your program
Script steps read parsed flags from ctx.flags and named positional arguments
from ctx.arguments. These mappings are read-only, and values stay data rather
than being inserted into the program's source.
The example declares replicas as a string flag, so the script converts
ctx.flags["replicas"] with int() before calculating. A boolean flag would
arrive as a boolean. The step calls fail("replicas must be positive") for zero
or negative counts, stopping the command with that error.
Try atmos capacity --replicas 0 to see the validation error.
Declare a flag with type: int to receive an integer in ctx.flags and drop the int()
conversion. An optional argument (required: false, no default) that the caller omits is an
empty string in ctx.arguments, so test it with if ctx.arguments["region"]:. See
flags and
optional arguments.
Grow the command
Custom commands can have multiple steps, named arguments, nested subcommands,
and component context. Start with the interface your team needs, then compose
the operations behind it. Move shared program logic into .star files when
several commands need the same behavior.
See the custom command configuration reference for the full YAML schema and the language overview for language helpers and execution controls. The complete runnable example contains the configuration used throughout this guide.
