Skip to main content

arguments

The arguments field declares positional arguments for a custom command. Argument values are available to steps, env, and templates as {{ .Arguments.<name> }}.

Positional Arguments​

If a positional argument is required but not provided by the user, the command fails — unless you define a default.

For example, this greet command accepts one name argument and defaults to "John Doe":

commands:
  - name: greet
    description: This command says hello to the provided name
    arguments:
      - name: name
        description: Name to greet
        default: John Doe
    steps:
      - "echo Hello {{ .Arguments.name }}!"

Run it with an argument:

atmos greet Alice

or rely on the default:

atmos greet
name
Required. Argument name, referenced as {{ .Arguments.<name> }}.
description
Help text shown in atmos help.
required
When true, the command fails if the argument is omitted and no default is set.
default
Value used when the argument is omitted.
type
Optional semantic type: component or stack. See Typed Arguments.

Trailing Arguments​

Atmos supports trailing arguments after -- (a standalone double-dash). The -- is a delimiter that signals the end of Atmos-specific options. Anything after -- is passed directly to the underlying command without being interpreted by Atmos, and is available in {{ .TrailingArgs }}.

commands:
  - name: ansible run
    description: "Runs an Ansible playbook, allowing extra arguments after --."
    arguments:
      - name: playbook
        description: "The Ansible playbook to run"
        default: site.yml
        required: true
    steps:
      - "ansible-playbook {{ .Arguments.playbook }} {{ .TrailingArgs }}"

Output:

$ atmos ansible run -- --limit web
Running: ansible-playbook site.yml --limit web

PLAY [web] *********************************************************************

Typed Arguments​

Set type: component or type: stack to tell Atmos that an argument provides the component name or stack name. Atmos then resolves the matching component configuration and exposes it as {{ .Component.* }}. See component for the full custom component type workflow.

commands:
  - name: script
    description: "Run script components"
    arguments:
      - name: component
        description: "Component name"
        type: component              # this argument provides the component name
        required: true
    component:
      type: script
    steps:
      - 'echo "Running {{ .Component.component }} in {{ .Component.atmos_stack }}"'

For flags, use semantic_type instead of type (since type on a flag specifies its data type).