Skip to main content

ctx.flags

The ctx.flags value is a read-only dictionary of the flags Atmos parsed for the running command. Read parsed values directly instead of interpolating them into the script source or mapping them to environment variables.

Usage​

ctx.flags["name"]
ctx.flags.get("name", default)

Returns​

A frozen dictionary with sorted keys. Its contents depend on the entry point:

  • Custom command: one entry per flag the command declares, with the values and types Atmos parsed. A flag declared as type: int is an integer (base-10 digits only: 010 is 10, and 0x10 is rejected), so use it in arithmetic directly. A flag declared as type: string is a string, so convert it with int(...) first. Boolean flags are booleans. An entry is present for each flag that has a value, including defaults. The default must match the flag's type; a mismatch makes the command unusable and logs a warning that names the flag.
  • Workflow step: the flags the workflow supplies, as strings. This is currently one entry, ctx.flags["stack"], holding the stack the workflow runs against, or an empty string when there is none.
  • Standalone script, hook, or any entry point without declared flags: an empty dictionary. A standalone program receives its flags as the flags argument of the entry function it passes to cli.command.

Steps inside parallel and matrix groups inherit the dictionary.

Examples​

Read typed flags in a custom command​

commands:
  - name: capacity
    description: Calculate a service's total worker capacity
    flags:
      - name: replicas
        type: int
        default: 2
    steps:
      - name: capacity
        type: script
        interpreter: starlark
        script: |
          replicas = ctx.flags["replicas"]
          if replicas < 1:
              fail("replicas must be positive")
          ui.success("{} workers".format(replicas * 4))
atmos capacity --replicas=3
✓ 12 workers

Provide a default for an optional flag​

stack = ctx.flags.get("stack", "dev")

Check whether a flag was provided​

if "dry-run" in ctx.flags and ctx.flags["dry-run"]:
    ui.warning("Dry run: no changes will be made")

Related​