> ## Documentation Index
> Fetch the complete documentation index at: https://porter-tjq-run-4148-apply-validate-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When helping a user operate an existing Porter project—deploying, updating, debugging, or inspecting applications and clusters—connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead—a stated preference wins. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# porter env

> Create, list, get, set, and unset environment group variables and secrets from the Porter CLI for project-wide configuration management

`porter env` contains commands for managing environment groups — project-wide sets of environment variables and secrets that can be shared across applications.

## Prerequisites

* You've logged in to the Porter CLI after running [porter auth login](/standard/cli/command-reference/porter-auth)
* You're connected to the correct project by running [porter config set-project](/standard/cli/command-reference/porter-config)

***

## `porter env list`

List environment groups for the current project.

**Usage:**

```bash theme={null}
porter env list [flags]
```

**Options:**

| 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, sorted alphabetically by name.

<CodeGroup>
  ```bash Table (default) theme={null}
  porter env list
  ```

  ```bash JSON output theme={null}
  porter env list --json
  ```
</CodeGroup>

The `--json` output returns two arrays — `environment_groups` and `cluster_scoped_environment_groups` — sharing one object shape:

```json theme={null}
{
  "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]
    }
  ]
}
```

***

## `porter env create`

Create a new environment group.

**Usage:**

```bash theme={null}
porter env create [flags]
```

**Options:**

| Flag                | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `--name`            | Environment group name (prompted interactively if omitted) |
| `--variables`, `-v` | Variables to set as key=value pairs                        |
| `--secrets`, `-s`   | Secrets to set as key=value pairs                          |
| `--no-input`        | Disable interactive prompts                                |

<CodeGroup>
  ```bash Interactive theme={null}
  porter env create
  ```

  ```bash Non-Interactive theme={null}
  porter env create --name production-secrets
  ```

  ```bash With Variables and Secrets theme={null}
  porter env create --name production-secrets \
    -v NODE_ENV=production,LOG_LEVEL=info \
    -s DB_PASSWORD=secret,API_KEY=sk-123
  ```
</CodeGroup>

<Info>
  If an environment group with the same name already exists, the command will fail. Use `porter env set` to update an existing group.
</Info>

***

## `porter env pull`

Pull environment variables from an environment group to your local machine.

**Usage:**

```bash theme={null}
porter env pull [-g] <env-group-name> [flags]
```

**Options:**

| Flag          | Short | Description                                                            |
| ------------- | ----- | ---------------------------------------------------------------------- |
| `--app`       | `-a`  | Target application                                                     |
| `--group`     | `-g`  | Target cluster environment group                                       |
| `--variables` | `-v`  | Output only variables (excludes secrets)                               |
| `--secrets`   | `-s`  | Output only secrets (excludes variables)                               |
| `--merged`    |       | Include variables from all linked env groups (only valid with `--app`) |

<CodeGroup>
  ```bash Print to stdout theme={null}
  porter env pull production-secrets
  ```

  ```bash Write to File theme={null}
  porter env pull production-secrets -f .env.local
  ```

  ```bash Variables Only theme={null}
  porter env pull production-secrets -v
  ```

  ```bash Secrets Only theme={null}
  porter env pull production-secrets -s
  ```

  ```bash App with Linked Env Groups theme={null}
  porter env pull --app my-app --merged
  ```
</CodeGroup>

<Info>
  By default, both variables and secrets are output together. Use `-v` or `-s` to filter. You cannot use both flags at the same time.
</Info>

***

## `porter env set`

Add or update variables and secrets in an environment group.

**Usage:**

```bash theme={null}
porter env set <env-group-name> [flags]
```

**Options:**

| Flag          | Short | Description                         |
| ------------- | ----- | ----------------------------------- |
| `--variables` | `-v`  | Variables to set as key=value pairs |
| `--secrets`   | `-s`  | Secrets to set as key=value pairs   |

<CodeGroup>
  ```bash Set Variables theme={null}
  porter env set production-secrets -v LOG_LEVEL=debug,FEATURE_FLAG=true
  ```

  ```bash Set Secrets theme={null}
  porter env set production-secrets -s API_KEY=sk-new-key
  ```

  ```bash Set Both theme={null}
  porter env set production-secrets \
    -v NODE_ENV=production,LOG_LEVEL=info \
    -s DATABASE_URL=postgres://...
  ```
</CodeGroup>

<Warning>
  Use `-s/--secrets` for sensitive values like API keys and passwords. Secrets are stored in your cloud provider's secret manager and are not visible after creation.
</Warning>

<Info>
  When you update an environment group, all applications synced to it are automatically redeployed with the new values.
</Info>

***

## `porter env unset`

Remove variables or secrets from an environment group.

**Usage:**

```bash theme={null}
porter env unset <env-group-name> [flags]
```

**Options:**

| Flag          | Short | Description                                      |
| ------------- | ----- | ------------------------------------------------ |
| `--variables` | `-v`  | Comma-separated list of variable names to remove |
| `--secrets`   | `-s`  | Comma-separated list of secret names to remove   |

<CodeGroup>
  ```bash Remove Variables theme={null}
  porter env unset production-secrets -v OLD_KEY,UNUSED_VAR
  ```

  ```bash Remove Secrets theme={null}
  porter env unset production-secrets -s ROTATED_KEY,OLD_SECRET
  ```

  ```bash Remove Both theme={null}
  porter env unset production-secrets -v VAR1 -s SECRET1
  ```
</CodeGroup>

<Info>
  When you update an environment group, all applications synced to it are automatically redeployed with the new values.
</Info>

***

## Legacy Commands

The following flag-based syntax is supported for managing app-level and cluster-level environment variables. These are legacy commands — for environment groups, use the positional argument syntax above.

### Legacy Flags

| Flag               | Short | Description                                                    |
| ------------------ | ----- | -------------------------------------------------------------- |
| `--app`            | `-a`  | Target application                                             |
| `--group`          | `-g`  | Target cluster environment group                               |
| `--target`         | `-x`  | Deployment target name                                         |
| `--skip-redeploys` |       | Skip re-deploying apps linked to the cluster environment group |

<Info>
  You must specify either `--app` or `--group`, but not both.
</Info>

<CodeGroup>
  ```bash Pull from App theme={null}
  porter env pull --app my-app
  ```

  ```bash Pull from Cluster Env Group theme={null}
  porter env pull --group staging-config
  ```

  ```bash Set App Variables theme={null}
  porter env set --app my-app -v KEY1=value1,KEY2=value2
  ```

  ```bash Set Cluster Group Variables theme={null}
  porter env set --group my-env-group -v KEY1=value1
  ```

  ```bash Unset App Variables theme={null}
  porter env unset --app my-app -v KEY1,KEY2
  ```

  ```bash Skip Redeploys theme={null}
  porter env set --group my-env-group -v KEY=value --skip-redeploys
  ```
</CodeGroup>

***

## Related

* [Environment Groups](/applications/configure/environment-groups) — Overview of environment groups
* [porter.yaml Reference](/applications/configuration-as-code/reference) — `envGroups` field in porter.yaml
* [porter app](/standard/cli/command-reference/porter-app) — Application management commands
* [porter apply](/standard/cli/command-reference/porter-apply) — Deploy with porter.yaml