From 9ece8c6d10a78fdcede6a1aff98a1c77e72c8aa0 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Sat, 12 Jul 2025 17:17:49 +0200
Subject: [PATCH] Templates/cli: improve ux and docs

---
 docs/site/guides/getting-started/deploy.md    |  4 ++--
 pkgs/clan-cli/clan_cli/__init__.py            | 20 +++++++++++++++++++
 .../clan-cli/clan_cli/templates/apply_disk.py | 20 +++++++++----------
 pkgs/clan-cli/clan_lib/api/disk.py            |  2 +-
 4 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md
index 945f29ffd..77b9da689 100644
--- a/docs/site/guides/getting-started/deploy.md
+++ b/docs/site/guides/getting-started/deploy.md
@@ -153,7 +153,7 @@ By default clan uses [disko](https://github.com/nix-community/disko) which allow
 To setup a disk schema for a machine run
 
 ```bash
-clan templates apply disk --to-machine jon --template single-disk --set mainDisk ""
+clan templates apply disk single-disk jon --set mainDisk ""
 ```
 
 Which should fail and give the valid options for the specific hardware:
@@ -166,7 +166,7 @@ Invalid value  for placeholder mainDisk - Valid options:
 Re-run the command with the correct disk:
 
 ```bash
-clan templates apply disk --to-machine jon --template single-disk --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
+clan templates apply disk single-disk jon --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
 ```
 
 Should now be succesfull
diff --git a/pkgs/clan-cli/clan_cli/__init__.py b/pkgs/clan-cli/clan_cli/__init__.py
index 57a62db44..dfe24e179 100644
--- a/pkgs/clan-cli/clan_cli/__init__.py
+++ b/pkgs/clan-cli/clan_cli/__init__.py
@@ -199,6 +199,26 @@ For more detailed information, visit: {help_hyperlink("getting-started", "https:
     parser_templates = subparsers.add_parser(
         "templates",
         help="Interact with templates",
+        description="Interact with templates",
+        epilog=(
+            """
+This subcommand provides an interface to templates provided by clan.
+
+Examples:
+
+  $ clan templates list
+  List all the machines managed by Clan.
+
+  $ clan templates apply disk [TEMPLATE] [MACHINE]
+  Will apply the specified [TEMPLATE] to the [MACHINE]
+
+  Many templates require to *set* variables via the `--set` flag.
+  $ clan templates apply disk [TEMPLATE] [MACHINE] --set key1 value1 --set key2 value2
+
+  Real world example
+  $ clan templates apply disk single-disk jon --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
+"""
+        ),
         formatter_class=argparse.RawTextHelpFormatter,
     )
     templates.register_parser(parser_templates)
diff --git a/pkgs/clan-cli/clan_cli/templates/apply_disk.py b/pkgs/clan-cli/clan_cli/templates/apply_disk.py
index 7b0ec3c60..1836a63a2 100644
--- a/pkgs/clan-cli/clan_cli/templates/apply_disk.py
+++ b/pkgs/clan-cli/clan_cli/templates/apply_disk.py
@@ -37,29 +37,27 @@ def apply_command(args: argparse.Namespace) -> None:
     placeholders = dict(set_tuples)
 
     set_machine_disk_schema(
-        Machine(args.to_machine, args.flake),
+        Machine(args.machine, args.flake),
         args.template,
         placeholders,
         force=args.force,
         check_hw=not args.skip_hardware_check,
     )
-    log.info(f"Applied disk template '{args.template}' to machine '{args.to_machine}' ")
+    log.info(f"Applied disk template '{args.template}' to machine '{args.machine}' ")
 
 
 def register_apply_disk_template_parser(parser: argparse.ArgumentParser) -> None:
-    machine_action = parser.add_argument(
-        "--to-machine",
+    parser.add_argument(
+        "template",
+        type=str,
+        help="The name of the disk template to apply",
+    )
+    machine_action = parser.add_argument(
+        "machine",
         type=str,
-        required=True,
         help="The machine to apply the template to",
     )
     add_dynamic_completer(machine_action, complete_machines)
-    parser.add_argument(
-        "--template",
-        type=str,
-        required=True,
-        help="The name of the disk template to apply",
-    )
     parser.add_argument(
         "--set",
         help="Set a placeholder in the template to a value",
diff --git a/pkgs/clan-cli/clan_lib/api/disk.py b/pkgs/clan-cli/clan_lib/api/disk.py
index 8afad3ffc..207fccefc 100644
--- a/pkgs/clan-cli/clan_lib/api/disk.py
+++ b/pkgs/clan-cli/clan_lib/api/disk.py
@@ -188,7 +188,7 @@ def set_machine_disk_schema(
     # check that all required placeholders are present
     for placeholder_name, schema_placeholder in disk_schema.placeholders.items():
         if schema_placeholder.required and placeholder_name not in placeholders:
-            msg = f"Required placeholder {placeholder_name} - {schema_placeholder} missing"
+            msg = f"Required to set template variable {placeholder_name}"
             raise ClanError(msg)
 
     # For every placeholder check that the value is valid