feat(cli): add CLI support for listing presets #18910

ssncferreira · 2025-07-17T08:51:16Z

Description

This PR introduces a new list presets command to display presets correspondent to a template and template version.

Changes

The list presets command queries the available presets associated with a template and version, and outputs them in a readable format.

> coder templates versions presets list --help

USAGE:
  coder templates versions presets list [flags] <template> <version>

  List all the presets of the specified template version

OPTIONS:
  -O, --org string, $CODER_ORGANIZATION
          Select which organization (uuid or name) to use.

  -c, --column [name|parameters|default|prebuilds] (default: name,parameters,default,prebuilds)
          Columns to display in table output.

  -o, --output table|json (default: table)
          Output format.

Related PR: #18912 - please consider both PRs together as they’re part of the same workflow
Relates to issue: #16594

ssncferreira · 2025-07-17T09:11:15Z

cli/templateversionpresets.go

+		Long: FormatExamples(
+			Example{
+				Description: "List presets of a specific template version",
+				Command:     "coder templates versions presets list my-template my-template-version",


Currently, the coder templates versions presets list command requires both a template and a template version as positional arguments. However, it might be more user-friendly to only require the template name, and by default use the active template version.

We could also introduce a --template-version flag for cases where the user wants to explicitly list the presets of a specific template version.

Example usage:

# Lists presets for the active version of the template coder templates versions presets list my-template # Lists presets for a specific template version coder templates versions presets list my-template --template-version my-template-version

Let me know what you think

coder templates versions presets list is too verbose. Since we're requiring the template name / version as args/flags, there's no need to mention them in the command IMHO. coder presets should suffice.

I like coder presets. I recall seeing the term preset used in unrelated work in the frontend a few months ago. Perhaps just check that we won't have any namespacing conflicts if we shorten the command but otherwise I think its a good idea.

I think template version flag should be optional with the active version as a default.

As an aside, I now see the logic of going for templates versions presets list, since it doesn't give presets any special treatment (or more special than versions which they exist inside of). I think the reasoning should've been spelled out in the description.

I'll just keep quiet about the naming now 😆

dannykopping

Before I review further, I'd like to just address some confusion I have:

I'm not really understanding the point of this command.

Users need to be able to specify a preset when creating a workspace. Presumably this command is to allow a user to find out which presets exist so they can pass a value to coder create.

However: coder create provides an interactive and non-interactive mode. If you supply a --template argument it'll use that value, otherwise interactively list all templates and prompt the user to select one.

I think presets should have the same experience. In other words, we likely don't need this command at all but rather we can move the logic you've already implemented to coder create.

That will be the most consistent UX, I believe.

Let me put it another way: were we aware of the interactive nature of coder create? If so, did we decide to design it this way for a particular reason? I can see how this design might fall out of not knowing about the interactive mode.

dannykopping · 2025-07-17T10:17:06Z

cli/templateversionpresets.go

+		Long: FormatExamples(
+			Example{
+				Description: "List presets of a specific template version",
+				Command:     "coder templates versions presets list my-template my-template-version",


coder templates versions presets list is too verbose. Since we're requiring the template name / version as args/flags, there's no need to mention them in the command IMHO. coder presets should suffice.

ssncferreira · 2025-07-17T14:30:45Z

Before I review further, I'd like to just address some confusion I have:

I'm not really understanding the point of this command.

Users need to be able to specify a preset when creating a workspace. Presumably this command is to allow a user to find out which presets exist so they can pass a value to coder create.

Exactly! One of the goals of this command is to help users discover which presets are available for a given template version, especially in non-interactive, automated environments. The ability to apply a preset during workspace creation is implemented in #18912.

However: coder create provides an interactive and non-interactive mode. If you supply a --template argument it'll use that value, otherwise interactively list all templates and prompt the user to select one.

I think presets should have the same experience. In other words, we likely don't need this command at all but rather we can move the logic you've already implemented to coder create.

That will be the most consistent UX, I believe.

I agree that presets should follow the same behavior in both interactive and non-interactive modes. While the current implementation doesn't include interactive support for presets, I think it absolutely should. I shared some thoughts on this here: https://github.com/coder/coder/pull/18912/files#r2212832022 including ideas on default selection, backward compatibility with scripting workflows, and introducing a "none" option.

That said, I believe this command is still valuable in non-interactive scenarios, where users might need to fetch the name of a preset to use during workspace creation.

Let me put it another way: were we aware of the interactive nature of coder create? If so, did we decide to design it this way for a particular reason? I can see how this design might fall out of not knowing about the interactive mode.

Yes, we’re aware of that! And while the interactive flow is great for users running coder create manually, we also need to support non-interactive usage, which is common in customer scripts and automation.

In those cases, users typically rely on:

coder templates list to discover templates,
coder templates versions list to discover template versions,
and now, coder templates versions presets list to discover presets (but I am open to a less verbose command 😅 )

This new command fits naturally into that pattern. It allows users to look up presets that they can then pass via --preset to coder create, without requiring any prompts.

Right now, the CLI does not provide any information about presets, this command gives users a way to discover and inspect available presets for a given template and version.

SasSwart

Looks great @ssncferreira. Some minor comments. I'll check back once we've finalized the thread Danny opened.

SasSwart · 2025-07-17T16:29:33Z

codersdk/presets.go

@@ -15,6 +15,7 @@ type Preset struct {
 	Name       string
 	Parameters []PresetParameter
 	Default    bool
+	Prebuilds  *int


Consider clarifying the naming to communicate whether this is the desired number of prebuilds or the eligible number of prebuilds. I can see from elsewhere that its the desired number, but we've spoken in the past about showing how many prebuilds are eligible in the frontend before. Would be good to leave room for both.

SasSwart · 2025-07-17T16:32:16Z

coderd/presets.go

@@ -38,12 +39,21 @@ func (api *API) templateVersionPresets(rw http.ResponseWriter, r *http.Request)
 		return
 	}

+	getPrebuildInstances := func(desiredInstances sql.NullInt32) *int {


this name implies fetching from somewhere, but it only does a type conversion. perhaps consider a more descriptive name?

SasSwart · 2025-07-17T16:34:59Z

cli/templateversionpresets.go

+			}
+
+			if len(presets) == 0 {
+				return xerrors.Errorf("no presets found for template %q and template-version %q", template.Name, version.Name)


Should this be an error? Or just an empty list?

dannykopping · 2025-07-17T16:57:04Z

Before I review further, I'd like to just address some confusion I have:
I'm not really understanding the point of this command.
Users need to be able to specify a preset when creating a workspace. Presumably this command is to allow a user to find out which presets exist so they can pass a value to coder create.

Exactly! One of the goals of this command is to help users discover which presets are available for a given template version, especially in non-interactive, automated environments. The ability to apply a preset during workspace creation is implemented in #18912.

However: coder create provides an interactive and non-interactive mode. If you supply a --template argument it'll use that value, otherwise interactively list all templates and prompt the user to select one.
I think presets should have the same experience. In other words, we likely don't need this command at all but rather we can move the logic you've already implemented to coder create.
That will be the most consistent UX, I believe.

I agree that presets should follow the same behavior in both interactive and non-interactive modes. While the current implementation doesn't include interactive support for presets, I think it absolutely should. I shared some thoughts on this here: #18912 (files) including ideas on default selection, backward compatibility with scripting workflows, and introducing a "none" option.

That said, I believe this command is still valuable in non-interactive scenarios, where users might need to fetch the name of a preset to use during workspace creation.

Let me put it another way: were we aware of the interactive nature of coder create? If so, did we decide to design it this way for a particular reason? I can see how this design might fall out of not knowing about the interactive mode.

Yes, we’re aware of that! And while the interactive flow is great for users running coder create manually, we also need to support non-interactive usage, which is common in customer scripts and automation.

In those cases, users typically rely on:

coder templates list to discover templates,

coder templates versions list to discover template versions,

and now, coder templates versions presets list to discover presets (but I am open to a less verbose command 😅 )

This new command fits naturally into that pattern. It allows users to look up presets that they can then pass via --preset to coder create, without requiring any prompts.

Right now, the CLI does not provide any information about presets, this command gives users a way to discover and inspect available presets for a given template and version.

My apologies @ssncferreira! I didn't see the other PR, maybe mention it in the description of this one?
I thought this PR represented the full scope of what was to be done; makes a lot of sense in the wider context.
Thanks!

ssncferreira · 2025-07-17T17:33:06Z

My apologies @ssncferreira! I didn't see the other PR, maybe mention it in the description of this one? I thought this PR represented the full scope of what was to be done; makes a lot of sense in the wider context. Thanks!

No worries @dannykopping 😊 it was a totally fair point, and I really appreciate you taking the time to make sure the UX of the CLI is thoughtfully considered. I've updated the description of both PRs to reference each other for clarity. Let me know if anything else is unclear!

dannykopping

No concerns from my side except naming. LGTM!

dannykopping · 2025-07-21T08:37:39Z

cli/templateversionpresets.go

+func (r *RootCmd) templateVersionPresets() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:     "presets",
+		Short:   "Manage presets of the specified template version",


Nit: we're not managing anything right now, and probably never will from this command.

dannykopping · 2025-07-21T08:44:48Z

cli/templateversionpresets.go

+		Long: FormatExamples(
+			Example{
+				Description: "List presets of a specific template version",
+				Command:     "coder templates versions presets list my-template my-template-version",


As an aside, I now see the logic of going for templates versions presets list, since it doesn't give presets any special treatment (or more special than versions which they exist inside of). I think the reasoning should've been spelled out in the description.

I'll just keep quiet about the naming now 😆

dannykopping · 2025-07-21T09:17:13Z

cli/templateversionpresets.go

+	Name       string `json:"-" table:"name,default_sort"`
+	Parameters string `json:"-" table:"parameters"`
+	Default    bool   `json:"-" table:"default"`
+	Prebuilds  string `json:"-" table:"prebuilds"`


$ ./scripts/coder-dev.sh template versions presets list docker objective_elgamal6 NAME PARAMETERS DEFAULT PREBUILDS I Like GoLand cpu=2,jetbrains_ide=GO false 1 Some Like PyCharm jetbrains_ide=PY true 0

PREBUILDS is confusing here (maybe irrelevant?); we could rename it to DESIRED PREBUILT INSTANCES or similar.

feat(cli): add CLI support for listing presets

356fb39

github-actions bot assigned ssncferreira Jul 17, 2025

ssncferreira commented Jul 17, 2025

View reviewed changes

ssncferreira marked this pull request as ready for review July 17, 2025 09:12

ssncferreira requested a review from aslilac as a code owner July 17, 2025 09:13

ssncferreira requested review from SasSwart and dannykopping July 17, 2025 09:14

dannykopping requested changes Jul 17, 2025

View reviewed changes

ssncferreira mentioned this pull request Jul 17, 2025

feat(cli): add CLI support for creating a workspace with preset #18912

Open

SasSwart reviewed Jul 17, 2025

View reviewed changes

dannykopping self-requested a review July 17, 2025 16:56

dannykopping approved these changes Jul 21, 2025

View reviewed changes

feat(cli): add CLI support for listing presets #18910

Are you sure you want to change the base?

feat(cli): add CLI support for listing presets #18910

Conversation

ssncferreira commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dannykopping left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ssncferreira commented Jul 17, 2025

Uh oh!

SasSwart left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dannykopping commented Jul 17, 2025

Uh oh!

ssncferreira commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dannykopping left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ssncferreira commented Jul 17, 2025 •

edited

Loading

dannykopping left a comment •

edited

Loading

ssncferreira commented Jul 17, 2025 •

edited

Loading