Skip to main content

flags

The flags field declares long and short flags for a custom command. Flag values are available to steps, env, and templates as {{ .Flags.<name> }}.

Passing Flags​

Passing flags works much like positional arguments, except they are passed using long or short flags. Flags can be optional by setting required: false.

commands:
  - name: hello
    description: This command says hello to the provided name
    flags:
      - name: name
        shorthand: n
        description: Name to greet
        required: true
    steps:
      - "echo Hello {{ .Flags.name }}!"

Run it using the long flag:

atmos hello --name world

Or the shorthand:

atmos hello -n world
name
Required. Flag name, used as --<name> and referenced as {{ .Flags.<name> }}.
shorthand
Optional single-character short flag (for example, n enables -n).
description
Help text shown in atmos help.
type
Data type of the flag: string (default) or bool. See Boolean Flags.
required
When true, the command fails if the flag is omitted and no default is set.
default
Value used when the flag is omitted. See Flag Defaults.
semantic_type
Optional component or stack. See Semantic Types.

Boolean Flags​

Flags can be defined as boolean type using type: bool. Boolean flags don't require a value — when present, they are set to true.

commands:
  - name: deploy
    description: Deploy to environment
    flags:
      - name: dry-run
        shorthand: d
        description: Perform a dry run without making changes
        type: bool
      - name: verbose
        shorthand: v
        description: Enable verbose output
        type: bool
        default: false
      - name: auto-approve
        description: Auto-approve without prompting
        type: bool
        default: true
    steps:
      - |
        {{ if .Flags.dry-run }}
        echo "DRY RUN MODE"
        {{ end }}
        {{ if .Flags.verbose }}
        echo "Verbose output enabled"
        {{ end }}
        {{ if .Flags.auto-approve }}
        terraform apply -auto-approve
        {{ else }}
        terraform apply
        {{ end }}

Usage:

# Enable dry-run (sets it to true)
atmos deploy --dry-run

# Use short flag
atmos deploy -d

# Boolean with explicit value
atmos deploy --auto-approve=false

Using Boolean Flags in Steps​

Boolean flags are available as Go template variables with values true or false. Here are common patterns for using them in bash:

commands:
  - name: build
    description: Build the project
    flags:
      - name: verbose
        shorthand: v
        type: bool
        description: Enable verbose output
      - name: clean
        type: bool
        default: true
        description: Clean before building
    steps:
      # Pattern 1: Conditional command execution with if/else
      - |
        {{ if .Flags.verbose }}
        echo "Verbose mode enabled"
        set -x
        {{ end }}

      # Pattern 2: Inline conditional flag
      - echo "Building{{ if .Flags.verbose }} with verbose output{{ end }}..."

      # Pattern 3: Pass as flag to another command
      - make build {{ if .Flags.verbose }}VERBOSE=1{{ end }}

      # Pattern 4: Conditional step execution
      - |
        {{ if .Flags.clean }}
        echo "Cleaning build directory..."
        rm -rf ./build
        {{ end }}

      # Pattern 5: Negation check
      - |
        {{ if not .Flags.clean }}
        echo "Skipping clean step"
        {{ end }}

      # Pattern 6: Convert to shell variable
      - |
        VERBOSE={{ .Flags.verbose }}
        if [ "$VERBOSE" = "true" ]; then
          echo "Verbose is on"
        fi

      # Pattern 7: Using printf for explicit string conversion
      - |
        VERBOSE={{ printf "%t" .Flags.verbose }}
        echo "Verbose flag is: $VERBOSE"
tip

Boolean values automatically render as true or false (lowercase strings) when used in templates. You can reference them directly with {{ .Flags.name }} — no conversion needed!

Flag Defaults​

Both string and boolean flags support default values using the default attribute:

flags:
  - name: environment
    description: Target environment
    default: "development"
  - name: force
    type: bool
    description: Force the operation
    default: false
  - name: auto-approve
    type: bool
    description: Skip confirmation prompts
    default: true

When a flag has a default value, users can omit it from the command line. The default value will be used unless explicitly overridden.

Semantic Types​

Set semantic_type: component or semantic_type: stack to tell Atmos that a flag provides the component name or stack name, so Atmos can resolve the matching component configuration and expose it as {{ .Component.* }}. We use semantic_type for flags because type already specifies the data type (string, bool).

commands:
  - name: script
    description: "Run script components"
    flags:
      - name: stack
        shorthand: s
        description: "Stack name"
        semantic_type: stack         # this flag provides the stack name
        required: true
    component:
      type: script
    steps:
      - 'echo "Stack: {{ .Component.atmos_stack }}"'

See component for the full custom component type workflow.