Files
coder/cli/testdata/coder_secret_list_--help.golden
T
Steven Masley 03cba25a63 feat: list a workspace build's secrets in coder secret list (#30388)
`coder secret list` now shows the current workspace build's secrets next to your user secrets, and which user secrets they replace. Part of [RELAY-7](https://linear.app/codercom/issue/RELAY-7/agent-relay-deliver-provider-credentials-via-coder-secrets-instead-of).

**Stack** (design decisions in #30248)
1. #30248 Database schema, queries, and RBAC
2. #30249 Encryption at rest
3. #30250 Set secrets on workspace builds
4. #30251 Deliver secrets to the agent
5. #30252 Docs
6. **#30388 List a build's secrets (this PR)**
7. #30459 Audit a build's secrets

- New `GET /workspacebuilds/{workspacebuild}/secrets` lists a build's secrets (metadata only, never values) and which user secret each one replaces.
- Inside a workspace, `coder secret list` includes the current build's secrets. Outside a workspace, use `--workspace` or `--build-id`.
- The agent now exposes `CODER_WORKSPACE_BUILD_ID`, so the CLI knows which build it is running in.
- The agent manifest and the new endpoint use one shared resolver, so they always agree on which secret wins.
- The user secret API is unchanged.

<details>
<summary>Implementation details</summary>

- The manifest carries `workspace_build_id`; the agent sets it as `CODER_WORKSPACE_BUILD_ID`.
- `coderd/workspacesecrets.Resolve(user, build, policy)` decides which secret is delivered on each env var and file. The manifest no longer relies on entry order.
- `codersdk.WorkspaceSecret` embeds `UserSecret` and adds `workspace_build_id`, `ephemeral`, `cleared_at`, `env_replaces`, and `file_replaces`. Secrets whose values a later build cleared are still listed, with `cleared_at` set.
- CLI columns: `source` and `replaced by` are shown by default only when a build is included; `ephemeral` is opt-in. The CLI makes two requests: user secrets, then build secrets.
- Agents that predate the build ID fall back to `CODER_WORKSPACE_ID` and its latest build.

</details>

<details>
<summary>Decision log</summary>

(existing decision log, unchanged)

</details>

---

*Created by Coder Agents on behalf of @Emyrk.*
2026-10-15 17:40:00 -05:00

37 lines
1.2 KiB
Plaintext

coder v0.0.0-devel
USAGE:
coder secret list [flags] [name]
List secrets, or show one by name
Aliases: ls
Secret values are omitted from the output.
When listing all secrets inside a workspace, or with --workspace or
--build-id, the workspace build's secrets are included and the source and
"replaced by" columns are shown by default. If a build secret uses the same
env var or file as a user secret, the user secret is not delivered on that
target and its "replaced by" column names the build secret, for example "env:
build/github-token".
OPTIONS:
--build-id string
Include the secrets of this workspace build. Takes precedence over
--workspace.
-c, --column [created|name|updated|source|env|file|enabled|replaced by|ephemeral|description] (default: name,created,updated,env,file,enabled,description)
Columns to display in table output.
-o, --output table|json (default: table)
Output format.
--workspace string
Include the secrets of this workspace's latest build. Inside a
workspace, the default is the build the workspace agent was started
from.
———
Run `coder --help` for a list of global options.