# Add Custom Commands

:::note 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](/cli/configuration/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.

**File:** `atmos.yaml`

```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:

```shell
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:

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

The inspect command wraps:

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

:::tip 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:

```shell
# 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:

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

:::