# Automate Common Workflows

:::note Optional chapter
You've already deployed the full backend. This chapter and the ones that follow are **optional** — reach for them when you want to package the commands your operators run every day.
:::

Atmos workflows combine multiple steps into a single executable unit of work. Since `atmos terraform deploy --all` and
`atmos terraform destroy --all` already handle graph-backed deploy and teardown, this workflow focuses on orientation:
what stacks exist, which component instances are in the selected stack, how to validate the manifests, and which commands
an operator should run next.

:::tip
See [Atmos Workflows](/workflows) for the full reference. Workflows and [custom commands](/cli/configuration/commands) compose: you can call a custom command from a workflow, and run a workflow from a custom command.
:::

## Configure the workflows directory

In `atmos.yaml`, configure the workflow base path:

```yaml
workflows:
  base_path: "stacks/workflows"
```

Add workflow manifests in the `stacks/workflows` folder:

```console
stacks/
└── workflows/
    ├── backend.yaml
    └── validation.yaml
```

## Add an operator orientation workflow

**File:** `stacks/workflows/backend.yaml`

```yaml
name: Backend
description: Operator workflows for exploring and running the application backend

workflows:
  operator/orient:
    description: |
      Show the stack tree, component instances, component catalog, validation
      command, and day-to-day commands an operator uses for this quick-start stack.
    steps:
      - name: stacks
        type: stage
        title: Stack import tree

      - name: show-stacks
        type: shell
        command: atmos list stacks --format tree --provenance --identity=false --process-functions=false --process-templates=false

      - name: instances
        type: stage
        title: Component instances

      - name: show-instances
        command: list instances --format tree --provenance --identity=false --process-functions=false --process-templates=false

      - name: catalog
        type: stage
        title: Component catalog

      - name: list-components
        type: spin
        title: Preparing component catalog command
        command: true

      - name: show-components
        command: list components --identity=false --process-functions=false --process-templates=false

      - name: commands
        type: stage
        title: Operator commands

      - name: validation-note
        type: markdown
        content: |
          Run `atmos validate stacks` after the sandbox is started to validate the stack manifests with runtime-backed functions enabled.

      - name: command-table
        type: table
        title: Quick-start operator commands
        columns:
          - task
          - command
        data:
          - task: Start sandbox
            command: atmos emulator up aws -s <stack>
          - task: Validate manifests
            command: atmos validate stacks
          - task: Deploy stack
            command: atmos terraform deploy --all -s <stack>
          - task: Inspect provenance
            command: atmos describe component app-config -s <stack> --provenance
          - task: Destroy stack
            command: atmos terraform destroy --all -s <stack> -auto-approve

      - name: done
        type: toast
        level: info
        content: "Use `atmos terraform deploy --all -s <stack>` and `atmos terraform destroy --all -s <stack>` for graph-backed operations."
```

The workflow uses newer step types:

- `stage` prints progress markers for the operator.
- `shell` runs a command exactly as written.
- `spin` keeps a short status step compact while it runs.
- `markdown` adds a short validation note without executing the validation command during a dry run.
- `table` shows the commands operators use next.
- `toast` finishes with a clear status message.

## Run the workflow

Run the workflow for a stack:

```shell
atmos workflow operator/orient -f backend -s plat-ue2-dev
```

Use `--dry-run` to preview the steps without executing them:

```shell
Executing the workflow 'operator/orient' from 'stacks/workflows/backend.yaml'

Executing workflow step: stacks
Executing workflow step: atmos list stacks --format tree --provenance --identity=false --process-functions=false --process-templates=false
Executing workflow step: instances
Executing workflow step: atmos list instances --format tree --provenance --identity=false --process-functions=false --process-templates=false -s plat-ue2-dev
Executing workflow step: catalog
Executing workflow step: list-components
Executing workflow step: atmos list components --identity=false --process-functions=false --process-templates=false -s plat-ue2-dev
Executing workflow step: commands
Executing workflow step: validation-note
Executing workflow step: command-table
Executing workflow step: done
```

:::tip Let Atmos prompt you
For single-component Terraform commands, you can omit the component or stack in an interactive terminal and Atmos will prompt you:

```shell
atmos terraform plan app-config -s plat-ue2-dev
atmos terraform plan
```

For bulk workflows, keep using explicit selectors such as `--all`, `--components`, or `--query`.
:::