# atmos list instances

Use this command to list all component instances across stacks, showing each unique component-stack combination. Upload instance metadata to Atmos Pro for centralized tracking and management.

## Usage

```shell
atmos list instances [flags]
```

## Description

The `atmos list instances` command displays all component instances defined across your Atmos stacks. Each instance represents a unique combination of a component and stack. This command is useful for:

- Getting an overview of all deployed/configured infrastructure
- Finding specific component instances across stacks
- Filtering instances by stack pattern or custom criteria
- Uploading instance inventory to Atmos Pro for centralized management

## Flags

- **`--format` / `-f`**
  Output format: 
  `table`
  , 
  `json`
  , 
  `yaml`
  , 
  `csv`
  , 
  `tsv`
  , 
  `tree`
  , 
  `matrix`
   (default: 
  `table`
  )
- **`--delimiter`**
  Delimiter for CSV/TSV output (default: tab for tsv, comma for csv)
- **`--provenance`**
  Show import provenance in tree format. Only works with 
  `--format=tree`
  . Displays the import hierarchy showing which files each component inherits from.
- **`--columns`**
  Columns to display (comma-separated). Overrides 
  `components.list.columns`
   configuration in atmos.yaml
- **`--stack` / `-s`**
  Filter by stack pattern (supports glob patterns, e.g., 
  `plat-*-prod`
  )
- **`--filter`**
  YQ predicate evaluated against each instance row. Rows where the expression is truthy are kept (e.g., 
  `.vars.region == "us-east-1"`
  , 
  `.component == "vpc"`
  ). Not supported with 
  `--format=tree`
   or 
  `--format=matrix`
  .
- **`--query` / `-q`**
  YQ expression that projects each row. Scalar results land in a 
  `value`
   column; map results become row keys addressable via 
  `--columns`
   templates (e.g., 
  `--query '.vars.region'`
  , 
  `--query '{"region": .vars.region, "tenant": .vars.tenant}'`
  ). Not supported with 
  `--format=tree`
   or 
  `--format=matrix`
  .
- **`--sort`**
  Sort by column:order (e.g., 
  `stack:asc,component:desc`
  )
- **`--upload`**
  Upload instances to Atmos Pro API (requires Pro configuration). Every real (non-abstract) instance is uploaded; 
  `settings.pro.enabled`
   is preserved verbatim in the payload so Atmos Pro can reconcile enabled vs. disabled state server-side.
- **`--output-file` / `-o`**
  Write output to file in 
  `key=value`
   format (for 
  `$GITHUB_OUTPUT`
  ). Only supported with 
  `--format=matrix`
  .
- **`--process-templates`**
  Enable/disable Go template processing in Atmos stack manifests (default 
  `true`
  ). Go template functions include 
  `atmos.Component(...)`
  .
  Environment variable: 
  `ATMOS_PROCESS_TEMPLATES`
- **`--process-functions`**
  Enable/disable YAML functions processing in Atmos stack manifests (default 
  `true`
  ). YAML functions include 
  `!terraform.state`
  , 
  `!terraform.output`
  , 
  `!store`
  , 
  `!aws.*`
  , etc. This is distinct from Go template functions like 
  `atmos.Component(...)`
  , which are controlled by 
  `--process-templates`
  .
  Environment variable: 
  `ATMOS_PROCESS_FUNCTIONS`
- **`--skip`**
  Skip executing a specific YAML function in the Atmos stack manifests when processing stacks. Repeat the flag to skip multiple functions (for example, 
  `--skip terraform.state --skip terraform.output`
  ). Useful with 
  `--upload`
   to bypass backend-resolving functions while leaving other YAML functions like 
  `!template`
   enabled.
  Environment variable: 
  `ATMOS_SKIP`

## Examples

List all instances in table format:

```shell
atmos list instances
```

Filter instances by stack pattern:

```shell
# List instances in all production stacks
atmos list instances --stack "*-prod"

# List instances in a specific stack
atmos list instances --stack tenant1-ue2-dev
```

Output in different formats:

```shell
# JSON format for machine processing
atmos list instances --format json

# YAML format for configuration review
atmos list instances --format yaml

# CSV format for spreadsheet compatibility
atmos list instances --format csv
```

Filter instances using YQ expressions:

```shell
# Find all instances in us-east-1 region
atmos list instances --filter '.vars.region == "us-east-1"'

# Find enabled VPC components
atmos list instances --filter '.component == "vpc" and .enabled == true'
```

Project specific fields with `--query`:

```shell
# Pull the region for every instance (scalar projection → `value` column)
atmos list instances --query '.vars.region' --columns 'Stack={{ .stack }},Region={{ .value }}'

# Project multiple fields at once (map projection → addressable keys)
atmos list instances \
  --query '{"region": .vars.region, "tenant": .vars.tenant}' \
  --columns 'Stack={{ .stack }},Tenant={{ .tenant }},Region={{ .region }}'
```

:::note
`--filter` and `--query` operate per-row and require `--format=table`,
`json`, `yaml`, `csv`, or `tsv`. They are rejected with `--format=tree` and
`--format=matrix`, which render different shapes (import hierarchy and
GitHub-Actions matrix JSON, respectively).
:::

Sort instances:

```shell
# Sort by stack name ascending
atmos list instances --sort stack:asc

# Multi-column sort
atmos list instances --sort "stack:asc,component:desc"
```

Upload instances to Atmos Pro:

```shell
atmos list instances --upload
```

The upload includes **every real (non-abstract) instance**, regardless of whether Atmos Pro is enabled for it. The `settings.pro.enabled` flag is preserved verbatim in the payload, so Atmos Pro can reconcile which instances are active vs. disabled on the server side (e.g., grey out disabled instances in the UI rather than losing track of them):

```yaml
components:
  terraform:
    vpc:
      settings:
        pro:
          enabled: true    # Uploaded as enabled
    app:
      settings:
        pro:
          enabled: false   # Uploaded as disabled — Atmos Pro keeps it visible but marks it inactive
    db:
      # No pro config — uploaded as disabled
```

On completion, the command reports a tally:

```
Successfully uploaded 3 instances to Atmos Pro API (1 enabled, 2 disabled, 1 drift enabled).
```

The `drift enabled` count reflects instances with `settings.pro.drift_detection.enabled: true` and is independent of `pro.enabled` — an instance can have drift detection enabled even if its `pro.enabled` flag is `false`.

If the repository has no instances at all, the command prints `No instances found; nothing to upload.` and exits successfully.

View instances in tree format:

```shell
# Tree view without import details
atmos list instances --format tree

# Tree view with import provenance (shows inheritance chain)
atmos list instances --format tree --provenance
```

Output as GitHub Actions matrix JSON:

```shell
# Print matrix JSON to stdout
atmos list instances --format matrix

# Write to $GITHUB_OUTPUT for use in GitHub Actions
atmos list instances --format matrix --output-file=$GITHUB_OUTPUT
```

## Tree Format with Import Provenance

The `tree` format provides a hierarchical view of your component instances organized by stack. When combined with the `--provenance` flag, it shows the complete import chain for each component, making it easy to understand configuration inheritance.

### Tree Format Structure

The tree format displays:

- **Stacks** as top-level nodes
- **Components** as child nodes under each stack
- **Import hierarchy** (when `--provenance` is enabled) showing the chain of stack configuration files

### Import Provenance

When you enable `--provenance`, each component shows its import chain - the sequence of stack configuration files it inherits from. This is particularly useful for:

- **Debugging configuration** - See exactly where each component's configuration comes from
- **Understanding inheritance** - Visualize the complete import chain
- **Auditing changes** - Track which base configurations affect which components
- **Documentation** - Generate visual representations of stack dependencies

Example tree output with provenance:

```
Component Instances
│
├── tenant1-ue2-dev
│   ├── vpc
│   │   ├── stacks/tenant1/ue2/dev
│   │   ├── stacks/tenant1/ue2/_defaults
│   │   └── stacks/catalog/vpc
│   └── eks
│       ├── stacks/tenant1/ue2/dev
│       ├── stacks/tenant1/ue2/_defaults
│       └── stacks/catalog/eks
```

The import chain is shown from most specific (top) to most general (bottom), reflecting how Atmos merges configurations.

## Matrix Format for CI/CD

The `matrix` format produces GitHub Actions-compatible JSON for driving parallel CI/CD jobs. It outputs the same `{"include":[...]}` structure as [`atmos describe affected --format=matrix`](/cli/commands/describe/affected), but includes all instances rather than only changed ones.

Each entry contains `stack`, `component`, `component_path`, and `component_type`:

```shell
atmos list instances --format matrix
```

```json
{"include":[{"stack":"ue1-dev","component":"vpc","component_path":"components/terraform/vpc","component_type":"terraform"}]}
```

### Writing to `$GITHUB_OUTPUT`

Use `--output-file` to write results in `key=value` format for GitHub Actions:

```shell
atmos list instances --format matrix --output-file=$GITHUB_OUTPUT
```

This writes two keys to the file:

```
matrix={"include":[...]}
count=42
```

When `ci.enabled` is true in `atmos.yaml`, `--output-file` is not provided, and `GITHUB_OUTPUT` is available (for example, in GitHub Actions), the output is written to `$GITHUB_OUTPUT` automatically. Outside of GitHub Actions, or when `GITHUB_OUTPUT` is unset, output falls back to stdout.

### GitHub Actions Example

```yaml
jobs:
  enumerate:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.instances.outputs.matrix }}
    steps:
      - uses: actions/checkout@v6
      - name: List all instances
        id: instances
        run: atmos list instances --format=matrix --output-file=$GITHUB_OUTPUT

  deploy:
    needs: enumerate
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJson(needs.enumerate.outputs.matrix) }}
    steps:
      - run: echo "Deploying ${{ matrix.component }} to ${{ matrix.stack }}"
```

## Custom Columns Configuration

You can customize the columns displayed by `atmos list instances` in your `atmos.yaml`:

```yaml
# atmos.yaml
components:
  list:
    columns:
      - name: Stack
        value: "{{ .stack }}"
      - name: Component
        value: "{{ .component }}"
      - name: Tenant
        value: "{{ .vars.tenant }}"
      - name: Environment
        value: "{{ .vars.environment }}"
      - name: Stage
        value: "{{ .vars.stage }}"
      - name: Region
        value: "{{ .vars.region }}"
      - name: Description
        value: "{{ .metadata.description }}"
      - name: Enabled
        value: "{{ .enabled }}"
```

### Available Template Fields

Column `value` fields support Go template syntax with access to:

- `.stack` - Stack name (e.g., `tenant1-ue2-dev`)
- `.component` - Component name (e.g., `vpc`)
- `.atmos_component` - Atmos component identifier
- `.atmos_component_type` - Component type (`terraform`, `helmfile`, etc.)
- `.vars` - All component variables (e.g., `.vars.region`, `.vars.tenant`)
- `.settings` - Component settings (e.g., `.settings.spacelift.workspace_enabled`)
- `.metadata` - Component metadata (e.g., `.metadata.description`)
- `.env` - Environment variables
- `.enabled` - Whether component is enabled (boolean)
- `.locked` - Whether component is locked (boolean)
- `.abstract` - Whether component is abstract (boolean)

### Template Functions

Columns support template functions for data transformation:

```yaml
components:
  list:
    columns:
      - name: Region (Upper)
        value: "{{ .vars.region | upper }}"
      - name: Short Description
        value: "{{ .metadata.description | truncate 50 }}"
      - name: Has Monitoring
        value: "{{ if .vars.monitoring_enabled }}Yes{{ else }}No{{ end }}"
```

### Override Columns via CLI

Override configured columns using the `--columns` flag:

```shell
# Display only stack and component columns
atmos list instances --columns stack,component

# Display custom subset
atmos list instances --columns "stack,component,vars.region,enabled"
```

:::tip

- Use `--format tree --provenance` to visualize component import hierarchies
- Use the `--filter` flag for complex filtering with YQ syntax
- Combine `--stack` (glob pattern) with `--filter` (YQ expression) for precise filtering
- The `--upload` flag sends every real instance to Atmos Pro; `settings.pro.enabled` is included in the payload so Atmos Pro decides enabled vs. disabled server-side
- Use `--format json` or `--format yaml` for programmatic processing
  :::

## Related Commands

- [`atmos list components`](/cli/commands/list/components) - List all components
- [`atmos list stacks`](/cli/commands/list/stacks) - List all stacks
- [`atmos describe component`](/cli/commands/describe/component) - Get detailed component configuration