From 361533d8de55c6d92611bd9e9d999b356168c0ef Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Wed, 15 Jul 2026 18:24:25 +0000
Subject: [PATCH 1/2] docs: document cluster-aware porter env list and json
output
---
standard/cli/command-reference/porter-env.mdx | 49 ++++++++++++++++++-
1 file changed, 47 insertions(+), 2 deletions(-)
diff --git a/standard/cli/command-reference/porter-env.mdx b/standard/cli/command-reference/porter-env.mdx
index 0933caa8..9c5b2b27 100644
--- a/standard/cli/command-reference/porter-env.mdx
+++ b/standard/cli/command-reference/porter-env.mdx
@@ -14,14 +14,59 @@ description: "Create, list, get, set, and unset environment group variables and
## `porter env list`
-List all environment groups in the current project.
+List environment groups for the current project.
**Usage:**
```bash
+porter env list [flags]
+```
+
+**Options:**
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | Output format: `table` (default) or `json` |
+
+When a cluster is set (via `porter config set-cluster`, the `--cluster` flag, or the `PORTER_CLUSTER` environment variable), the list is scoped to that cluster: environment groups whose sync targets include the cluster, plus any cluster-scoped environment groups. This matches what the dashboard shows on the cluster's environment groups page. Without a cluster context, all environment groups in the project are listed.
+
+The default table output shows each group's name, current version, and last updated time.
+
+
+```bash Table (default)
porter env list
```
-Displays a table with each group's name, current version, and last updated time.
+```bash JSON output
+porter env list -o json
+```
+
+
+The `json` output returns two arrays — `environment_groups` and `cluster_scoped_environment_groups` — sharing one object shape:
+
+```json
+{
+ "environment_groups": [
+ {
+ "id": "2a54d3ab-08e2-4922-9368-a7e45ad87d23",
+ "name": "tessier-internal",
+ "current_version": 9,
+ "created_at": "2026-02-25T09:23:16.332254Z",
+ "updated_at": "2026-06-30T04:23:25.23501Z",
+ "sync_target_cluster_ids": [11]
+ }
+ ],
+ "cluster_scoped_environment_groups": [
+ {
+ "id": "",
+ "name": "billing-db",
+ "current_version": 202,
+ "created_at": "2025-10-27T16:00:48Z",
+ "updated_at": "2025-10-27T16:00:48Z",
+ "sync_target_cluster_ids": [11]
+ }
+ ]
+}
+```
---
From 15cdb4aab8e0fdb1312d04127c715413924d4350 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 21 Jul 2026 14:34:28 +0000
Subject: [PATCH 2/2] docs: swap porter env list -o json for --json flag
---
standard/cli/command-reference/porter-env.mdx | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/standard/cli/command-reference/porter-env.mdx b/standard/cli/command-reference/porter-env.mdx
index 9c5b2b27..3617d62c 100644
--- a/standard/cli/command-reference/porter-env.mdx
+++ b/standard/cli/command-reference/porter-env.mdx
@@ -23,13 +23,13 @@ porter env list [flags]
**Options:**
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--output` | `-o` | Output format: `table` (default) or `json` |
+| Flag | Description |
+|------|-------------|
+| `--json` | Print environment groups as JSON instead of a table |
When a cluster is set (via `porter config set-cluster`, the `--cluster` flag, or the `PORTER_CLUSTER` environment variable), the list is scoped to that cluster: environment groups whose sync targets include the cluster, plus any cluster-scoped environment groups. This matches what the dashboard shows on the cluster's environment groups page. Without a cluster context, all environment groups in the project are listed.
-The default table output shows each group's name, current version, and last updated time.
+The default table output shows each group's name, current version, and last updated time, sorted alphabetically by name.
```bash Table (default)
@@ -37,11 +37,11 @@ porter env list
```
```bash JSON output
-porter env list -o json
+porter env list --json
```
-The `json` output returns two arrays — `environment_groups` and `cluster_scoped_environment_groups` — sharing one object shape:
+The `--json` output returns two arrays — `environment_groups` and `cluster_scoped_environment_groups` — sharing one object shape:
```json
{