Files
coder/docs/reference/cli/update.md
T
dylanhuff-at-coderandNick Vigilante b4d51012da feat: allow template version selection for workspace builds (#30199)
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>
2026-10-07 13:17:12 -07:00

3.9 KiB
Generated

title, description
title description
`coder update` Will update and start a given workspace if it is out of date. If the workspace is already running, it will be stopped first.

Will update and start a given workspace if it is out of date. If the workspace is already running, it will be stopped first.

Usage

coder update [flags] <workspace>

Description

Use --always-prompt to change the parameter values of the workspace.

Options

-y, --yes

Type bool

Bypass confirmation prompts.

--template-version

Type string

Start with a named version of the workspace template. Defaults to the active version.

--stop-template-version

Type string

Stop with a named version of the workspace template. Only applies when the workspace is started. Defaults to the workspace's current version.

--build-option

Type string-array
Environment $CODER_BUILD_OPTION

Build option value in the format "name=value".

--build-options

Type bool

Prompt for one-time build options defined with ephemeral parameters.

--ephemeral-parameter

Type string-array
Environment $CODER_EPHEMERAL_PARAMETER

Set the value of ephemeral parameters defined in the template. The format is "name=value".

--prompt-ephemeral-parameters

Type bool
Environment $CODER_PROMPT_EPHEMERAL_PARAMETERS

Prompt to set values of ephemeral parameters defined in the template. If a value has been set via --ephemeral-parameter, it will not be prompted for.

--parameter

Type string-array
Environment $CODER_RICH_PARAMETER

Rich parameter value in the format "name=value".

--rich-parameter-file

Type string
Environment $CODER_RICH_PARAMETER_FILE

Specify a file path with values for rich parameters defined in the template. The file should be in YAML format, containing key-value pairs for the parameters.

--parameter-default

Type string-array
Environment $CODER_RICH_PARAMETER_DEFAULT

Rich parameter default values in the format "name=value".

--use-parameter-defaults

Type bool
Environment $CODER_WORKSPACE_USE_PARAMETER_DEFAULTS

Automatically accept parameter defaults when no value is provided.

--always-prompt

Type bool

Always prompt all parameters. Does not pull parameter values from existing workspace.