# Compare environments

See every secret name across Default and each environment, what each environment resolves it to, and which values are equal, without any value leaving the server.

## Prerequisites

- Permission for `secrets:ListSecrets`; rows show only secrets you may describe
  (`secrets:GetSecret`).
- To compare values, `secrets:CompareSecretValues` on each secret compared. It is a sensitive
  action: each comparison is recorded in the audit log, and read-only policies leave it out.
- In the console, also `secrets:ListSecretEnvironments` to open **Environments**; without it the
  page says your policies do not grant it.

## See the matrix

**Console**
1. Open **Environments** (in the Secrets navigation).
2. Read the table: one row per name, a column for **Default** and each environment. A cell shows
   the environment's own version (`v3`), `default` when it gets the Default, or `not set`. A name
   missing while an earlier environment has it reads `not set · in Staging`, in amber.
3. (Optional) Turn on **Compare values**. Cells with the same letter hold the same value. Only
   names set in more than one place are compared.
4. (Optional) Choose a row to see one name in every environment, open its secrets, promote it, or
   choose **Override the default** or **Set a value**.

**CLI**
```sh
dcloud secrets environments matrix --compare 1 --group dialog
```

**API**
```http
GET /secrets/api/environments/matrix?compare=1&group=dialog
```

Each row has `cells` (by `default` and environment id) and `resolves`: for each environment `own`,
`default` or `missing`. For a `missing` one, `promotableFrom` names the nearest earlier environment
that has its own secret; otherwise it is `null`. `compare=1` adds a `valueClass` letter per cell;
secrets you may not compare, or whose value cannot be read, are counted in `notCompared`. `group` limits the rows to a group and the groups below it.

## Compare two environments

```sh
dcloud secrets environments diff --from '"default"' --to '"7c6d5e4f-3a2b-4c1d-9e8f-7a6b5c4d3e2f"'
```

`GET /secrets/api/environments/diff?from=…&to=…` takes environment ids or `default`, and returns one
row per name with `status` `same`, `different`, `only-from`, `only-to` or `unknown`. An `unknown`
row has a `reason`: "needs secrets:CompareSecretValues on both" when you lack the action on either
secret, or why a value could not be read (such as a disabled key). An unknown environment id is
`404` "Environment not found".

## Related

- [Promote a secret](promote-a-secret.md)
- [Environments](environments.md)
