Custom Columns docs

website/docs/cli/commands/list/list-components.mdx

@@ -38,6 +38,24 @@ atmos list components
 atmos list components -s tenant1-ue2-dev
 ```
 
+### Custom Columns for Components
+
+This configuration customizes the output of `atmos list components`:
+
+```yaml
+# In atmos.yaml
+components:
+  list:
+    columns:
+      - name: Component Name
+        value: "{{ .component_name }}"
+      - name: Component Type
+        value: "{{ .component_type }}"
+      - name: Component Path
+        value: "{{ .component_path }}"
+```
+Running `atmos list components` will produce a table with these custom columns.
+
 ## Flags
 
 | Flag             | Description                                                                                                                                                                                                                               | Alias | Required |

website/docs/cli/commands/list/list-metadata.mdx

@@ -86,6 +86,22 @@ atmos list metadata --format csv
 atmos list metadata --format tsv
 ```
 
+### Custom Column using Stack Name
+
+You can use available variables like `.stack_name` in your column definitions:
+
+```yaml
+# In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata)
+list:
+  columns:
+    - name: "Stack"
+      value: "{{ .stack_name }}"
+    - name: "Metadata"
+      value: "{{ .key }}"
+    - name: "Value"
+      value: "{{ .value }}"
+```
+
 ## Example Output
 
 ```shell

website/docs/cli/commands/list/list-settings.mdx

@@ -84,6 +84,22 @@ atmos list settings --format csv
 atmos list settings --format tsv
 ```
 
+### Custom Column using Stack Name
+
+You can use available variables like `.stack_name` in your column definitions:
+
+```yaml
+# In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata)
+list:
+  columns:
+    - name: "Stack"
+      value: "{{ .stack_name }}"
+    - name: "Setting"
+      value: "{{ .key }}"
+    - name: "Value"
+      value: "{{ .value }}"
+```
+
 ## Example Output
 
 ```shell

website/docs/cli/commands/list/list-stacks.mdx

@@ -39,6 +39,24 @@ atmos list stacks
 atmos list stacks -c vpc
 ```
 
+### Customizing Output Columns
+
+This configuration customizes the output of `atmos list stacks`:
+
+```yaml
+# In atmos.yaml
+stacks:
+  list:
+    format: table
+    columns:
+      - name: Stack Name
+        value: "{{ .stack_name }}"
+      - name: Configuration Path
+        value: "{{ .stack_path }}"
+```
+
+When you run `atmos list stacks`, the output table will have columns titled "Stack Name" and "Configuration Path".
+
 ## Flags
 
 | Flag             | Description                                                                                                                                                                                                                               | Alias | Required |

website/docs/cli/commands/list/list-values.mdx

@@ -92,6 +92,22 @@ atmos list values vpc --format tsv
 # The table format will show a width error if the data is too wide for your terminal
 ```
 
+### Custom Column using Stack Name
+
+You can use available variables like `.stack_name` in your column definitions:
+
+```yaml
+# In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata)
+list:
+  columns:
+    - name: "Stack"
+      value: "{{ .stack_name }}"
+    - name: "Key"
+      value: "{{ .key }}"
+    - name: "Value"
+      value: "{{ .value }}"
+```
+
 ## Example Output
 
 ```shell

website/docs/cli/commands/list/list-vars.mdx

@@ -102,6 +102,22 @@ Filter by stack and specific variables:
 atmos list vars vpc --stack '*-ue2-*' --query .vars.region
 ```
 
+### Custom Column using Stack Name
+
+You can use available variables like `.stack_name` in your column definitions:
+
+```yaml
+# In atmos.yaml, under the appropriate scope (values, vars, settings, or metadata)
+list:
+  columns:
+    - name: "Stack"
+      value: "{{ .stack_name }}"
+    - name: "Variable"
+      value: "{{ .key }}"
+    - name: "Value"
+      value: "{{ .value }}"
+```
+
 ## Example Output
 
 ```shell

website/docs/cli/commands/list/list-workflows.mdx

@@ -88,3 +88,44 @@ atmos list workflows --format csv --delimiter ','
 - Use the `--file` flag to filter workflows from a specific manifest file
 - The `describe workflows` command provides more detailed information about workflows
 :::
+
+
+## Examples
+
+### Custom Columns for Workflows
+
+This configuration customizes the output of `atmos list workflows`:
+
+```yaml
+# In atmos.yaml
+workflows:
+  list:
+    columns:
+      - name: Workflow
+        value: "{{ .workflow_name }}"
+      - name: Definition File
+        value: "{{ .workflow_file }}"
+      - name: Description
+        value: "{{ .workflow_description }}"
+```
+Running `atmos list workflows` will display these columns.
+
+## Examples
+
+### Custom Columns for Workflows
+
+This configuration customizes the output of `atmos list workflows`:
+
+```yaml
+# In atmos.yaml
+workflows:
+  list:
+    columns:
+      - name: Workflow
+        value: "{{ .workflow_name }}"
+      - name: Definition File
+        value: "{{ .workflow_file }}"
+      - name: Description
+        value: "{{ .workflow_description }}"
+```
+Running `atmos list workflows` will display these columns.

website/docs/cli/commands/list/usage.mdx

@@ -4,15 +4,156 @@ sidebar_label: list
 sidebar_class_name: command
 description: "List Atmos Stacks and Components"
 ---
-import Screengrab from '@site/src/components/Screengrab'
+
+import Screengrab from '@site/src/components/Screengrab';
 import DocCardList from '@theme/DocCardList';
 
 :::note Purpose
-Use these subcommands to validate Atmos configurations.
+Use these subcommands to list sections of Atmos configurations.
 :::
 
 <Screengrab title="atmos list --help" slug="atmos-list--help" />
 
+Atmos provides a powerful feature to customize the columns displayed by various `atmos list` commands (e.g., `atmos list stacks`, `atmos list components`, `atmos list workflows`). This allows you to tailor the tabular output to show precisely the information you need for different contexts.
+
+Column customization is configured within your `atmos.yaml` file using Go template expressions, enabling dynamic values based on stack, component, or workflow data. This guide explains how to configure and use this feature.
+
+
 ## Subcommands
 
 <DocCardList />
+
+## Supported List Commands
+
+| Command                    | Description                                                                                   |
+|---------------------------|-----------------------------------------------------------------------------------------------|
+| `atmos list stacks`       | Lists all defined **stacks** in your project. A *stack* is a named configuration representing a deployment environment (e.g., `dev/us-east-1`, `prod/eu-west-1`). |
+| `atmos list components`   | Lists all available **components** (Terraform, Helmfile, etc.) defined in the project. Components are reusable infrastructure building blocks. |
+| `atmos list workflows`    | Lists all defined **workflows**, which are custom command sequences defined in `atmos.yaml` to streamline repetitive tasks. |
+| `atmos list values`       | Displays the fully resolved **configuration values** for a specified component in a stack, after inheritance and imports are applied. |
+| `atmos list vars`         | Lists the **Terraform `vars`** (input variables) that will be passed to a component for a given stack. Useful for debugging variable resolution. |
+| `atmos list settings`     | Shows the **`settings` block**, typically used for configuring a component’s behavior (e.g., module version, backend type). |
+| `atmos list metadata`     | Displays the **`metadata` block** associated with a component in a stack, including attributes like `stage`, `tenant`, `environment`, and `namespace`. |
+
+You can define custom columns for each of these commands individually in your `atmos.yaml`.
+
+
+## How Column Customization Works
+
+To customize columns for a specific `list` command, navigate to the relevant section (e.g., `stacks`, `components`, `workflows`) in your `atmos.yaml` configuration file. Within that section, define a `list` block.
+
+Inside the `list` block:
+1.  Specify the output `format` (optional, defaults to `table`). Other options include `json`, `yaml`, `csv`, `tsv`.
+2.  Define a `columns` array. Each element in this array represents a column in the output table and must have:
+    *   `name`: The string that will appear as the column header.
+    *   `value`: A Go template string that dynamically determines the value for each row in that column.
+
+**Example Structure:**
+```yaml
+# In atmos.yaml
+stacks: # Or components, workflows, etc.
+  list:
+    format: table # Optional
+    columns:
+      - name: "Header 1"
+        value: "{{ .some_template_variable }}"
+      - name: "Header 2"
+        value: "Static Text or {{ .another_variable }}"
+      # ... more columns
+```
+
+
+## YAML Template Syntax
+
+The `value` field in each column definition supports Go templates. The available variables within the template depend on the specific `atmos list` command being customized:
+
+### For `atmos list stacks`:
+```yaml
+{{ .stack_name }}  # Name of the stack
+{{ .stack_path }}  # Filesystem path to the stack configuration file
+```
+
+### For `atmos list components`:
+```yaml
+{{ .component_name }}  # Name of the component
+{{ .component_type }}  # Type of the component (e.g., terraform, helmfile)
+{{ .component_path }}  # Filesystem path to the component directory
+```
+
+### For `atmos list workflows`:
+```yaml
+{{ .name }}      # The name of the workflow
+{{ .file }}      # The manifest name
+{{ .description }}  # The description provided for the workflow
+```
+
+### For `atmos list values`, `atmos list vars`, `atmos list settings`, and `atmos list metadata`:
+```yaml
+{{ .stack_name }}  # Name of the stack context
+{{ .key }}         # The key or property name being listed
+{{ .value }}       # The corresponding value for the key
+```
+
+
+## Full Reference: atmos.yaml Structure
+
+Here's the general structure for defining custom list columns in `atmos.yaml`:
+
+```yaml
+<command_scope>: # e.g., stacks, components, workflows, values, vars, settings, metadata
+  list:
+    format: table|json|csv|yaml|tsv  # Optional, default is 'table'
+    columns:
+      - name: "<Your Column Header>"
+        value: "<Go template string using available variables>"
+      # ... add more column definitions as needed
+```
+
+- Replace `<command_scope>` with the specific scope corresponding to the `atmos list` command you want to customize (e.g., `stacks` for `atmos list stacks`).
+- The `columns` array is mandatory if you want to override the default columns. If `columns` is omitted, the command uses its default output columns.
+
+### Custom Columns for Workflows
+
+```yaml
+# In atmos.yaml
+workflows:
+  list:
+    columns:
+      - name: Workflow
+        value: "{{ .name }}"  # Corresponds to the workflow key in the manifest
+      - name: Manifest Name
+        value: "{{ .file }}"   # Corresponds to the 'name' field within the manifest file
+      - name: Description
+        value: "{{ .description }}" # Corresponds to the 'description' field for the workflow
+```
+
+:::info
+Note that `{{ .file }}` in this context refers to the value of the top-level `name` attribute within the workflow manifest file itself, not the path to the file.
+:::
+
+
+## Display Behavior
+
+### TTY vs Non-TTY Output
+
+The appearance of the output table depends on whether `atmos` detects an interactive terminal (TTY) or not:
+
+- **TTY Output (e.g., running in your terminal)**
+  - Displays a formatted table with borders and styling.
+  - Attempts to fit within the terminal width.
+  - Uses standard padding between columns (TableColumnPadding = 3).
+  - Defaults to `format: table` if not specified.
+
+- **Non-TTY Output (e.g., redirecting to a file, piping to another command)**
+  - Produces a simpler, machine-readable format suitable for scripting or automation.
+  - Ensures consistent structure for programmatic parsing.
+
+## Troubleshooting & Tips
+
+- **Blank Columns:** If a column appears empty, double-check the template variable name (`{{ .variable }}`) against the [YAML Template Syntax](#yaml-template-syntax) section for the specific command. Ensure the data context actually contains that variable for the items being listed.
+- **Inspecting Available Data:** Use the `describe` command with `--format json` or `--format yaml` (e.g., `atmos describe stacks --format json`) to see the raw data structure and available fields you can use in your templates.
+- **Wide Tables:** If the table is too wide for your terminal or you encounter errors about content width:
+    - Reduce the number of columns defined in your `atmos.yaml`.
+    - Use a different output format like `json` or `yaml`.
+    - Some `list` commands might support a `--max-columns` flag (check command help).
+- **Filtering:** Use command-specific flags like `--stacks 'pattern'` for `atmos list stacks` to filter the rows, which can indirectly simplify the output. Query flags (`--query`) might also help narrow down data.