Files
coder/docs/reference/cli/update.md
T
dylanhuff-at-coder c856d5fb22 feat: accept template version IDs in --template-version (#30563)
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.
2026-10-14 08:52:36 -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 version of the workspace template, by name or ID. Defaults to the active version.

--stop-template-version

Type string

Stop with a version of the workspace template, by name or ID. 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.