From 70cbef1a254c9205f205d0692459a138b88fc4cb Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 09:43:37 +0200
Subject: [PATCH 01/13] feat(stack): add support for container templates

Add `mw stack create`, which creates a container stack either empty or
from a container template via the create-stack API's `templateConfig`.
Template user inputs can be supplied non-interactively with repeatable
`--input name=value` flags; required inputs without a value or default
are prompted for interactively.

Also:
- add `mw stack list-templates` to discover available templates and IDs
- show the originating template in `mw stack list` (`templateId`)
- make `mw stack rm` work for any stack (template or not) by using the
  dedicated delete-stack API instead of the previous "empty the default
  stack" workaround
- deprecate `mw stack deploy --from-template` in favour of
  `mw stack create --from-template`

Closes #2048

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/stack.md                                 | 135 ++++++++++++++++
 src/commands/stack/create.tsx                 | 144 ++++++++++++++++++
 src/commands/stack/delete.ts                  |  29 ++--
 src/commands/stack/deploy.tsx                 |   7 +
 src/commands/stack/list-templates.ts          |  52 +++++++
 src/commands/stack/list.ts                    |   6 +
 .../resources/stack/template-inputs.test.ts   |  95 ++++++++++++
 src/lib/resources/stack/template-inputs.ts    |  69 +++++++++
 8 files changed, 523 insertions(+), 14 deletions(-)
 create mode 100644 src/commands/stack/create.tsx
 create mode 100644 src/commands/stack/list-templates.ts
 create mode 100644 src/lib/resources/stack/template-inputs.test.ts
 create mode 100644 src/lib/resources/stack/template-inputs.ts

diff --git a/docs/stack.md b/docs/stack.md
index af18d3b14..69572a54f 100644
--- a/docs/stack.md
+++ b/docs/stack.md
@@ -3,16 +3,86 @@
 
 Manage container stacks
 
+* [`mw stack create`](#mw-stack-create)
 * [`mw stack delete [STACK-ID]`](#mw-stack-delete-stack-id)
 * [`mw stack deploy`](#mw-stack-deploy)
 * [`mw stack list`](#mw-stack-list)
+* [`mw stack list-templates`](#mw-stack-list-templates)
 * [`mw stack ls`](#mw-stack-ls)
 * [`mw stack ps`](#mw-stack-ps)
 * [`mw stack rm [STACK-ID]`](#mw-stack-rm-stack-id)
 * [`mw stack set-update-schedule STACK-ID SCHEDULE`](#mw-stack-set-update-schedule-stack-id-schedule)
+* [`mw stack templates`](#mw-stack-templates)
 * [`mw stack unset-update-schedule STACK-ID`](#mw-stack-unset-update-schedule-stack-id)
 * [`mw stack up`](#mw-stack-up)
 
+## `mw stack create`
+
+Create a new container stack
+
+```
+USAGE
+  $ mw stack create -d <value> [--token <value>] [-p <value>] [-q] [--input <value>... --from-template <value>]
+    [-c]
+
+FLAGS
+  -c, --update-context         update the CLI context to use the newly created stack
+  -d, --description=<value>    (required) description of the stack
+  -p, --project-id=<value>     ID or short ID of a project; this flag is optional if a default project is set in the
+                               context
+  -q, --quiet                  suppress process output and only display a machine-readable summary
+      --from-template=<value>  ID of a container template to create the stack from
+      --input=<value>...       user input for a template, in 'name=value' format
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  Create a new container stack
+
+  Creates a new, empty container stack, or a stack based on a container template.
+
+  When --from-template is given, the referenced template may define user inputs.
+  These can be supplied non-interactively with one or more --input flags in
+  'name=value' format; any required inputs that are neither provided nor have a
+  default value are prompted for interactively.
+
+  Use "mw stack list-templates" to discover available templates and
+  their IDs.
+
+EXAMPLES
+  Create an empty stack
+
+    $ mw stack create --description "my stack"
+
+  Create a stack from a template, providing user inputs
+
+    $ mw stack create --description "my n8n" --from-template <template-id> --input DOMAIN=example.com --input \
+      ADMIN_EMAIL=admin@example.com
+
+FLAG DESCRIPTIONS
+  -p, --project-id=<value>  ID or short ID of a project; this flag is optional if a default project is set in the context
+
+    May contain a short ID or a full ID of a project; you can also use the "mw context set --project-id=<VALUE>" command
+    to persistently set a default project for all commands that accept this flag.
+
+  -q, --quiet  suppress process output and only display a machine-readable summary
+
+    This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
+    scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  --from-template=<value>  ID of a container template to create the stack from
+
+    When set, the stack is created from the given container template. Omit this flag to create an empty stack.
+
+  --input=<value>...  user input for a template, in 'name=value' format
+
+    May be repeated to provide multiple inputs. Only applicable together with --from-template. Required inputs that are
+    not provided (and have no default) are prompted for interactively.
+```
+
+
 ## `mw stack delete [STACK-ID]`
 
 Delete a container stack
@@ -90,6 +160,8 @@ FLAG DESCRIPTIONS
 
   --from-template=<value>  deploy from a GitHub template (e.g., mittwald/n8n)
 
+    DEPRECATED: use "mw stack create --from-template" instead. This flag uses an older, GitHub-based template mechanism.
+
     Fetch and deploy a stack from a GitHub template repository. Template names are automatically converted to repository
     names by prefixing "stack-template-" to the name part.
 
@@ -144,6 +216,37 @@ FLAG DESCRIPTIONS
 ```
 
 
+## `mw stack list-templates`
+
+List container templates that stacks can be created from.
+
+```
+USAGE
+  $ mw stack list-templates -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+    [--no-relative-dates] [--csv-separator ,|;]
+
+FLAGS
+  -o, --output=<option>         (required) [default: txt] output in a more machine friendly format
+                                <options: txt|json|yaml|csv|tsv>
+  -x, --extended                show extended information
+      --csv-separator=<option>  [default: ,] separator for CSV output (only relevant for CSV output)
+                                <options: ,|;>
+      --no-header               hide table header
+      --no-relative-dates       show dates in absolute format, not relative (only relevant for txt output)
+      --no-truncate             do not truncate output (only relevant for txt output)
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  List container templates that stacks can be created from.
+
+ALIASES
+  $ mw stack templates
+```
+
+
 ## `mw stack ls`
 
 List container stacks for a given project.
@@ -281,6 +384,36 @@ FLAG DESCRIPTIONS
 ```
 
 
+## `mw stack templates`
+
+List container templates that stacks can be created from.
+
+```
+USAGE
+  $ mw stack templates -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+    [--no-relative-dates] [--csv-separator ,|;]
+
+FLAGS
+  -o, --output=<option>         (required) [default: txt] output in a more machine friendly format
+                                <options: txt|json|yaml|csv|tsv>
+  -x, --extended                show extended information
+      --csv-separator=<option>  [default: ,] separator for CSV output (only relevant for CSV output)
+                                <options: ,|;>
+      --no-header               hide table header
+      --no-relative-dates       show dates in absolute format, not relative (only relevant for txt output)
+      --no-truncate             do not truncate output (only relevant for txt output)
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  List container templates that stacks can be created from.
+
+ALIASES
+  $ mw stack templates
+```
+
 ## `mw stack unset-update-schedule STACK-ID`
 
 Unset the update schedule of a container stack
@@ -353,6 +486,8 @@ FLAG DESCRIPTIONS
 
   --from-template=<value>  deploy from a GitHub template (e.g., mittwald/n8n)
 
+    DEPRECATED: use "mw stack create --from-template" instead. This flag uses an older, GitHub-based template mechanism.
+
     Fetch and deploy a stack from a GitHub template repository. Template names are automatically converted to repository
     names by prefixing "stack-template-" to the name part.
 
diff --git a/src/commands/stack/create.tsx b/src/commands/stack/create.tsx
new file mode 100644
index 000000000..1ce8e1f11
--- /dev/null
+++ b/src/commands/stack/create.tsx
@@ -0,0 +1,144 @@
+import { ExecRenderBaseCommand } from "../../lib/basecommands/ExecRenderBaseCommand.js";
+import {
+  makeProcessRenderer,
+  processFlags,
+} from "../../rendering/process/process_flags.js";
+import { ReactNode } from "react";
+import { assertStatus } from "@mittwald/api-client-commons";
+import { Success } from "../../rendering/react/components/Success.js";
+import { Value } from "../../rendering/react/components/Value.js";
+import { projectFlags } from "../../lib/resources/project/flags.js";
+import { Flags } from "@oclif/core";
+import type { MittwaldAPIV2 } from "@mittwald/api-client";
+import Context from "../../lib/context/Context.js";
+import { parseEnvironmentVariablesFromArray } from "../../lib/util/parser.js";
+import { collectTemplateUserInputs } from "../../lib/resources/stack/template-inputs.js";
+
+type ContainerCreateStack =
+  MittwaldAPIV2.Components.Schemas.ContainerCreateStack;
+
+type Result = {
+  stackId: string;
+};
+
+export class Create extends ExecRenderBaseCommand<typeof Create, Result> {
+  static summary = "Create a new container stack";
+  static description = `\
+Creates a new, empty container stack, or a stack based on a container template.
+
+When --from-template is given, the referenced template may define user inputs.
+These can be supplied non-interactively with one or more --input flags in
+'name=value' format; any required inputs that are neither provided nor have a
+default value are prompted for interactively.
+
+Use "<%= config.bin %> stack list-templates" to discover available templates and
+their IDs.`;
+
+  static examples = [
+    {
+      description: "Create an empty stack",
+      command: '<%= config.bin %> <%= command.id %> --description "my stack"',
+    },
+    {
+      description: "Create a stack from a template, providing user inputs",
+      command:
+        '<%= config.bin %> <%= command.id %> --description "my n8n" --from-template <template-id> --input DOMAIN=example.com --input ADMIN_EMAIL=admin@example.com',
+    },
+  ];
+
+  static flags = {
+    ...projectFlags,
+    ...processFlags,
+    description: Flags.string({
+      char: "d",
+      summary: "description of the stack",
+      required: true,
+    }),
+    "from-template": Flags.string({
+      summary: "ID of a container template to create the stack from",
+      description:
+        "When set, the stack is created from the given container template. Omit this flag to create an empty stack.",
+    }),
+    input: Flags.string({
+      summary: "user input for a template, in 'name=value' format",
+      description:
+        "May be repeated to provide multiple inputs. Only applicable together with --from-template. Required inputs that are not provided (and have no default) are prompted for interactively.",
+      multiple: true,
+      dependsOn: ["from-template"],
+    }),
+    "update-context": Flags.boolean({
+      char: "c",
+      summary: "update the CLI context to use the newly created stack",
+    }),
+  };
+
+  protected async exec(): Promise<Result> {
+    const process = makeProcessRenderer(
+      this.flags,
+      "Creating a new container stack",
+    );
+    const projectId = await this.withProjectId(Create);
+    const { description, "from-template": fromTemplate } = this.flags;
+
+    const data: ContainerCreateStack = { description };
+
+    if (fromTemplate) {
+      const template = await process.runStep(
+        "retrieving container template",
+        async () => {
+          const r = await this.apiClient.container.getTemplate({
+            templateId: fromTemplate,
+          });
+          assertStatus(r, 200);
+          return r.data;
+        },
+      );
+
+      const providedInputs = parseEnvironmentVariablesFromArray(
+        this.flags.input,
+      );
+      const userInputs = await collectTemplateUserInputs(
+        template.userInputs ?? [],
+        providedInputs,
+        process,
+      );
+
+      data.templateConfig = {
+        templateId: fromTemplate,
+        userInputs,
+      };
+    }
+
+    const { id: stackId } = await process.runStep(
+      "creating container stack",
+      async () => {
+        const r = await this.apiClient.container.createStack({
+          projectId,
+          data,
+        });
+        assertStatus(r, 201);
+        return r.data;
+      },
+    );
+
+    if (this.flags["update-context"]) {
+      await process.runStep("updating CLI context", async () => {
+        await new Context(this.apiClient, this.config).setStackId(stackId);
+      });
+    }
+
+    await process.complete(
+      <Success>
+        The container stack <Value>{stackId}</Value> was successfully created.
+      </Success>,
+    );
+
+    return { stackId };
+  }
+
+  protected render({ stackId }: Result): ReactNode {
+    if (this.flags.quiet) {
+      return stackId;
+    }
+  }
+}
diff --git a/src/commands/stack/delete.ts b/src/commands/stack/delete.ts
index a906faf1a..af1575408 100644
--- a/src/commands/stack/delete.ts
+++ b/src/commands/stack/delete.ts
@@ -24,23 +24,24 @@ export default class Delete extends DeleteBaseCommand<typeof Delete> {
     const stackResponse = await this.apiClient.container.getStack({ stackId });
     assertStatus(stackResponse, 200);
 
-    if (stackResponse.data.projectId !== stackResponse.data.id) {
-      throw new Error("not implemented");
-    }
-
-    const resp = await this.apiClient.container.declareStack({
-      stackId,
-      data: {
-        services: {},
-        volumes: {},
-      },
-    });
-
-    assertSuccess(resp);
-
     if (this.flags["with-volumes"]) {
+      // Empty the stack first so that its services release the volumes, then
+      // remove the volumes while the stack (and thus their delete endpoint)
+      // still exists.
+      const declareResp = await this.apiClient.container.declareStack({
+        stackId,
+        data: {
+          services: {},
+          volumes: {},
+        },
+      });
+      assertSuccess(declareResp);
+
       await this.deleteVolumes(stackId, stackResponse.data.projectId);
     }
+
+    const resp = await this.apiClient.container.deleteStack({ stackId });
+    assertSuccess(resp);
   }
 
   protected async deleteVolumes(
diff --git a/src/commands/stack/deploy.tsx b/src/commands/stack/deploy.tsx
index c59ec97ce..6522fa5b7 100644
--- a/src/commands/stack/deploy.tsx
+++ b/src/commands/stack/deploy.tsx
@@ -58,7 +58,14 @@ export class Deploy extends ExecRenderBaseCommand<typeof Deploy, DeployResult> {
     }),
     "from-template": Flags.string({
       summary: "deploy from a GitHub template (e.g., mittwald/n8n)",
+      deprecated: {
+        message:
+          'The "--from-template" flag of "stack deploy" is deprecated. Use "stack create --from-template" to create a stack from a container template instead.',
+        to: "stack create --from-template",
+      },
       description: `\
+DEPRECATED: use "mw stack create --from-template" instead. This flag uses an older, GitHub-based template mechanism.
+
 Fetch and deploy a stack from a GitHub template repository. Template names are automatically converted to repository names by prefixing "stack-template-" to the name part.
 
 For example, "mittwald/n8n" resolves to the repository "mittwald/stack-template-n8n". The command fetches both docker-compose.yml and .env files from the main branch.
diff --git a/src/commands/stack/list-templates.ts b/src/commands/stack/list-templates.ts
new file mode 100644
index 000000000..7cb67ec3b
--- /dev/null
+++ b/src/commands/stack/list-templates.ts
@@ -0,0 +1,52 @@
+import { Response, Simplify } from "@mittwald/api-client-commons";
+import { assertStatus, type MittwaldAPIV2 } from "@mittwald/api-client";
+import { ListBaseCommand } from "../../lib/basecommands/ListBaseCommand.js";
+import { ListColumns } from "../../rendering/formatter/Table.js";
+
+type Template = MittwaldAPIV2.Components.Schemas.ContainerTemplate;
+
+type ListResponse = Response<Template[]>;
+type ListItem = Simplify<Template>;
+
+export class ListTemplates extends ListBaseCommand<
+  typeof ListTemplates,
+  ListItem,
+  ListResponse
+> {
+  static description =
+    "List container templates that stacks can be created from.";
+  static aliases = ["stack:templates"];
+
+  static args = {};
+  static flags = {
+    ...ListBaseCommand.baseFlags,
+  };
+
+  public async getData(): Promise<ListResponse> {
+    const response = await this.apiClient.container.listTemplates();
+
+    assertStatus(response, 200);
+    return response;
+  }
+
+  protected getColumns(): ListColumns<ListItem> {
+    return {
+      id: {
+        header: "ID",
+      },
+      name: {
+        get(template) {
+          return template.name.en;
+        },
+      },
+      type: {},
+      version: {},
+      developer: {},
+      categories: {
+        get(template) {
+          return template.categories.join(", ");
+        },
+      },
+    };
+  }
+}
diff --git a/src/commands/stack/list.ts b/src/commands/stack/list.ts
index 66c456c17..3f057d599 100644
--- a/src/commands/stack/list.ts
+++ b/src/commands/stack/list.ts
@@ -34,6 +34,12 @@ export class List extends ListBaseCommand<typeof List, ListItem, ListResponse> {
     return {
       id,
       description: {},
+      template: {
+        header: "Template",
+        get(stack) {
+          return stack.templateId ?? "no template";
+        },
+      },
       services: {
         get(stack) {
           if (stack.services === undefined || stack.services.length === 0) {
diff --git a/src/lib/resources/stack/template-inputs.test.ts b/src/lib/resources/stack/template-inputs.test.ts
new file mode 100644
index 000000000..3beb19d30
--- /dev/null
+++ b/src/lib/resources/stack/template-inputs.test.ts
@@ -0,0 +1,95 @@
+import { describe, it, expect, jest } from "@jest/globals";
+import { collectTemplateUserInputs } from "./template-inputs.js";
+import type { MittwaldAPIV2 } from "@mittwald/api-client";
+import { ProcessRenderer } from "../../../rendering/process/process.js";
+
+type TemplateUserInputDefinition = NonNullable<
+  MittwaldAPIV2.Components.Schemas.ContainerTemplate["userInputs"]
+>[number];
+
+function makeRenderer(inputAnswers: string[] = []): {
+  renderer: ProcessRenderer;
+  addInput: jest.Mock;
+  addInfo: jest.Mock;
+} {
+  const answers = [...inputAnswers];
+  const addInput = jest.fn(() => Promise.resolve(answers.shift() ?? ""));
+  const addInfo = jest.fn();
+  const renderer = { addInput, addInfo } as unknown as ProcessRenderer;
+  return { renderer, addInput, addInfo };
+}
+
+describe("collectTemplateUserInputs", () => {
+  it("uses provided values over defaults and prompts", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      { name: "DOMAIN", required: true, defaultValue: "example.org" },
+    ];
+    const { renderer, addInput } = makeRenderer();
+
+    const result = await collectTemplateUserInputs(
+      definitions,
+      { DOMAIN: "example.com" },
+      renderer,
+    );
+
+    expect(result).toEqual([{ name: "DOMAIN", value: "example.com" }]);
+    expect(addInput).not.toHaveBeenCalled();
+  });
+
+  it("falls back to the default value for required inputs", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      { name: "PORT", required: true, defaultValue: "8080" },
+    ];
+    const { renderer, addInput } = makeRenderer();
+
+    const result = await collectTemplateUserInputs(definitions, {}, renderer);
+
+    expect(result).toEqual([{ name: "PORT", value: "8080" }]);
+    expect(addInput).not.toHaveBeenCalled();
+  });
+
+  it("prompts for required inputs without a value or default", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      {
+        name: "ADMIN_EMAIL",
+        required: true,
+        label: { en: "Admin e-mail", de: "Admin-E-Mail" },
+      },
+    ];
+    const { renderer, addInput } = makeRenderer(["admin@example.com"]);
+
+    const result = await collectTemplateUserInputs(definitions, {}, renderer);
+
+    expect(result).toEqual([
+      { name: "ADMIN_EMAIL", value: "admin@example.com" },
+    ]);
+    expect(addInput).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits optional inputs without a provided value", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      { name: "OPTIONAL", required: false, defaultValue: "from-template" },
+    ];
+    const { renderer } = makeRenderer();
+
+    const result = await collectTemplateUserInputs(definitions, {}, renderer);
+
+    expect(result).toEqual([]);
+  });
+
+  it("warns about inputs that are not defined by the template", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      { name: "KNOWN", required: false },
+    ];
+    const { renderer, addInfo } = makeRenderer();
+
+    await collectTemplateUserInputs(
+      definitions,
+      { KNOWN: "a", UNKNOWN: "b" },
+      renderer,
+    );
+
+    expect(addInfo).toHaveBeenCalledTimes(1);
+    expect(addInfo).toHaveBeenCalledWith(expect.stringContaining("UNKNOWN"));
+  });
+});
diff --git a/src/lib/resources/stack/template-inputs.ts b/src/lib/resources/stack/template-inputs.ts
new file mode 100644
index 000000000..cc9e4cce5
--- /dev/null
+++ b/src/lib/resources/stack/template-inputs.ts
@@ -0,0 +1,69 @@
+import type { MittwaldAPIV2 } from "@mittwald/api-client";
+import { ProcessRenderer } from "../../../rendering/process/process.js";
+
+type ContainerTemplate = MittwaldAPIV2.Components.Schemas.ContainerTemplate;
+type TemplateUserInputDefinition = NonNullable<
+  ContainerTemplate["userInputs"]
+>[number];
+
+export interface TemplateUserInput {
+  name: string;
+  value: string;
+}
+
+/**
+ * Resolves the concrete user inputs that should be sent to the API when
+ * creating a stack from a template.
+ *
+ * Values are resolved in the following order of precedence:
+ *
+ * 1. Values explicitly provided by the user (e.g. via `--input name=value`).
+ * 2. For required inputs without a provided value: the template's default value
+ *    (if present) or an interactive prompt.
+ *
+ * Optional inputs without a provided value are omitted entirely; the API fills
+ * them from the template defaults.
+ */
+export async function collectTemplateUserInputs(
+  definitions: TemplateUserInputDefinition[],
+  providedInputs: Record<string, string>,
+  renderer: ProcessRenderer,
+): Promise<TemplateUserInput[]> {
+  const knownNames = new Set(definitions.map((d) => d.name));
+  for (const name of Object.keys(providedInputs)) {
+    if (!knownNames.has(name)) {
+      renderer.addInfo(
+        `ignoring input '${name}', which is not defined by the template`,
+      );
+    }
+  }
+
+  const result: TemplateUserInput[] = [];
+
+  for (const definition of definitions) {
+    const providedValue = providedInputs[definition.name];
+    if (providedValue !== undefined) {
+      result.push({ name: definition.name, value: providedValue });
+      continue;
+    }
+
+    // Optional inputs are filled from template defaults by the API.
+    if (!definition.required) {
+      continue;
+    }
+
+    if (definition.defaultValue !== undefined) {
+      result.push({ name: definition.name, value: definition.defaultValue });
+      continue;
+    }
+
+    const label = definition.label?.en;
+    const suffix = label ? ` (${label})` : "";
+    const value = await renderer.addInput(
+      `enter value for required template input '${definition.name}'${suffix}`,
+    );
+    result.push({ name: definition.name, value });
+  }
+
+  return result;
+}

From bcfde2e5e314ecfa0fd190fbcb983ea8d07bb53e Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 10:32:42 +0200
Subject: [PATCH 02/13] feat(stack): move template listing to "stack templates
 list" and add filters

Rename `mw stack list-templates` to `mw stack templates list`, using a new
"templates" subtopic under "stack" (alias: `stack templates ls`).

Add `--category` and `--type` flags to filter the listing; both map to the
corresponding query parameters of the list-templates API and are omitted
from the request when unset.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package.json                                  |  7 +++-
 src/commands/stack/create.tsx                 |  2 +-
 .../{list-templates.ts => templates/list.ts}  | 37 ++++++++++++++-----
 3 files changed, 35 insertions(+), 11 deletions(-)
 rename src/commands/stack/{list-templates.ts => templates/list.ts} (50%)

diff --git a/package.json b/package.json
index ad8dde446..fa2a1d13b 100644
--- a/package.json
+++ b/package.json
@@ -252,7 +252,12 @@
         "description": "Manage SSH users of your projects"
       },
       "stack": {
-        "description": "Manage container stacks"
+        "description": "Manage container stacks",
+        "subtopics": {
+          "templates": {
+            "description": "Browse container templates that stacks can be created from"
+          }
+        }
       },
       "user": {
         "description": "Manage your own user account",
diff --git a/src/commands/stack/create.tsx b/src/commands/stack/create.tsx
index 1ce8e1f11..d78de7758 100644
--- a/src/commands/stack/create.tsx
+++ b/src/commands/stack/create.tsx
@@ -31,7 +31,7 @@ These can be supplied non-interactively with one or more --input flags in
 'name=value' format; any required inputs that are neither provided nor have a
 default value are prompted for interactively.
 
-Use "<%= config.bin %> stack list-templates" to discover available templates and
+Use "<%= config.bin %> stack templates list" to discover available templates and
 their IDs.`;
 
   static examples = [
diff --git a/src/commands/stack/list-templates.ts b/src/commands/stack/templates/list.ts
similarity index 50%
rename from src/commands/stack/list-templates.ts
rename to src/commands/stack/templates/list.ts
index 7cb67ec3b..679ba6fc0 100644
--- a/src/commands/stack/list-templates.ts
+++ b/src/commands/stack/templates/list.ts
@@ -1,29 +1,48 @@
 import { Response, Simplify } from "@mittwald/api-client-commons";
 import { assertStatus, type MittwaldAPIV2 } from "@mittwald/api-client";
-import { ListBaseCommand } from "../../lib/basecommands/ListBaseCommand.js";
-import { ListColumns } from "../../rendering/formatter/Table.js";
+import { ListBaseCommand } from "../../../lib/basecommands/ListBaseCommand.js";
+import { ListColumns } from "../../../rendering/formatter/Table.js";
+import { Flags } from "@oclif/core";
 
 type Template = MittwaldAPIV2.Components.Schemas.ContainerTemplate;
+type TemplateType = Template["type"];
 
 type ListResponse = Response<Template[]>;
 type ListItem = Simplify<Template>;
 
-export class ListTemplates extends ListBaseCommand<
-  typeof ListTemplates,
-  ListItem,
-  ListResponse
-> {
+export class List extends ListBaseCommand<typeof List, ListItem, ListResponse> {
   static description =
     "List container templates that stacks can be created from.";
-  static aliases = ["stack:templates"];
+  static aliases = ["stack:templates:ls"];
+
+  static examples = [
+    {
+      description: "List all templates of a given category",
+      command: "<%= config.bin %> <%= command.id %> --category cms",
+    },
+    {
+      description: "List only standalone templates",
+      command: "<%= config.bin %> <%= command.id %> --type standalone",
+    },
+  ];
 
   static args = {};
   static flags = {
     ...ListBaseCommand.baseFlags,
+    category: Flags.string({
+      summary: "only list templates belonging to the given category",
+    }),
+    type: Flags.custom<TemplateType>({
+      summary: "only list templates of the given type",
+      options: ["component", "standalone"],
+    })(),
   };
 
   public async getData(): Promise<ListResponse> {
-    const response = await this.apiClient.container.listTemplates();
+    const { category, type } = this.flags;
+    const response = await this.apiClient.container.listTemplates({
+      queryParameters: { category, type },
+    });
 
     assertStatus(response, 200);
     return response;

From a17ba51f65eb3d5f09f934c99eac8903636f59ee Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:33:47 +0000
Subject: [PATCH 03/13] chore: re-generate README

---
 docs/stack.md | 100 +++++++++++++++++++++++++++++++-------------------
 1 file changed, 62 insertions(+), 38 deletions(-)

diff --git a/docs/stack.md b/docs/stack.md
index 69572a54f..87f03adeb 100644
--- a/docs/stack.md
+++ b/docs/stack.md
@@ -7,12 +7,12 @@ Manage container stacks
 * [`mw stack delete [STACK-ID]`](#mw-stack-delete-stack-id)
 * [`mw stack deploy`](#mw-stack-deploy)
 * [`mw stack list`](#mw-stack-list)
-* [`mw stack list-templates`](#mw-stack-list-templates)
 * [`mw stack ls`](#mw-stack-ls)
 * [`mw stack ps`](#mw-stack-ps)
 * [`mw stack rm [STACK-ID]`](#mw-stack-rm-stack-id)
 * [`mw stack set-update-schedule STACK-ID SCHEDULE`](#mw-stack-set-update-schedule-stack-id-schedule)
-* [`mw stack templates`](#mw-stack-templates)
+* [`mw stack templates list`](#mw-stack-templates-list)
+* [`mw stack templates ls`](#mw-stack-templates-ls)
 * [`mw stack unset-update-schedule STACK-ID`](#mw-stack-unset-update-schedule-stack-id)
 * [`mw stack up`](#mw-stack-up)
 
@@ -48,7 +48,7 @@ DESCRIPTION
   'name=value' format; any required inputs that are neither provided nor have a
   default value are prompted for interactively.
 
-  Use "mw stack list-templates" to discover available templates and
+  Use "mw stack templates list" to discover available templates and
   their IDs.
 
 EXAMPLES
@@ -216,37 +216,6 @@ FLAG DESCRIPTIONS
 ```
 
 
-## `mw stack list-templates`
-
-List container templates that stacks can be created from.
-
-```
-USAGE
-  $ mw stack list-templates -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
-    [--no-relative-dates] [--csv-separator ,|;]
-
-FLAGS
-  -o, --output=<option>         (required) [default: txt] output in a more machine friendly format
-                                <options: txt|json|yaml|csv|tsv>
-  -x, --extended                show extended information
-      --csv-separator=<option>  [default: ,] separator for CSV output (only relevant for CSV output)
-                                <options: ,|;>
-      --no-header               hide table header
-      --no-relative-dates       show dates in absolute format, not relative (only relevant for txt output)
-      --no-truncate             do not truncate output (only relevant for txt output)
-
-AUTHENTICATION FLAGS
-  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
-                   tokens passed via this flag might be logged in your shell history.
-
-DESCRIPTION
-  List container templates that stacks can be created from.
-
-ALIASES
-  $ mw stack templates
-```
-
-
 ## `mw stack ls`
 
 List container stacks for a given project.
@@ -384,24 +353,70 @@ FLAG DESCRIPTIONS
 ```
 
 
-## `mw stack templates`
+## `mw stack templates list`
+
+List container templates that stacks can be created from.
+
+```
+USAGE
+  $ mw stack templates list -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+    [--no-relative-dates] [--csv-separator ,|;] [--category <value>] [--type component|standalone]
+
+FLAGS
+  -o, --output=<option>         (required) [default: txt] output in a more machine friendly format
+                                <options: txt|json|yaml|csv|tsv>
+  -x, --extended                show extended information
+      --category=<value>        only list templates belonging to the given category
+      --csv-separator=<option>  [default: ,] separator for CSV output (only relevant for CSV output)
+                                <options: ,|;>
+      --no-header               hide table header
+      --no-relative-dates       show dates in absolute format, not relative (only relevant for txt output)
+      --no-truncate             do not truncate output (only relevant for txt output)
+      --type=<option>           only list templates of the given type
+                                <options: component|standalone>
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  List container templates that stacks can be created from.
+
+ALIASES
+  $ mw stack templates ls
+
+EXAMPLES
+  List all templates of a given category
+
+    $ mw stack templates list --category cms
+
+  List only standalone templates
+
+    $ mw stack templates list --type standalone
+```
+
+
+## `mw stack templates ls`
 
 List container templates that stacks can be created from.
 
 ```
 USAGE
-  $ mw stack templates -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
-    [--no-relative-dates] [--csv-separator ,|;]
+  $ mw stack templates ls -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+    [--no-relative-dates] [--csv-separator ,|;] [--category <value>] [--type component|standalone]
 
 FLAGS
   -o, --output=<option>         (required) [default: txt] output in a more machine friendly format
                                 <options: txt|json|yaml|csv|tsv>
   -x, --extended                show extended information
+      --category=<value>        only list templates belonging to the given category
       --csv-separator=<option>  [default: ,] separator for CSV output (only relevant for CSV output)
                                 <options: ,|;>
       --no-header               hide table header
       --no-relative-dates       show dates in absolute format, not relative (only relevant for txt output)
       --no-truncate             do not truncate output (only relevant for txt output)
+      --type=<option>           only list templates of the given type
+                                <options: component|standalone>
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -411,7 +426,16 @@ DESCRIPTION
   List container templates that stacks can be created from.
 
 ALIASES
-  $ mw stack templates
+  $ mw stack templates ls
+
+EXAMPLES
+  List all templates of a given category
+
+    $ mw stack templates ls --category cms
+
+  List only standalone templates
+
+    $ mw stack templates ls --type standalone
 ```
 
 ## `mw stack unset-update-schedule STACK-ID`

From 72938b78032857977d64f7f744f2d15e6a93fb46 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 10:38:14 +0200
Subject: [PATCH 04/13] fix(stack): do not delete a project's default stack on
 "stack rm"

A project's default stack (identified by its ID matching the project ID)
cannot be removed, so it is emptied instead by declaring it without any
services or volumes; "--with-volumes" additionally removes its volumes.

Any other stack is removed with a single delete-stack call, without the
preceding declare that the previous implementation performed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/commands/stack/delete.ts | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/commands/stack/delete.ts b/src/commands/stack/delete.ts
index af1575408..33632cb1b 100644
--- a/src/commands/stack/delete.ts
+++ b/src/commands/stack/delete.ts
@@ -13,6 +13,8 @@ export default class Delete extends DeleteBaseCommand<typeof Delete> {
     ...DeleteBaseCommand.baseFlags,
     "with-volumes": Flags.boolean({
       summary: "also include remove volumes in removal",
+      description:
+        "Only relevant for a project's default stack, which is emptied instead of removed; the volumes of any other stack are removed together with the stack itself.",
       default: false,
       char: "v",
     }),
@@ -24,20 +26,25 @@ export default class Delete extends DeleteBaseCommand<typeof Delete> {
     const stackResponse = await this.apiClient.container.getStack({ stackId });
     assertStatus(stackResponse, 200);
 
-    if (this.flags["with-volumes"]) {
-      // Empty the stack first so that its services release the volumes, then
-      // remove the volumes while the stack (and thus their delete endpoint)
-      // still exists.
-      const declareResp = await this.apiClient.container.declareStack({
+    const { id, projectId } = stackResponse.data;
+
+    // A project's default stack cannot be removed; it is emptied instead by
+    // declaring it without any services or volumes.
+    if (id === projectId) {
+      const resp = await this.apiClient.container.declareStack({
         stackId,
         data: {
           services: {},
           volumes: {},
         },
       });
-      assertSuccess(declareResp);
+      assertSuccess(resp);
+
+      if (this.flags["with-volumes"]) {
+        await this.deleteVolumes(stackId, projectId);
+      }
 
-      await this.deleteVolumes(stackId, stackResponse.data.projectId);
+      return;
     }
 
     const resp = await this.apiClient.container.deleteStack({ stackId });

From 2405cf3d77d4ed89ffbf1031775a3ff8e570fc24 Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:39:34 +0000
Subject: [PATCH 05/13] chore: re-generate README

---
 docs/stack.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/stack.md b/docs/stack.md
index 87f03adeb..372db35fb 100644
--- a/docs/stack.md
+++ b/docs/stack.md
@@ -114,6 +114,11 @@ FLAG DESCRIPTIONS
 
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -v, --with-volumes  also include remove volumes in removal
+
+    Only relevant for a project's default stack, which is emptied instead of removed; the volumes of any other stack are
+    removed together with the stack itself.
 ```
 
 
@@ -320,6 +325,11 @@ FLAG DESCRIPTIONS
 
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -v, --with-volumes  also include remove volumes in removal
+
+    Only relevant for a project's default stack, which is emptied instead of removed; the volumes of any other stack are
+    removed together with the stack itself.
 ```
 
 ## `mw stack set-update-schedule STACK-ID SCHEDULE`

From b2ae8fe0123997cea82d2bf314012f68e0e7c492 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 10:43:59 +0200
Subject: [PATCH 06/13] feat(stack): add "stack templates install" to install a
 template into a stack

Adds a command wrapping the add-template-component API operation, which
adds a template's services and volumes to an already existing stack
instead of creating a new stack for it.

The stack is taken from the CLI context or --stack-id; template user
inputs are resolved with the same precedence as "stack create"
(provided -> template default -> interactive prompt).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/commands/stack/create.tsx            |   8 +-
 src/commands/stack/templates/install.tsx | 121 +++++++++++++++++++++++
 2 files changed, 123 insertions(+), 6 deletions(-)
 create mode 100644 src/commands/stack/templates/install.tsx

diff --git a/src/commands/stack/create.tsx b/src/commands/stack/create.tsx
index d78de7758..cac37bae8 100644
--- a/src/commands/stack/create.tsx
+++ b/src/commands/stack/create.tsx
@@ -26,13 +26,9 @@ export class Create extends ExecRenderBaseCommand<typeof Create, Result> {
   static description = `\
 Creates a new, empty container stack, or a stack based on a container template.
 
-When --from-template is given, the referenced template may define user inputs.
-These can be supplied non-interactively with one or more --input flags in
-'name=value' format; any required inputs that are neither provided nor have a
-default value are prompted for interactively.
+When --from-template is given, the referenced template may define user inputs. These can be supplied non-interactively with one or more --input flags in 'name=value' format; any required inputs that are neither provided nor have a default value are prompted for interactively.
 
-Use "<%= config.bin %> stack templates list" to discover available templates and
-their IDs.`;
+Use "<%= config.bin %> stack templates list" to discover available templates and their IDs. To add a template to a stack that already exists, use "<%= config.bin %> stack templates install" instead.`;
 
   static examples = [
     {
diff --git a/src/commands/stack/templates/install.tsx b/src/commands/stack/templates/install.tsx
new file mode 100644
index 000000000..788056833
--- /dev/null
+++ b/src/commands/stack/templates/install.tsx
@@ -0,0 +1,121 @@
+import { Args, Flags } from "@oclif/core";
+import { ExecRenderBaseCommand } from "../../../lib/basecommands/ExecRenderBaseCommand.js";
+import { ReactNode } from "react";
+import {
+  makeProcessRenderer,
+  processFlags,
+} from "../../../rendering/process/process_flags.js";
+import { Success } from "../../../rendering/react/components/Success.js";
+import { Value } from "../../../rendering/react/components/Value.js";
+import { stackFlags } from "../../../lib/resources/stack/flags.js";
+import { assertStatus } from "@mittwald/api-client";
+import assertSuccess from "../../../lib/apiutil/assert_success.js";
+import { parseEnvironmentVariablesFromArray } from "../../../lib/util/parser.js";
+import { collectTemplateUserInputs } from "../../../lib/resources/stack/template-inputs.js";
+
+type Result = {
+  stackId: string;
+  templateId: string;
+};
+
+export default class Install extends ExecRenderBaseCommand<
+  typeof Install,
+  Result
+> {
+  static summary = "Install a template into an existing container stack";
+  static description = `\
+Adds the services and volumes of a container template to a stack that already exists, instead of creating a new stack for it.
+
+This is intended for templates of type "component"; use "<%= config.bin %> stack create --from-template" to create a new stack from a standalone template.
+
+Template user inputs can be supplied non-interactively with one or more --input flags in 'name=value' format; any required inputs that are neither provided nor have a default value are prompted for interactively.`;
+
+  static examples = [
+    {
+      description: "Install a template into the stack from the current context",
+      command: "<%= config.bin %> <%= command.id %> <template-id>",
+    },
+    {
+      description: "Install a template into a specific stack, with inputs",
+      command:
+        "<%= config.bin %> <%= command.id %> <template-id> --stack-id <stack-id> --input DB_NAME=mydb",
+    },
+  ];
+
+  static args = {
+    "template-id": Args.string({
+      description: "ID of the container template to install",
+      required: true,
+    }),
+  };
+
+  static flags = {
+    ...stackFlags,
+    ...processFlags,
+    input: Flags.string({
+      summary: "user input for the template, in 'name=value' format",
+      description:
+        "May be repeated to provide multiple inputs. Required inputs that are not provided (and have no default) are prompted for interactively.",
+      multiple: true,
+    }),
+  };
+
+  protected async exec(): Promise<Result> {
+    const process = makeProcessRenderer(
+      this.flags,
+      "Installing template into container stack",
+    );
+    const stackId = await this.withStackId(Install);
+    const templateId = this.args["template-id"];
+
+    const template = await process.runStep(
+      "retrieving container template",
+      async () => {
+        const r = await this.apiClient.container.getTemplate({ templateId });
+        assertStatus(r, 200);
+        return r.data;
+      },
+    );
+
+    if (template.type !== "component") {
+      process.addInfo(
+        `template '${templateId}' is of type '${template.type}'; installing it into an existing stack may not be supported. Consider "${this.config.bin} stack create --from-template" instead.`,
+      );
+    }
+
+    const providedInputs = parseEnvironmentVariablesFromArray(this.flags.input);
+    const userInputs = await collectTemplateUserInputs(
+      template.userInputs ?? [],
+      providedInputs,
+      process,
+    );
+
+    await process.runStep("installing template into stack", async () => {
+      const r = await this.apiClient.container.addTemplateComponent({
+        stackId,
+        data: {
+          templateConfig: {
+            templateId,
+            userInputs,
+          },
+        },
+      });
+      assertSuccess(r);
+    });
+
+    await process.complete(
+      <Success>
+        The template <Value>{template.name.en}</Value> was successfully
+        installed into stack <Value>{stackId}</Value>.
+      </Success>,
+    );
+
+    return { stackId, templateId };
+  }
+
+  protected render({ stackId }: Result): ReactNode {
+    if (this.flags.quiet) {
+      return stackId;
+    }
+  }
+}

From 53e14c26ef5488c2173b84da5384652d17de35fb Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:45:10 +0000
Subject: [PATCH 07/13] chore: re-generate README

---
 docs/stack.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 64 insertions(+), 5 deletions(-)

diff --git a/docs/stack.md b/docs/stack.md
index 372db35fb..e3c38f14d 100644
--- a/docs/stack.md
+++ b/docs/stack.md
@@ -11,6 +11,7 @@ Manage container stacks
 * [`mw stack ps`](#mw-stack-ps)
 * [`mw stack rm [STACK-ID]`](#mw-stack-rm-stack-id)
 * [`mw stack set-update-schedule STACK-ID SCHEDULE`](#mw-stack-set-update-schedule-stack-id-schedule)
+* [`mw stack templates install TEMPLATE-ID`](#mw-stack-templates-install-template-id)
 * [`mw stack templates list`](#mw-stack-templates-list)
 * [`mw stack templates ls`](#mw-stack-templates-ls)
 * [`mw stack unset-update-schedule STACK-ID`](#mw-stack-unset-update-schedule-stack-id)
@@ -43,13 +44,12 @@ DESCRIPTION
 
   Creates a new, empty container stack, or a stack based on a container template.
 
-  When --from-template is given, the referenced template may define user inputs.
-  These can be supplied non-interactively with one or more --input flags in
-  'name=value' format; any required inputs that are neither provided nor have a
+  When --from-template is given, the referenced template may define user inputs. These can be supplied non-interactively
+  with one or more --input flags in 'name=value' format; any required inputs that are neither provided nor have a
   default value are prompted for interactively.
 
-  Use "mw stack templates list" to discover available templates and
-  their IDs.
+  Use "mw stack templates list" to discover available templates and their IDs. To add a template to a stack that already
+  exists, use "mw stack templates install" instead.
 
 EXAMPLES
   Create an empty stack
@@ -363,6 +363,65 @@ FLAG DESCRIPTIONS
 ```
 
 
+## `mw stack templates install TEMPLATE-ID`
+
+Install a template into an existing container stack
+
+```
+USAGE
+  $ mw stack templates install TEMPLATE-ID [--token <value>] [-s <value>] [-q] [--input <value>...]
+
+ARGUMENTS
+  TEMPLATE-ID  ID of the container template to install
+
+FLAGS
+  -q, --quiet             suppress process output and only display a machine-readable summary
+  -s, --stack-id=<value>  ID of a stack; this flag is optional if a default stack is set in the context
+      --input=<value>...  user input for the template, in 'name=value' format
+
+AUTHENTICATION FLAGS
+  --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
+                   tokens passed via this flag might be logged in your shell history.
+
+DESCRIPTION
+  Install a template into an existing container stack
+
+  Adds the services and volumes of a container template to a stack that already exists, instead of creating a new stack
+  for it.
+
+  This is intended for templates of type "component"; use "mw stack create --from-template" to create a new stack from a
+  standalone template.
+
+  Template user inputs can be supplied non-interactively with one or more --input flags in 'name=value' format; any
+  required inputs that are neither provided nor have a default value are prompted for interactively.
+
+EXAMPLES
+  Install a template into the stack from the current context
+
+    $ mw stack templates install <template-id>
+
+  Install a template into a specific stack, with inputs
+
+    $ mw stack templates install <template-id> --stack-id <stack-id> --input DB_NAME=mydb
+
+FLAG DESCRIPTIONS
+  -q, --quiet  suppress process output and only display a machine-readable summary
+
+    This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
+    scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -s, --stack-id=<value>  ID of a stack; this flag is optional if a default stack is set in the context
+
+    May contain a ID of a stack; you can also use the "mw context set --stack-id=<VALUE>" command to persistently set a
+    default stack for all commands that accept this flag.
+
+  --input=<value>...  user input for the template, in 'name=value' format
+
+    May be repeated to provide multiple inputs. Required inputs that are not provided (and have no default) are prompted
+    for interactively.
+```
+
+
 ## `mw stack templates list`
 
 List container templates that stacks can be created from.

From 8fd46f5ec7d3258a5c39294e400428b90efe7a28 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 10:47:53 +0200
Subject: [PATCH 08/13] refactor(stack): name the template subtopic in singular

All other topics use a singular name, so "stack templates list" and
"stack templates install" become "stack template list" and
"stack template install" (alias: "stack template ls").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 package.json                                           | 2 +-
 src/commands/stack/create.tsx                          | 2 +-
 src/commands/stack/{templates => template}/install.tsx | 0
 src/commands/stack/{templates => template}/list.ts     | 2 +-
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename src/commands/stack/{templates => template}/install.tsx (100%)
 rename src/commands/stack/{templates => template}/list.ts (97%)

diff --git a/package.json b/package.json
index fa2a1d13b..5aec85f20 100644
--- a/package.json
+++ b/package.json
@@ -254,7 +254,7 @@
       "stack": {
         "description": "Manage container stacks",
         "subtopics": {
-          "templates": {
+          "template": {
             "description": "Browse container templates that stacks can be created from"
           }
         }
diff --git a/src/commands/stack/create.tsx b/src/commands/stack/create.tsx
index cac37bae8..1cb0d847b 100644
--- a/src/commands/stack/create.tsx
+++ b/src/commands/stack/create.tsx
@@ -28,7 +28,7 @@ Creates a new, empty container stack, or a stack based on a container template.
 
 When --from-template is given, the referenced template may define user inputs. These can be supplied non-interactively with one or more --input flags in 'name=value' format; any required inputs that are neither provided nor have a default value are prompted for interactively.
 
-Use "<%= config.bin %> stack templates list" to discover available templates and their IDs. To add a template to a stack that already exists, use "<%= config.bin %> stack templates install" instead.`;
+Use "<%= config.bin %> stack template list" to discover available templates and their IDs. To add a template to a stack that already exists, use "<%= config.bin %> stack template install" instead.`;
 
   static examples = [
     {
diff --git a/src/commands/stack/templates/install.tsx b/src/commands/stack/template/install.tsx
similarity index 100%
rename from src/commands/stack/templates/install.tsx
rename to src/commands/stack/template/install.tsx
diff --git a/src/commands/stack/templates/list.ts b/src/commands/stack/template/list.ts
similarity index 97%
rename from src/commands/stack/templates/list.ts
rename to src/commands/stack/template/list.ts
index 679ba6fc0..3857b785c 100644
--- a/src/commands/stack/templates/list.ts
+++ b/src/commands/stack/template/list.ts
@@ -13,7 +13,7 @@ type ListItem = Simplify<Template>;
 export class List extends ListBaseCommand<typeof List, ListItem, ListResponse> {
   static description =
     "List container templates that stacks can be created from.";
-  static aliases = ["stack:templates:ls"];
+  static aliases = ["stack:template:ls"];
 
   static examples = [
     {

From 1d3100140f78b8dd8a46dd66f55e50d4ae52071a Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:49:09 +0000
Subject: [PATCH 09/13] chore: re-generate README

---
 docs/stack.md | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/docs/stack.md b/docs/stack.md
index e3c38f14d..961e01cea 100644
--- a/docs/stack.md
+++ b/docs/stack.md
@@ -11,9 +11,9 @@ Manage container stacks
 * [`mw stack ps`](#mw-stack-ps)
 * [`mw stack rm [STACK-ID]`](#mw-stack-rm-stack-id)
 * [`mw stack set-update-schedule STACK-ID SCHEDULE`](#mw-stack-set-update-schedule-stack-id-schedule)
-* [`mw stack templates install TEMPLATE-ID`](#mw-stack-templates-install-template-id)
-* [`mw stack templates list`](#mw-stack-templates-list)
-* [`mw stack templates ls`](#mw-stack-templates-ls)
+* [`mw stack template install TEMPLATE-ID`](#mw-stack-template-install-template-id)
+* [`mw stack template list`](#mw-stack-template-list)
+* [`mw stack template ls`](#mw-stack-template-ls)
 * [`mw stack unset-update-schedule STACK-ID`](#mw-stack-unset-update-schedule-stack-id)
 * [`mw stack up`](#mw-stack-up)
 
@@ -48,8 +48,8 @@ DESCRIPTION
   with one or more --input flags in 'name=value' format; any required inputs that are neither provided nor have a
   default value are prompted for interactively.
 
-  Use "mw stack templates list" to discover available templates and their IDs. To add a template to a stack that already
-  exists, use "mw stack templates install" instead.
+  Use "mw stack template list" to discover available templates and their IDs. To add a template to a stack that already
+  exists, use "mw stack template install" instead.
 
 EXAMPLES
   Create an empty stack
@@ -363,13 +363,13 @@ FLAG DESCRIPTIONS
 ```
 
 
-## `mw stack templates install TEMPLATE-ID`
+## `mw stack template install TEMPLATE-ID`
 
 Install a template into an existing container stack
 
 ```
 USAGE
-  $ mw stack templates install TEMPLATE-ID [--token <value>] [-s <value>] [-q] [--input <value>...]
+  $ mw stack template install TEMPLATE-ID [--token <value>] [-s <value>] [-q] [--input <value>...]
 
 ARGUMENTS
   TEMPLATE-ID  ID of the container template to install
@@ -398,11 +398,11 @@ DESCRIPTION
 EXAMPLES
   Install a template into the stack from the current context
 
-    $ mw stack templates install <template-id>
+    $ mw stack template install <template-id>
 
   Install a template into a specific stack, with inputs
 
-    $ mw stack templates install <template-id> --stack-id <stack-id> --input DB_NAME=mydb
+    $ mw stack template install <template-id> --stack-id <stack-id> --input DB_NAME=mydb
 
 FLAG DESCRIPTIONS
   -q, --quiet  suppress process output and only display a machine-readable summary
@@ -422,13 +422,13 @@ FLAG DESCRIPTIONS
 ```
 
 
-## `mw stack templates list`
+## `mw stack template list`
 
 List container templates that stacks can be created from.
 
 ```
 USAGE
-  $ mw stack templates list -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+  $ mw stack template list -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
     [--no-relative-dates] [--csv-separator ,|;] [--category <value>] [--type component|standalone]
 
 FLAGS
@@ -452,26 +452,26 @@ DESCRIPTION
   List container templates that stacks can be created from.
 
 ALIASES
-  $ mw stack templates ls
+  $ mw stack template ls
 
 EXAMPLES
   List all templates of a given category
 
-    $ mw stack templates list --category cms
+    $ mw stack template list --category cms
 
   List only standalone templates
 
-    $ mw stack templates list --type standalone
+    $ mw stack template list --type standalone
 ```
 
 
-## `mw stack templates ls`
+## `mw stack template ls`
 
 List container templates that stacks can be created from.
 
 ```
 USAGE
-  $ mw stack templates ls -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
+  $ mw stack template ls -o txt|json|yaml|csv|tsv [--token <value>] [-x] [--no-header] [--no-truncate]
     [--no-relative-dates] [--csv-separator ,|;] [--category <value>] [--type component|standalone]
 
 FLAGS
@@ -495,16 +495,16 @@ DESCRIPTION
   List container templates that stacks can be created from.
 
 ALIASES
-  $ mw stack templates ls
+  $ mw stack template ls
 
 EXAMPLES
   List all templates of a given category
 
-    $ mw stack templates ls --category cms
+    $ mw stack template ls --category cms
 
   List only standalone templates
 
-    $ mw stack templates ls --type standalone
+    $ mw stack template ls --type standalone
 ```
 
 ## `mw stack unset-update-schedule STACK-ID`

From dda95d16398c6a52ceeac9aab02e09a48ad2a381 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 10:56:08 +0200
Subject: [PATCH 10/13] fix(container,volume): stop hard-wiring commands to the
 default stack

"container run", "volume create" and "volume rm" derived the stack ID
from the project ID, so they could only ever address a project's default
stack. They now accept an optional --stack-id flag, resolved via the new
withStackIdOrDefault() helper: explicit flag, then the CLI context, and
only then the project's default stack. Existing invocations therefore
keep working unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/commands/container/run.tsx   | 12 ++++++++-
 src/commands/volume/create.tsx   | 14 ++++++++--
 src/commands/volume/delete.tsx   | 14 ++++++++--
 src/lib/resources/stack/flags.ts | 45 +++++++++++++++++++++++++++++++-
 4 files changed, 79 insertions(+), 6 deletions(-)

diff --git a/src/commands/container/run.tsx b/src/commands/container/run.tsx
index 018dc9793..3bc8b6c4b 100644
--- a/src/commands/container/run.tsx
+++ b/src/commands/container/run.tsx
@@ -6,6 +6,10 @@ import {
   processFlags,
 } from "../../rendering/process/process_flags.js";
 import { projectFlags } from "../../lib/resources/project/flags.js";
+import {
+  optionalStackFlags,
+  withStackIdOrDefault,
+} from "../../lib/resources/stack/flags.js";
 import dockerNames from "docker-names";
 import { assertStatus, MittwaldAPIV2 } from "@mittwald/api-client";
 import {
@@ -43,6 +47,7 @@ export class Run extends ExecRenderBaseCommand<typeof Run, Result> {
   static flags = {
     ...processFlags,
     ...projectFlags,
+    ...optionalStackFlags,
     env: Flags.string({
       summary: "set environment variables in the container",
       description:
@@ -158,7 +163,12 @@ export class Run extends ExecRenderBaseCommand<typeof Run, Result> {
     const p = makeProcessRenderer(this.flags, "Creating a container");
 
     const projectId = await this.withProjectId(Run);
-    const stackId = projectId;
+    const stackId = await withStackIdOrDefault(
+      this.apiClient,
+      this.flags,
+      projectId,
+      this.config,
+    );
     const serviceName = this.getServiceName();
 
     const { image, meta: imageMeta } = await p.runStep(
diff --git a/src/commands/volume/create.tsx b/src/commands/volume/create.tsx
index 79b1fa1ec..fce5e705c 100644
--- a/src/commands/volume/create.tsx
+++ b/src/commands/volume/create.tsx
@@ -9,6 +9,10 @@ import { assertStatus } from "@mittwald/api-client-commons";
 import { Success } from "../../rendering/react/components/Success.js";
 import { Value } from "../../rendering/react/components/Value.js";
 import { projectFlags } from "../../lib/resources/project/flags.js";
+import {
+  optionalStackFlags,
+  withStackIdOrDefault,
+} from "../../lib/resources/stack/flags.js";
 
 type Result = {
   volumeName: string;
@@ -18,10 +22,11 @@ type Result = {
 export class Create extends ExecRenderBaseCommand<typeof Create, Result> {
   static summary = "Create a new volume";
   static description =
-    "Creates a new named volume in the project stack. The volume will be available for use by containers.";
+    "Creates a new named volume in a container stack. The volume will be available for use by containers of that stack.";
 
   static flags = {
     ...projectFlags,
+    ...optionalStackFlags,
     ...processFlags,
   };
 
@@ -35,7 +40,12 @@ export class Create extends ExecRenderBaseCommand<typeof Create, Result> {
   protected async exec(): Promise<Result> {
     const process = makeProcessRenderer(this.flags, "Creating a new volume");
     const projectId = await this.withProjectId(Create);
-    const stackId = projectId; // In mStudio, project and stack are the same for volumes
+    const stackId = await withStackIdOrDefault(
+      this.apiClient,
+      this.flags,
+      projectId,
+      this.config,
+    );
     const { name: volumeName } = this.args;
 
     // Get current stack state
diff --git a/src/commands/volume/delete.tsx b/src/commands/volume/delete.tsx
index da37e1747..c85fb1310 100644
--- a/src/commands/volume/delete.tsx
+++ b/src/commands/volume/delete.tsx
@@ -9,6 +9,10 @@ import { assertStatus } from "@mittwald/api-client-commons";
 import { Success } from "../../rendering/react/components/Success.js";
 import { Value } from "../../rendering/react/components/Value.js";
 import { projectFlags } from "../../lib/resources/project/flags.js";
+import {
+  optionalStackFlags,
+  withStackIdOrDefault,
+} from "../../lib/resources/stack/flags.js";
 
 type Result = {
   volumeName: string;
@@ -17,12 +21,13 @@ type Result = {
 export class Delete extends ExecRenderBaseCommand<typeof Delete, Result> {
   static summary = "Remove one or more volumes";
   static description =
-    "Removes named volumes from the project stack. Be careful as this will permanently delete the volume data.";
+    "Removes named volumes from a container stack. Be careful as this will permanently delete the volume data.";
 
   static aliases = ["volume:rm"];
 
   static flags = {
     ...projectFlags,
+    ...optionalStackFlags,
     ...processFlags,
     force: Flags.boolean({
       summary: "force removal without confirmation",
@@ -41,7 +46,12 @@ export class Delete extends ExecRenderBaseCommand<typeof Delete, Result> {
   protected async exec(): Promise<Result> {
     const process = makeProcessRenderer(this.flags, "Removing volume");
     const projectId = await this.withProjectId(Delete);
-    const stackId = projectId; // In mStudio, project and stack are the same for volumes
+    const stackId = await withStackIdOrDefault(
+      this.apiClient,
+      this.flags,
+      projectId,
+      this.config,
+    );
     const { name: volumeName } = this.args;
 
     // Get current stack state
diff --git a/src/lib/resources/stack/flags.ts b/src/lib/resources/stack/flags.ts
index 528ed783a..9328c0878 100644
--- a/src/lib/resources/stack/flags.ts
+++ b/src/lib/resources/stack/flags.ts
@@ -1,5 +1,20 @@
 import FlagSetBuilder from "../../context/FlagSetBuilder.js";
-import { assertStatus } from "@mittwald/api-client";
+import { assertStatus, MittwaldAPIV2Client } from "@mittwald/api-client";
+import { Config, Flags } from "@oclif/core";
+import Context from "../../context/Context.js";
+
+/**
+ * Stack selection for commands that operate on a project's default stack unless
+ * told otherwise. Resolve these with `withStackIdOrDefault`.
+ */
+export const optionalStackFlags = {
+  "stack-id": Flags.string({
+    char: "s",
+    summary: "ID of the stack to operate on",
+    description:
+      "If omitted, the stack set in the CLI context is used; when that is not set either, the project's default stack is used.",
+  }),
+};
 
 export const {
   flags: stackFlags,
@@ -23,3 +38,31 @@ export const {
     return null;
   },
 }).build();
+
+/**
+ * Resolves the stack that a project-scoped command should operate on.
+ *
+ * Unlike `withStackId`, this does not fail when no stack can be determined; it
+ * falls back to the project's default stack (whose ID is identical to the
+ * project ID). This keeps commands that used to be hard-wired to the default
+ * stack working as before, while allowing any other stack to be addressed
+ * explicitly.
+ */
+export async function withStackIdOrDefault(
+  apiClient: MittwaldAPIV2Client,
+  flags: { [k: string]: unknown },
+  projectId: string,
+  cfg: Config,
+): Promise<string> {
+  const fromFlags = flags["stack-id"];
+  if (typeof fromFlags === "string") {
+    return fromFlags;
+  }
+
+  const fromContext = await new Context(apiClient, cfg).stackId();
+  if (fromContext) {
+    return fromContext.value;
+  }
+
+  return projectId;
+}

From c8ac227f5e2e908105a4a6db9b88f3863c6d61c2 Mon Sep 17 00:00:00 2001
From: martin-helmich <2538958+martin-helmich@users.noreply.github.com>
Date: Wed, 29 Jul 2026 08:57:16 +0000
Subject: [PATCH 11/13] chore: re-generate README

---
 docs/container.md |  6 ++++++
 docs/volume.md    | 30 ++++++++++++++++++++++++------
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/docs/container.md b/docs/container.md
index a2e2bcb92..1e58f35c0 100644
--- a/docs/container.md
+++ b/docs/container.md
@@ -531,6 +531,7 @@ FLAGS
   -p, --project-id=<value>   ID or short ID of a project; this flag is optional if a default project is set in the
                              context
   -q, --quiet                suppress process output and only display a machine-readable summary
+  -s, --stack-id=<value>     ID of the stack to operate on
   -v, --volume=<value>...    bind mount a volume to the container
       --cpus=<value>         set CPU limit for the container
       --create-volumes       automatically create named volumes that do not exist
@@ -568,6 +569,11 @@ FLAG DESCRIPTIONS
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
 
+  -s, --stack-id=<value>  ID of the stack to operate on
+
+    If omitted, the stack set in the CLI context is used; when that is not set either, the project's default stack is
+    used.
+
   -v, --volume=<value>...  bind mount a volume to the container
 
     This flag can be used to add volume mounts to the container. It can be used multiple times to mount multiple
diff --git a/docs/volume.md b/docs/volume.md
index 6b666c1b4..8937d06d3 100644
--- a/docs/volume.md
+++ b/docs/volume.md
@@ -15,7 +15,7 @@ Create a new volume
 
 ```
 USAGE
-  $ mw volume create NAME [--token <value>] [-p <value>] [-q]
+  $ mw volume create NAME [--token <value>] [-p <value>] [-s <value>] [-q]
 
 ARGUMENTS
   NAME  name of the volume to create
@@ -24,6 +24,7 @@ FLAGS
   -p, --project-id=<value>  ID or short ID of a project; this flag is optional if a default project is set in the
                             context
   -q, --quiet               suppress process output and only display a machine-readable summary
+  -s, --stack-id=<value>    ID of the stack to operate on
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -32,7 +33,7 @@ AUTHENTICATION FLAGS
 DESCRIPTION
   Create a new volume
 
-  Creates a new named volume in the project stack. The volume will be available for use by containers.
+  Creates a new named volume in a container stack. The volume will be available for use by containers of that stack.
 
 FLAG DESCRIPTIONS
   -p, --project-id=<value>  ID or short ID of a project; this flag is optional if a default project is set in the context
@@ -44,6 +45,11 @@ FLAG DESCRIPTIONS
 
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -s, --stack-id=<value>  ID of the stack to operate on
+
+    If omitted, the stack set in the CLI context is used; when that is not set either, the project's default stack is
+    used.
 ```
 
 
@@ -53,7 +59,7 @@ Remove one or more volumes
 
 ```
 USAGE
-  $ mw volume delete NAME [--token <value>] [-p <value>] [-q] [-f]
+  $ mw volume delete NAME [--token <value>] [-p <value>] [-s <value>] [-q] [-f]
 
 ARGUMENTS
   NAME  name of the volume to remove
@@ -63,6 +69,7 @@ FLAGS
   -p, --project-id=<value>  ID or short ID of a project; this flag is optional if a default project is set in the
                             context
   -q, --quiet               suppress process output and only display a machine-readable summary
+  -s, --stack-id=<value>    ID of the stack to operate on
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -71,7 +78,7 @@ AUTHENTICATION FLAGS
 DESCRIPTION
   Remove one or more volumes
 
-  Removes named volumes from the project stack. Be careful as this will permanently delete the volume data.
+  Removes named volumes from a container stack. Be careful as this will permanently delete the volume data.
 
 ALIASES
   $ mw volume rm
@@ -86,6 +93,11 @@ FLAG DESCRIPTIONS
 
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -s, --stack-id=<value>  ID of the stack to operate on
+
+    If omitted, the stack set in the CLI context is used; when that is not set either, the project's default stack is
+    used.
 ```
 
 
@@ -172,7 +184,7 @@ Remove one or more volumes
 
 ```
 USAGE
-  $ mw volume rm NAME [--token <value>] [-p <value>] [-q] [-f]
+  $ mw volume rm NAME [--token <value>] [-p <value>] [-s <value>] [-q] [-f]
 
 ARGUMENTS
   NAME  name of the volume to remove
@@ -182,6 +194,7 @@ FLAGS
   -p, --project-id=<value>  ID or short ID of a project; this flag is optional if a default project is set in the
                             context
   -q, --quiet               suppress process output and only display a machine-readable summary
+  -s, --stack-id=<value>    ID of the stack to operate on
 
 AUTHENTICATION FLAGS
   --token=<value>  API token to use for authentication (overrides environment and config file). NOTE: watch out that
@@ -190,7 +203,7 @@ AUTHENTICATION FLAGS
 DESCRIPTION
   Remove one or more volumes
 
-  Removes named volumes from the project stack. Be careful as this will permanently delete the volume data.
+  Removes named volumes from a container stack. Be careful as this will permanently delete the volume data.
 
 ALIASES
   $ mw volume rm
@@ -205,4 +218,9 @@ FLAG DESCRIPTIONS
 
     This flag controls if you want to see the process output or only a summary. When using mw non-interactively (e.g. in
     scripts), you can use this flag to easily get the IDs of created resources for further processing.
+
+  -s, --stack-id=<value>  ID of the stack to operate on
+
+    If omitted, the stack set in the CLI context is used; when that is not set either, the project's default stack is
+    used.
 ```

From 1ca36decf5ba39d9f034061fdc1c9e380738c10a Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 11:10:19 +0200
Subject: [PATCH 12/13] feat(stack): mask prompts for sensitive template inputs

Values whose name suggests a password, secret, token, API key, private
key or credential are now prompted for with a masked input, so they are
neither echoed while typing nor shown in the process summary.

The container template API does not mark user inputs as sensitive, so
this is based on a heuristic over the input name. The same heuristic is
applied to "__PROMPT__" environment variables in the compose-based
deployment path, which previously always prompted unmasked.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/lib/resources/stack/env.ts                |  3 +-
 .../resources/stack/template-inputs.test.ts   | 22 +++++++++++
 src/lib/resources/stack/template-inputs.ts    |  2 +
 src/lib/util/isSensitiveName.test.ts          | 32 ++++++++++++++++
 src/lib/util/isSensitiveName.ts               | 38 +++++++++++++++++++
 5 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 src/lib/util/isSensitiveName.test.ts
 create mode 100644 src/lib/util/isSensitiveName.ts

diff --git a/src/lib/resources/stack/env.ts b/src/lib/resources/stack/env.ts
index 7fcf15e0a..1fd88a724 100644
--- a/src/lib/resources/stack/env.ts
+++ b/src/lib/resources/stack/env.ts
@@ -3,6 +3,7 @@ import { pathExists } from "../../util/fs/pathExists.js";
 import { ProcessRenderer } from "../../../rendering/process/process.js";
 import { getRandomValues } from "node:crypto";
 import { parseEnvironmentVariablesFromStr } from "../../util/parser.js";
+import { isSensitiveName } from "../../util/isSensitiveName.js";
 
 export async function collectEnvironment(
   base: NodeJS.ProcessEnv,
@@ -36,7 +37,7 @@ export async function fillMissingEnvironmentVariables(
     if (value === "__PROMPT__") {
       output[key] = await renderer.addInput(
         `enter value for environment variable ${key}`,
-        false,
+        isSensitiveName(key),
       );
     }
 
diff --git a/src/lib/resources/stack/template-inputs.test.ts b/src/lib/resources/stack/template-inputs.test.ts
index 3beb19d30..7f1f257aa 100644
--- a/src/lib/resources/stack/template-inputs.test.ts
+++ b/src/lib/resources/stack/template-inputs.test.ts
@@ -64,6 +64,28 @@ describe("collectTemplateUserInputs", () => {
       { name: "ADMIN_EMAIL", value: "admin@example.com" },
     ]);
     expect(addInput).toHaveBeenCalledTimes(1);
+    expect(addInput).toHaveBeenCalledWith(expect.any(String), false);
+  });
+
+  it("masks the prompt for sensitive inputs", async () => {
+    const definitions: TemplateUserInputDefinition[] = [
+      { name: "ADMIN_PASSWORD", required: true },
+      { name: "ADMIN_EMAIL", required: true },
+    ];
+    const { renderer, addInput } = makeRenderer(["s3cret", "a@example.com"]);
+
+    await collectTemplateUserInputs(definitions, {}, renderer);
+
+    expect(addInput).toHaveBeenNthCalledWith(
+      1,
+      expect.stringContaining("ADMIN_PASSWORD"),
+      true,
+    );
+    expect(addInput).toHaveBeenNthCalledWith(
+      2,
+      expect.stringContaining("ADMIN_EMAIL"),
+      false,
+    );
   });
 
   it("omits optional inputs without a provided value", async () => {
diff --git a/src/lib/resources/stack/template-inputs.ts b/src/lib/resources/stack/template-inputs.ts
index cc9e4cce5..65c906df5 100644
--- a/src/lib/resources/stack/template-inputs.ts
+++ b/src/lib/resources/stack/template-inputs.ts
@@ -1,5 +1,6 @@
 import type { MittwaldAPIV2 } from "@mittwald/api-client";
 import { ProcessRenderer } from "../../../rendering/process/process.js";
+import { isSensitiveName } from "../../util/isSensitiveName.js";
 
 type ContainerTemplate = MittwaldAPIV2.Components.Schemas.ContainerTemplate;
 type TemplateUserInputDefinition = NonNullable<
@@ -61,6 +62,7 @@ export async function collectTemplateUserInputs(
     const suffix = label ? ` (${label})` : "";
     const value = await renderer.addInput(
       `enter value for required template input '${definition.name}'${suffix}`,
+      isSensitiveName(definition.name),
     );
     result.push({ name: definition.name, value });
   }
diff --git a/src/lib/util/isSensitiveName.test.ts b/src/lib/util/isSensitiveName.test.ts
new file mode 100644
index 000000000..dcf87d141
--- /dev/null
+++ b/src/lib/util/isSensitiveName.test.ts
@@ -0,0 +1,32 @@
+import { describe, it, expect } from "@jest/globals";
+import { isSensitiveName } from "./isSensitiveName.js";
+
+describe("isSensitiveName", () => {
+  it.each([
+    "PASSWORD",
+    "DB_PASSWORD",
+    "db-password",
+    "dbPassword",
+    "MYSQL_ROOT_PASSWD",
+    "GPG_PASSPHRASE",
+    "APP_SECRET",
+    "ACCESS_TOKEN",
+    "API_KEY",
+    "apiKey",
+    "PRIVATE_KEY",
+    "REGISTRY_CREDENTIALS",
+  ])("treats '%s' as sensitive", (name) => {
+    expect(isSensitiveName(name)).toBe(true);
+  });
+
+  it.each([
+    "DOMAIN",
+    "ADMIN_EMAIL",
+    "PORT",
+    "TIMEZONE",
+    "DB_NAME",
+    "PUBLIC_URL",
+  ])("treats '%s' as not sensitive", (name) => {
+    expect(isSensitiveName(name)).toBe(false);
+  });
+});
diff --git a/src/lib/util/isSensitiveName.ts b/src/lib/util/isSensitiveName.ts
new file mode 100644
index 000000000..f54071254
--- /dev/null
+++ b/src/lib/util/isSensitiveName.ts
@@ -0,0 +1,38 @@
+/**
+ * Substrings that indicate that a value is sensitive and should therefore be
+ * masked when the user is prompted for it.
+ *
+ * Deliberately errs on the side of masking: masking a harmless value is a minor
+ * annoyance, whereas echoing a password to the terminal (and into the process
+ * summary) is not.
+ */
+const sensitiveSubstrings = [
+  "password",
+  "passwd",
+  "passphrase",
+  "secret",
+  "token",
+  "apikey",
+  "privatekey",
+  "credential",
+];
+
+/**
+ * Determines whether a value identified by the given name should be treated as
+ * sensitive, and therefore be masked on input.
+ *
+ * The container template API does not mark user inputs as sensitive, so this
+ * heuristic on the input's name is the best signal available.
+ *
+ * Matching is case-insensitive and ignores separators, so that `DB_PASSWORD`,
+ * `db-password` and `dbPassword` are all recognized.
+ *
+ * @param name Name of the input, environment variable or similar
+ */
+export function isSensitiveName(name: string): boolean {
+  const normalized = name.toLowerCase().replaceAll(/[^a-z0-9]+/g, "");
+
+  return sensitiveSubstrings.some((substring) =>
+    normalized.includes(substring),
+  );
+}

From cb35f3799d0b7939cced5821c9ff6316d9d9a031 Mon Sep 17 00:00:00 2001
From: Martin Helmich <m.helmich@mittwald.de>
Date: Wed, 29 Jul 2026 11:13:50 +0200
Subject: [PATCH 13/13] fix(stack): detect sensitive template inputs via their
 validation schema

Templates mark sensitive inputs with a validation schema of format
"password", so use that instead of guessing from the input name.

This replaces the name-based heuristic introduced in the previous commit
and reverts the unrelated change to the "__PROMPT__" environment
variable path, which has no validation schema to go by.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/lib/resources/stack/env.ts                |  3 +-
 .../resources/stack/template-inputs.test.ts   | 61 +++++++++++++++++--
 src/lib/resources/stack/template-inputs.ts    | 29 ++++++++-
 src/lib/util/isSensitiveName.test.ts          | 32 ----------
 src/lib/util/isSensitiveName.ts               | 38 ------------
 5 files changed, 85 insertions(+), 78 deletions(-)
 delete mode 100644 src/lib/util/isSensitiveName.test.ts
 delete mode 100644 src/lib/util/isSensitiveName.ts

diff --git a/src/lib/resources/stack/env.ts b/src/lib/resources/stack/env.ts
index 1fd88a724..7fcf15e0a 100644
--- a/src/lib/resources/stack/env.ts
+++ b/src/lib/resources/stack/env.ts
@@ -3,7 +3,6 @@ import { pathExists } from "../../util/fs/pathExists.js";
 import { ProcessRenderer } from "../../../rendering/process/process.js";
 import { getRandomValues } from "node:crypto";
 import { parseEnvironmentVariablesFromStr } from "../../util/parser.js";
-import { isSensitiveName } from "../../util/isSensitiveName.js";
 
 export async function collectEnvironment(
   base: NodeJS.ProcessEnv,
@@ -37,7 +36,7 @@ export async function fillMissingEnvironmentVariables(
     if (value === "__PROMPT__") {
       output[key] = await renderer.addInput(
         `enter value for environment variable ${key}`,
-        isSensitiveName(key),
+        false,
       );
     }
 
diff --git a/src/lib/resources/stack/template-inputs.test.ts b/src/lib/resources/stack/template-inputs.test.ts
index 7f1f257aa..414cdeea5 100644
--- a/src/lib/resources/stack/template-inputs.test.ts
+++ b/src/lib/resources/stack/template-inputs.test.ts
@@ -1,5 +1,8 @@
 import { describe, it, expect, jest } from "@jest/globals";
-import { collectTemplateUserInputs } from "./template-inputs.js";
+import {
+  collectTemplateUserInputs,
+  isSensitiveInput,
+} from "./template-inputs.js";
 import type { MittwaldAPIV2 } from "@mittwald/api-client";
 import { ProcessRenderer } from "../../../rendering/process/process.js";
 
@@ -67,10 +70,24 @@ describe("collectTemplateUserInputs", () => {
     expect(addInput).toHaveBeenCalledWith(expect.any(String), false);
   });
 
-  it("masks the prompt for sensitive inputs", async () => {
+  it("masks the prompt for inputs with a password validation schema", async () => {
     const definitions: TemplateUserInputDefinition[] = [
-      { name: "ADMIN_PASSWORD", required: true },
-      { name: "ADMIN_EMAIL", required: true },
+      {
+        name: "ADMIN_PASSWORD",
+        required: true,
+        validationSchema: JSON.stringify({
+          type: "string",
+          format: "password",
+        }),
+      },
+      {
+        name: "ADMIN_EMAIL",
+        required: true,
+        validationSchema: JSON.stringify({
+          type: "string",
+          format: "email",
+        }),
+      },
     ];
     const { renderer, addInput } = makeRenderer(["s3cret", "a@example.com"]);
 
@@ -115,3 +132,39 @@ describe("collectTemplateUserInputs", () => {
     expect(addInfo).toHaveBeenCalledWith(expect.stringContaining("UNKNOWN"));
   });
 });
+
+describe("isSensitiveInput", () => {
+  it("detects a password format", () => {
+    expect(
+      isSensitiveInput({
+        name: "PASSWORD",
+        required: true,
+        validationSchema: '{"type":"string","format":"password"}',
+      }),
+    ).toBe(true);
+  });
+
+  it("does not treat other formats as sensitive", () => {
+    expect(
+      isSensitiveInput({
+        name: "EMAIL",
+        required: true,
+        validationSchema: '{"type":"string","format":"email"}',
+      }),
+    ).toBe(false);
+  });
+
+  it("is not sensitive without a validation schema", () => {
+    expect(isSensitiveInput({ name: "PASSWORD", required: true })).toBe(false);
+  });
+
+  it("tolerates a malformed validation schema", () => {
+    expect(
+      isSensitiveInput({
+        name: "PASSWORD",
+        required: true,
+        validationSchema: "not json",
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/src/lib/resources/stack/template-inputs.ts b/src/lib/resources/stack/template-inputs.ts
index 65c906df5..cac4a2437 100644
--- a/src/lib/resources/stack/template-inputs.ts
+++ b/src/lib/resources/stack/template-inputs.ts
@@ -1,6 +1,5 @@
 import type { MittwaldAPIV2 } from "@mittwald/api-client";
 import { ProcessRenderer } from "../../../rendering/process/process.js";
-import { isSensitiveName } from "../../util/isSensitiveName.js";
 
 type ContainerTemplate = MittwaldAPIV2.Components.Schemas.ContainerTemplate;
 type TemplateUserInputDefinition = NonNullable<
@@ -12,6 +11,32 @@ export interface TemplateUserInput {
   value: string;
 }
 
+/**
+ * Determines whether an input holds a sensitive value, and should therefore be
+ * masked when prompting for it. Templates mark these inputs with a validation
+ * schema of format "password".
+ */
+export function isSensitiveInput(
+  definition: TemplateUserInputDefinition,
+): boolean {
+  const { validationSchema } = definition;
+  if (!validationSchema) {
+    return false;
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(validationSchema);
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      "format" in parsed &&
+      parsed.format === "password"
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Resolves the concrete user inputs that should be sent to the API when
  * creating a stack from a template.
@@ -62,7 +87,7 @@ export async function collectTemplateUserInputs(
     const suffix = label ? ` (${label})` : "";
     const value = await renderer.addInput(
       `enter value for required template input '${definition.name}'${suffix}`,
-      isSensitiveName(definition.name),
+      isSensitiveInput(definition),
     );
     result.push({ name: definition.name, value });
   }
diff --git a/src/lib/util/isSensitiveName.test.ts b/src/lib/util/isSensitiveName.test.ts
deleted file mode 100644
index dcf87d141..000000000
--- a/src/lib/util/isSensitiveName.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { describe, it, expect } from "@jest/globals";
-import { isSensitiveName } from "./isSensitiveName.js";
-
-describe("isSensitiveName", () => {
-  it.each([
-    "PASSWORD",
-    "DB_PASSWORD",
-    "db-password",
-    "dbPassword",
-    "MYSQL_ROOT_PASSWD",
-    "GPG_PASSPHRASE",
-    "APP_SECRET",
-    "ACCESS_TOKEN",
-    "API_KEY",
-    "apiKey",
-    "PRIVATE_KEY",
-    "REGISTRY_CREDENTIALS",
-  ])("treats '%s' as sensitive", (name) => {
-    expect(isSensitiveName(name)).toBe(true);
-  });
-
-  it.each([
-    "DOMAIN",
-    "ADMIN_EMAIL",
-    "PORT",
-    "TIMEZONE",
-    "DB_NAME",
-    "PUBLIC_URL",
-  ])("treats '%s' as not sensitive", (name) => {
-    expect(isSensitiveName(name)).toBe(false);
-  });
-});
diff --git a/src/lib/util/isSensitiveName.ts b/src/lib/util/isSensitiveName.ts
deleted file mode 100644
index f54071254..000000000
--- a/src/lib/util/isSensitiveName.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-/**
- * Substrings that indicate that a value is sensitive and should therefore be
- * masked when the user is prompted for it.
- *
- * Deliberately errs on the side of masking: masking a harmless value is a minor
- * annoyance, whereas echoing a password to the terminal (and into the process
- * summary) is not.
- */
-const sensitiveSubstrings = [
-  "password",
-  "passwd",
-  "passphrase",
-  "secret",
-  "token",
-  "apikey",
-  "privatekey",
-  "credential",
-];
-
-/**
- * Determines whether a value identified by the given name should be treated as
- * sensitive, and therefore be masked on input.
- *
- * The container template API does not mark user inputs as sensitive, so this
- * heuristic on the input's name is the best signal available.
- *
- * Matching is case-insensitive and ignores separators, so that `DB_PASSWORD`,
- * `db-password` and `dbPassword` are all recognized.
- *
- * @param name Name of the input, environment variable or similar
- */
-export function isSensitiveName(name: string): boolean {
-  const normalized = name.toLowerCase().replaceAll(/[^a-z0-9]+/g, "");
-
-  return sensitiveSubstrings.some((substring) =>
-    normalized.includes(substring),
-  );
-}