Follow-up to #30199. `--template-version` on `coder create`, `start`,
`stop`, and `update` (plus `--stop-template-version` on `update`) now
takes a template version ID as well as a name. Passing a version UUID
used to 404 with a pretty unhelpful `get template version by name`
error.
`resolveTemplateVersionID` still looks up by name first, so a version
that happens to be named like a UUID resolves the same way it did
before. If that 404s and the input parses as a UUID, it falls back to
fetching the version by ID. Either way the version has to belong to the
selected template. That check matters most for `create`, which only
sends the version ID and lets the server derive the template from it, so
without it `coder create --template foo --template-version <id of a bar
version>` would quietly create a `bar` workspace.
The name is now path-escaped before the lookup. Previously something
like `../../../templateversions/<id>` could reach other API routes
through the name lookup and skip the template check entirely.
Not-found errors now read `template version "x" not found for template
"foo"` instead of the raw SDK error, so anything matching on the old
text will need updating. Flag help and the generated CLI docs say "name
or ID" now.
Add named template version selection to `coder start` and `coder stop`,
and independent stop/start selection to `coder update` with
`--stop-template-version` and `--template-version`. Stop still defaults
to the workspace's current version, and update starts with the active
version by default. Explicit selections use the selected version for
parameter preparation and builds, keep server permissions authoritative,
and never silently fall back to the active version.
Classic stop builds retain previous parameter values omitted by the
selected stop version, so a later start can reuse them across separate
commands or an interrupted update. Declared parameters still follow
normal validation, and start builds still discard removed parameters.
Update now returns an error and retry guidance when a start apply fails
after stopping, including unflagged updates that previously returned
success.
Closes#29100
[PLAT-616](https://linear.app/codercom/issue/PLAT-616/cli-allow-specifying-a-template-version-for-stopstart-builds-and-both)
---------
Co-authored-by: Nick Vigilante <nickvigilante@users.noreply.github.com>
## What
Adds in-memory log buffering for CLI diagnostics so the debug detail
leading up to a failure is available without logging debug during normal
operation. Below-level entries are kept in a slog flight recorder
(`v3.2.0`) and emitted only when a command returns an error. This
implements CLI-4 (connection-log RFC req 13). Depends on the
`cdr.dev/slog/v3` `v3.2.0` bump (already on `main`).
## How
- **Root command** (`cli/root.go`):
- New global `--log-buffer-size` / `CODER_LOG_BUFFER_SIZE` (default
`10`, `0` disables, clamped to `10000`), shared by all commands instead
of duplicated per command.
- `bufferedLoggerMiddleware` runs the invocation logger at `Info` (or
`Debug` with `-v`) with a flight recorder, and on a returned error calls
`Flush` to replay the buffered history to stderr. `Flush` does not add a
duplicate error line; the returned error is still rendered by the normal
formatter.
- Opt-in via an `annotationBufferedLogger` annotation so it does not
clobber the ~17 commands that build their own logger on `inv.Logger`
(which would otherwise double-log). Future commands opt in with one
line.
- `start` / `stop` / `update`: opt into the middleware and just
`client.SetLogger(inv.Logger)` so codersdk request/response debug is
captured and flushed to stderr on failure. They **no longer write
session log files** and dropped their per-command `--log-dir` /
`--log-buffer-size`.
- `ssh`: keeps its own file logger (writing to stderr would corrupt its
stdio stream), now using the global buffer size and the shared
`bufferedLogger` helper. It retains `--log-dir` / `CODER_SSH_LOG_DIR`,
stdio/PID filename handling, and file pruning (50 most recent).
- `restart` is excluded, matching the `client_session_id` opt-in set
(DEVEX-664).
## Default behavior change
`start` / `stop` / `update` now emit buffered diagnostics (recent
below-level entries, e.g. sdk request/response) to **stderr** when they
fail; on success they stay quiet. `coder ssh` continues to write a
per-connection diagnostic file by default under the XDG state dir
(`~/.local/state/coder/logs`), pruned to the 50 most recent. Opt out of
buffering with `--log-buffer-size 0`.
## Review changes (Asher)
- Shared logger construction: the level is computed once and the flight
recorder is always attached, in a single `bufferedLogger` helper used by
ssh and the workspace commands.
- Workspace commands print to normal output instead of a log file, and
the default buffer is `10` to avoid flooding the terminal on failure.
- The buffer lives on the root command / logger (global option +
middleware) rather than being wired into each command.
## Alignment with #29671 (agent)
Same core model: `Info` default with a flight recorder, `-v` for full
debug, and the shared `--log-buffer-size` semantics (`0` disables).
Differences: the agent writes to a file and defaults the buffer to
`1000`, while the CLI prints to stderr and defaults to `10`; both now
rely on slog's auto-flush-on-error (the CLI additionally flushes via the
middleware on a returned error).
> [!NOTE]
> The agent PR (#29671) adds an agent-scoped `--log-buffer-size` /
`CODER_AGENT_LOG_BUFFER_SIZE` on the hidden `coder agent` command. Once
both land, the global `--log-buffer-size` here and the agent's own flag
will need reconciling on `coder agent`. Flagging for whichever merges
second.
## Testing
`cli.TestClampLogBufferSize`, `TestPruneSessionLogs`,
`TestDefaultSessionLogDir`, and `TestBufferedLogger_*` cover clamping,
ssh log retention, the default state dir, buffer-until-error, the
middleware's flush path, and the verbose escape hatch.
`start`/`stop`/`update`/`ssh` command tests pass. Golden `--help` output
and `docs/reference/cli` regenerated. (`TestSSH/Env` is a pre-existing
interactive-PTY test that does not run in all sandboxes; it fails
identically on `main` here.)
<details>
<summary>Rollout context</summary>
Cross-repo sequence: coder/slog flight recorder (released as v3.2.0) ->
go.mod bump in coder/coder (#29600, merged) -> CLIENT-672 (agent,
#29671) and this PR (CLI-4), which are independent consumers and can
merge in any order.
</details>
---
<sub>Opened by Coder Agents on behalf of @aqandrew.</sub>
## Summary
Implements DEVEX-664: the coder CLI commands that open a workspace
connection now generate a client session ID and attach it to their
requests, logs, and existing network telemetry, per the connection-log
RFC.
Commands opt in explicitly with a `client_session_id` annotation. The
opted-in set is `coder ssh`, `coder start`, `coder stop`, and `coder
update`. Long-running daemon commands (`coder server`, `agent`,
`provisionerd`, and so on) deliberately stay out, so they never carry a
meaningless session ID in their logs, request baggage, or telemetry.
- **Generate / resolve**: a 16-byte lowercase-hex session ID is
generated per opted-in invocation. When `CODER_TRACE_SESSION_ID` is set
(so Toolbox and the VS Code plugin can correlate the CLI they spawn),
that value is used verbatim; a warning is logged if it is not the
canonical 32-char lowercase hex form, since coderd/agent middleware drop
non-canonical values.
- **Requests**: the ID is attached to every request as
`client_session_id` W3C baggage via a transport wrapper, independent of
whether tracing is enabled. The already-merged coderd tracing middleware
(#27671) reads it.
- **Coordinate websocket**: the ID is also set explicitly as baggage on
the tailnet coordinate handshake in `workspacesdk.DialAgent`, so
coderd's `/api/v2/workspaceagents/{id}/coordinate` endpoint logs it (it
does not rely on the CLI transport for that dial).
- **Logs**: the ID is added to the command's log context.
- **Existing telemetry**: the ID is added to tailnet `TelemetryEvent`
(`client_session_id`, new field 20; proto minor version bumped) and
plumbed from the CLI through `workspacesdk.DialAgent`.
Scope is the coder CLI client only (RFC glossary + requirement 5), and
within the CLI only the opted-in workspace-connecting commands above.
This PR is independent of #28039 (the agent middleware that consumes the
baggage); it depends only on `tracing.SessionIDBaggageKey`, which is
already on `main` via #27671.
## Out of scope
RFC requirements 7-16 (connection-state change logging,
`connection_logs` columns, log buffering, routing/disconnect-reason
logs, coordination-protocol plumbing, `agentssh`/`reconnectingpty`
command logging, support-bundle log capture) and requirements 4.2/4.3
(VS Code telemetry, Prometheus stats) are separate tickets. IDE plugins,
Toolbox, and the daemon commands are also out of scope.
## Testing
- `go test ./coderd/tracing/... ./cli/... ./tailnet/...
./codersdk/workspacesdk/...` (unit tests for the generator, the
env/generate resolver, per-command opt-in, the baggage transport
wrapper, the coordinate-dial baggage helper, and the telemetry field).
- `go build ./...`, `go vet`, and `golangci-lint` pass on the touched
packages.
- `make tailnet/proto/tailnet.pb.go` regenerated the proto; the proto
minor version was bumped and `postStartup` now connects at the current
agent API version so `TestWorkspaceAgent_Startup/OK` tracks it.
> Note: the pre-commit `enterprise/cli/.gen-golden` step could not run
in this environment (no Postgres: `open postgres connection: EOF`).
`cli/testdata/.gen-golden` passed; this change adds no serpent flags, so
there is no CLI help/golden drift.
<details>
<summary>Implementation plan</summary>
### Scope mapping (RFC -> DEVEX-664)
In scope (the CLI workspace-connecting subset of RFC phase 2):
- Req 1: generate a 16-byte session ID as 32-char lowercase hex.
- Req 2: add the session ID to every log the command makes for the
session.
- Req 3: attach the session ID to every API request via
`client_session_id` baggage, including the coordinate websocket
handshake. (The query-param fallback is browser-only; not applicable to
the CLI.)
- Req 4.1: attach the session ID to CLI network telemetry.
- Req 5 / 5.3: support `CODER_TRACE_SESSION_ID`; when set, use it
instead of generating.
### Resolved decisions
- Scope: opt-in per command via a `client_session_id` annotation;
opted-in set is `coder ssh`, `coder start`, `coder stop`, `coder
update`. Daemon commands are excluded.
- `CODER_TRACE_SESSION_ID`: when set, use the value verbatim; warn if it
is not canonical 32-char lowercase hex. When unset, generate a fresh ID.
- Existing telemetry = CLI network telemetry (tailnet `TelemetryEvent`);
requires a new proto field + plumbing and a proto minor version bump.
- Coordinate endpoint: set the session ID as baggage on the coordinate
handshake explicitly in `DialAgent` (header, not query param) so it is
logged server-side without relying on the CLI transport.
- Shared helper: add `tracing.NewSessionID()` and export the validator
as `tracing.ValidSessionID` for a single source of truth.
### Implementation
1. `coderd/tracing`: add `NewSessionID()` (16 random bytes,
hex-encoded); export `ValidSessionID`.
2. `cli`: resolve the ID from `CODER_TRACE_SESSION_ID` or generate;
attach `client_session_id` baggage to every request via
`wrapTransportWithSessionIDHeader`, gated on the
`annotationClientSessionID` opt-in; add it to the command log context.
3. `tailnet` + `codersdk/workspacesdk`: add `client_session_id` to
`TelemetryEvent`, an `Options.ClientSessionID`/`Conn.clientSessionID`
set in `newTelemetryEvent`, a `DialAgentOptions.ClientSessionID` plumbed
from the opted-in commands, and the coordinate-handshake baggage in
`DialAgent`.
</details>
---
_This PR was created by Coder Agents on behalf of @aqandrew._
`namedWorkspace` in `cli/root.go` parsed workspace identifiers with
`uuid.Parse` first and returned immediately on success, even when no
workspace had that UUID as its actual ID. This caused 404 errors for any
workspace whose name was a valid 32-char hex string (dashless UUID).
- Add `codersdk.ResolveWorkspace`: tries UUID lookup first, falls back
to name lookup on 404. `NameValid` guard skips the fallback for standard
dashed UUIDs (36 chars > 32-char name limit).
- Export `codersdk.SplitWorkspaceIdentifier`, replacing the duplicate
`splitNamedWorkspace` in `cli/root.go` (uses `strings.Cut`).
- Delete `namedWorkspace` from `cli/root.go`; all 28 call sites now use
`client.ResolveWorkspace` directly.
- Delete `namedWorkspace` and `splitNameAndOwner` from
`codersdk/toolsdk/bash.go`; inline `client.ResolveWorkspace`.
- Simplify `GetWorkspace` tool handler to a single `ResolveWorkspace`
call.
- Unit tests via httptest mock cover UUID, name, owner/name, UUID-like
fallback, not-found, server error, transport error, and invalid
identifier paths.
- Integration tests in `cli/show_test.go` and `codersdk/toolsdk` for
workspaces with UUID-like names.
> Generated with Coder Agents
## Problem
The CLI does not honor `default` values on template parameters in two
ways:
1. **`--use-parameter-defaults` rejects empty-string defaults.** The
check `parameterValue != ""` means `default = ""` in Terraform falls
through to an interactive prompt. In CI this causes an EOF error.
2. **`--use-parameter-defaults` only exists on `coder create`.** The
`start`, `update`, and `restart` commands never wire it through. SSH
auto-start passes empty `workspaceParameterFlags{}`, so users SSH-ing
into a stopped workspace with new template parameters get stuck in an
interactive prompt they cannot complete.
## Fix
### 1. Fix empty-string default detection and expose flag on all
commands
Replace `parameterValue != ""` with a check based on `!tvp.Required`. A
parameter with `Required==false` always has a valid default in
Terraform, even if that default is `""`. Also respect CLI defaults
provided via `--parameter-default`.
Move `--use-parameter-defaults` from a standalone option on `create`
into the shared `workspaceParameterFlags` struct. This exposes the flag
(and `CODER_WORKSPACE_USE_PARAMETER_DEFAULTS`) on `start`, `update`, and
`restart` via `allOptions()`. Wire it through
`buildWorkspaceStartRequest` so the resolver receives it.
### 2. SSH auto-start always uses defaults
Set `useParameterDefaults: true` on both `startWorkspace` calls in the
SSH auto-start path (initial start and the forbidden/upgrade fallback).
SSH is non-interactive and should never prompt.
Fixes https://linear.app/codercom/issue/DEVEX-180
Fixes https://github.com/coder/coder/issues/22272
<details><summary>Implementation notes</summary>
### Scoping decisions
- **`--yes` does not imply `--use-parameter-defaults`**: Making `--yes`
auto-accept defaults exposes a validation gap in the dynamic parameter
path (client-side validation happens during prompting, and skipping
prompts bypasses it). This is deferred to a follow-up that also
addresses `codersdk.ValidateWorkspaceBuildParameter` integration in the
resolver. Tracked in PLAT-114.
- **Explicit overrides always win**: `--parameter`,
`--rich-parameter-file`, and `--preset` are resolved in stages 1-5 of
the resolver, before `resolveWithInput` runs. No change needed for
precedence.
- **`!tvp.Required` vs `parameterValue != ""`**: The `Required` field is
set by the Terraform provider based on whether a `default` is present.
This is the canonical signal for "has a default," not the string value
itself.
</details>
> Generated with [Coder Agents](https://coder.com/agents)
Fixes#22030
## Problem
When a template has `require_active_version = true` and a workspace is
outdated, the web UI always shows "Update and start" as the **only**
button (for all users including admins), but `coder start` starts with
the old version. For admins, this silently succeeds on the stale
version. For non-admins, it goes through a clunky 403→retry path. This
also affects the VS Code extension, which calls `coder start --yes`
under the hood.
## Root Cause
`buildWorkspaceStartRequest()` in `cli/start.go` checks
`workspace.AutomaticUpdates == "always"` but ignores
`workspace.TemplateRequireActiveVersion`. The server-side autostart
already ORs both settings together:
```go
// coderd/autobuild/lifecycle_executor.go
func useActiveVersion(opts, ws) bool {
return opts.RequireActiveVersion || ws.AutomaticUpdates == "always"
}
```
The CLI was missing the `RequireActiveVersion` check.
## Fix
Add `workspace.TemplateRequireActiveVersion` to the existing OR
condition:
```go
// Before:
if workspace.AutomaticUpdates == codersdk.AutomaticUpdatesAlways || action == WorkspaceUpdate {
// After:
if workspace.AutomaticUpdates == codersdk.AutomaticUpdatesAlways || workspace.TemplateRequireActiveVersion || action == WorkspaceUpdate {
```
Now `coder start` and `coder restart` proactively use the active
template version when `require_active_version` is set, matching the web
UI and server autostart behavior. The 403→retry fallback remains as a
safety net but is no longer the primary path for any user.
## Testing
Updated `enterprise/cli/start_test.go` — all user types (owner, template
admin, ACL admin, group ACL admin, member) now expect the active version
when `require_active_version` is set, and verify the 403→retry message
does NOT appear.
Refactors the CLI to create the `*codersdk.Client` in the handlers. This is groundwork for changing the `rootCmd.InitClient()` to use the new `ClientOption`s.
It also improves variable locality, scoping the Client to the handler. This makes misuse less likely and reduces the memory allocations to just the command being executed, rather than allocating a Client for every command regardless of whether it is executed.
This PR introduces new build reason values to identify what type of
connection triggered a workspace build, helping to troubleshoot
workspace-related issues.
## Database Migration
Added migration 000349_extend_workspace_build_reason.up.sql that extends
the build_reason enum with new values:
```
dashboard, cli, ssh_connection, vscode_connection, jetbrains_connection
```
## Implementation
The build reason is specified through the API when creating new
workspace builds:
- Dashboard: Automatically sets reason to `dashboard` when users start
workspaces via the web interface
- CLI `start` command: Sets reason to `cli` when workspaces are started
via the command line
- CLI `ssh` command: Sets reason to ssh_connection when workspaces are
started due to SSH connections
- VS Code connections: Will be set to `vscode_connection` by the VS Code
extension through CLI hidden flag
(https://github.com/coder/vscode-coder/pull/550)
- JetBrains connections: Will be set to `jetbrains_connection` by the
Jetbrains Toolbox
(https://github.com/coder/coder-jetbrains-toolbox/pull/150) and
Jetbrains Gateway extension
(https://github.com/coder/jetbrains-coder/pull/561)
## UI Changes:
* Tooltip with reason in Build history
<img width="309" height="457" alt="image"
src="https://github.com/user-attachments/assets/bde8440b-bf3b-49a1-a244-ed7e8eb9763c"
/>
* Reason in Audit Logs Row tooltip
<img width="906" height="237" alt="image"
src="https://github.com/user-attachments/assets/ebbb62c7-cf07-4398-afbf-323c83fb6426"
/>
<img width="909" height="188" alt="image"
src="https://github.com/user-attachments/assets/1ddbab07-44bf-4dee-8867-b4e2cd56ae96"
/>
- Refactors `checkProvisioners` into `db2sdk.MatchedProvisioners`
- Adds a separate RBAC subject just for reading provisioner daemons
- Adds matched provisioners information to additional endpoints relating to
workspace builds and templates
-Updates existing unit tests for above endpoints
-Adds API endpoint for matched provisioners of template dry-run job
-Updates CLI to show warning when creating/starting/stopping/deleting
workspaces for which no provisoners are available
---------
Co-authored-by: Danny Kopping <danny@coder.com>
This PR aims to rename `build-option` to `ephemeral-parameters` based on
#10488 conversation.
`build-option` has been renamed `ephemeral-parameter` and can be used to
define a value for an ephemeral parameter in the template.
`build-options` has been renamed `prompt-ephemeral-parameters` and can
be used to prompt the user to put values for the ephemeral parameters in
the template.
---------
Co-authored-by: Mathias Fredriksson <mafredri@gmail.com>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: defelmnq <yvincent@coder.com>
* feat: influence parameter defaults through cli flag/env
Add a --parameter-default flag / CODER_RICH_PARAMETER_DEFAULT
environment variable which overrides default values suggested for
parameters.
This allows scripts or middleware wrapping the CLI to substitute
defaults for parameter values beyond those defined at the template
level. For example, Git repository/branch parameters can be given
defaults based on the current checkout, or default parameter values can
be parsed out of files inside the repo.
* Rename defaults arg to defaultOverrides
This change will improve over CLI performance and "snappiness" as well as
substantially reduce our test times. Preliminary benchmarks show
`coder server --help` times cut from 300ms to 120ms on my dogfood
instance.
The inefficiency of lipgloss disproportionately impacts our system, as all help
text for every command is generated whenever any command is invoked.
The `pretty` API could clean up a lot of the code (e.g., by replacing
complex string concatenations with Printf), but this commit is too
expansive as is so that work will be done in a follow up.
* chore: add /v2 to import module path
go mod requires semantic versioning with versions greater than 1.x
This was a mechanical update by running:
```
go install github.com/marwan-at-work/mod/cmd/mod@latest
mod upgrade
```
Migrate generated files to import /v2
* Fix gen
* feat: Add bufferring to provisioner job logs
This should improve overall build performance, and especially under load.
It removes the old `id` column on the `provisioner_job_logs` table
and replaces it with an auto-incrementing big integer to preserve order.
Funny enough, we never had to care about order before because inserts
would at minimum be 1ms different. Now they aren't, so the order needs
to be preserved.
* Fix log bufferring
* Fix frontend log streaming
* Fix JS test
* fix: Remove unused workspace routes in favor of list with filter
This consolidates the workspace routes into a single place.
It allows users to fetch a workspace by their username and
workspace name, which will be used by the frontend for routing.
* Fix RBAC
* Fix CLI usages
This changes all "coder workspace *" commands to root.
A few of these were already at the root, like SSH. The
inconsistency made for a confusing experience.
Workspace commands will be aliased at the top-level, so
"start" would easily be confused with starting a workspace.
Server seems like a more appropriate name too.
* Improve CLI documentation
* feat: Allow workspace resources to attach multiple agents
This enables a "kubernetes_pod" to attach multiple agents that
could be for multiple services. Each agent is required to have
a unique name, so SSH syntax is:
`coder ssh <workspace>.<agent>`
A resource can have zero agents too, they aren't required.
* Add tree view
* Improve table UI
* feat: Allow workspace resources to attach multiple agents
This enables a "kubernetes_pod" to attach multiple agents that
could be for multiple services. Each agent is required to have
a unique name, so SSH syntax is:
`coder ssh <workspace>.<agent>`
A resource can have zero agents too, they aren't required.
* Rename `tunnel` to `skip-tunnel`
This command was `true` by default, which causes
a confusing user experience.
* Add disclaimer about editing templates
* Add help to template create
* Improve workspace create flow
* Add end-to-end test for config-ssh
* Improve testing of config-ssh
* Fix workspace list
* Fix config ssh tests
* Update cli/configssh.go
Co-authored-by: Cian Johnston <public@cianjohnston.ie>
* Fix requested changes
* Remove socat requirement
* Fix resources not reading in TTY
Co-authored-by: Cian Johnston <public@cianjohnston.ie>