Add Custom Commands

Optional chapter

This chapter is optional. Most people add a custom command only after they use Atmos for a while and find a task they repeat.

You can extend Atmos with custom CLI commands. Each command is your own atmos <verb> subcommand. Define it in YAML to wrap a task your team repeats.

tip

See Atmos Custom Commands for the full reference.

You define custom commands in the commands section of atmos.yaml.

This example adds an operator command group. It wraps atmos list stacks, atmos list components, and atmos list instances in the views operators use most.

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. It shows 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 to find 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

Atmos prompts you in single-component Terraform commands. If you omit the component or stack, Atmos asks for it:

# 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