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>
`coder update` stopped and restarted a running workspace without asking
and had no `-y`, while `coder restart` and the dashboard's update dialog
both confirm first.
It now asks for confirmation before stopping a running workspace, using
the dashboard's wording that updating can delete non-persistent data.
`-y` skips it, and also answers the existing "Enqueue another stop?"
prompt.
**Behavior change:** **New prompt; can break scripts.** `coder update`
on a running workspace without `-y` now blocks on stdin, or fails if
stdin is closed.
Stopped workspaces don't prompt.
Parameter prompts such as `--always-prompt` aren't affected by `-y`.
The [Update
workspaces](https://coder.com/docs/user-guides/workspace-management#update-with-the-cli)
guide now notes the prompt and `-y`.
<details>
<summary>Decisions</summary>
- Mirrors `coder restart`'s prompt pattern.
- Doc-check suggested a row in the 2.29 to 2.34 ESR upgrade guide. This
change ships after 2.34, so it's documented in the user guide instead.
</details>
Closes [CLI-34](https://linear.app/codercom/issue/CLI-34)
_This PR was generated by Coder Agents on behalf of @nickvigilante._
## 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
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.
Fixes https://github.com/coder/coder/issues/17840
NOTE: calling this out as a breaking change so that it is highly visible
in the changelog.
* CLI: Modifies `coder update` to stop the workspace if already running.
* UI: Modifies "update" button to always stop the workspace if already
running.
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>
* 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.