Add Custom Commands

Optional chapter

This is an advanced extension point, not a required step — most people add custom commands only after running Atmos for a while and noticing a command they wish existed.

Atmos can be extended with any number of custom CLI commands — your own atmos <verb> subcommands, defined in YAML, that wrap whatever your team repeats.

tip

See Atmos Custom Commands for the full reference.

Custom commands are defined in the commands section of your atmos.yaml.

Atmos already has built-in commands for discovery, including atmos list stacks, atmos list components, and atmos list instances. Instead of reimplementing those, the quick-start example adds an operator command group that combines the built-ins into the views operators usually need.

atmos.yaml

commands:
  - name: operator
    description: Operator shortcuts for exploring and running the quick-start stack
    commands:
      - name: status
        description: Show the stack/component tree and next operator checks
        flags:
          - name: stack
            shorthand: s
            description: Target stack (for example, plat-ue2-dev)
            required: true
        steps:
          - name: stacks
            type: stage
            title: Stack import tree
          - type: shell
            command: atmos list stacks --format tree --provenance --identity=false --process-functions=false --process-templates=false
          - name: instances
            type: stage
            title: Component instances in {{ .Flags.stack }}
          - type: shell
            command: atmos list instances --stack {{ .Flags.stack }} --format tree --provenance --identity=false --process-functions=false --process-templates=false
          - name: catalog
            type: stage
            title: Component catalog
          - type: spin
            title: Resolving component catalog
            command: atmos list components --identity=false --process-functions=false --process-templates=false
          - type: table
            title: Next operator commands
            columns:
              - task
              - command
            data:
              - task: Validate manifests
                command: atmos validate stacks
              - task: Deploy stack
                command: atmos terraform deploy --all -s {{ .Flags.stack }}
              - task: Destroy stack
                command: atmos terraform destroy --all -s {{ .Flags.stack }} -auto-approve
          - type: toast
            level: success
            content: "Operator status complete for {{ .Flags.stack }}."

      - name: inspect
        description: Inspect a component and show where its values came from
        arguments:
          - name: component
            description: Component to inspect
        flags:
          - name: stack
            shorthand: s
            description: Target stack (for example, plat-ue2-dev)
            required: true
        steps:
          - name: provenance
            type: stage
            title: Component configuration provenance
          - type: shell
            command: atmos describe component {{ .Arguments.component }} -s {{ .Flags.stack }} --provenance
          - type: toast
            level: info
            content: "Use `atmos terraform plan {{ .Arguments.component }} -s {{ .Flags.stack }}` to preview changes, or omit the component/stack in an interactive terminal and Atmos will prompt you."

Run the status command to see stack inheritance, component instances, the component catalog, and the next operator commands:

atmos operator status -s plat-ue2-dev

Stack import tree
Component instances in plat-ue2-dev
Component catalog
Next operator commands

Run the inspect command when you need to answer where a value came from:

atmos operator inspect app-config -s plat-ue2-dev

The inspect command wraps:

atmos describe component app-config -s plat-ue2-dev --provenance

Let Atmos prompt you

Prompting is built into single-component Terraform commands. If you forget the component or stack, omit it and Atmos will ask:

# Explicit
atmos terraform plan app-config -s plat-ue2-dev

# Interactive: choose component, then stack
atmos terraform plan

For bulk operations, use --all, --components, or --query instead:

atmos terraform deploy --all -s plat-ue2-dev
atmos terraform destroy --all -s plat-ue2-dev -auto-approve