pkgs/cli: Add facts deprecation warning to clan facts help output

Merge pull request 'ui/scene: refactor simplify select animation' (#4325 ) from ui-scene-1 into main
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4325
2025-07-15 14:28:36 +02:00 · 2025-07-13 18:56:12 +00:00 · 2025-07-13 20:44:12 +02:00 · 2025-07-13 20:43:35 +02:00 · 2025-07-13 16:14:21 +00:00 · 2025-07-13 18:03:56 +02:00
48 changed files with 1548 additions and 1280 deletions
--- a/clanModules/disk-id/roles/default.nix
+++ b/clanModules/disk-id/roles/default.nix
@@ -1,5 +1,4 @@
 {
-  config,
  pkgs,
  ...
 }:
@@ -9,9 +8,14 @@
  config = {

    warnings = [
-      "The clan.disk-id module is deprecated and will be removed on 2025-07-15.
-      Please migrate to user-maintained configuration or the new equivalent clan services
-      (https://docs.clan.lol/reference/clanServices)."
+      ''
+        The clan.disk-id module is deprecated and will be removed on 2025-07-15.
+        For migration see: https://docs.clan.lol/guides/migrations/disk-id/
+
+        !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+        !!! Please migrate. Otherwise you may not be able to boot your system after that date.  !!!
+        !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+      ''
    ];
    clan.core.vars.generators.disk-id = {
      files.diskId.secret = false;
--- a/clanServices/users/default.nix
+++ b/clanServices/users/default.nix
@@ -11,7 +11,7 @@

  roles.default = {
    interface =
-      { lib, ... }:
+      { config, lib, ... }:
      {
        options = {
          user = lib.mkOption {
@@ -28,8 +28,8 @@

              Effects:

-              - *enabled* (`true`) - Prompt for a passwort during the machine installation or update workflow.
-              - *disabled* (`false`) - Generate a passwort during the machine installation or update workflow.
+              - *enabled* (`true`) - Prompt for a password during the machine installation or update workflow.
+              - *disabled* (`false`) - Generate a password during the machine installation or update workflow.

              The password can be shown in two steps:

@@ -37,6 +37,23 @@
              - `clan vars get <machine-name> <name-of-password-variable>`
            '';
          };
+          regularUser = lib.mkOption {
+            type = lib.types.bool;
+            default = config.user != "root";
+            defaultText = lib.literalExpression "config.user != \"root\"";
+            example = false;
+            description = ''
+              Whether the user should be a regular user or a system user.
+
+              Regular users are normal users that can log in and have a home directory.
+
+              System users are used for system services and do not have a home directory.
+
+              !!! Warning
+                  `root` cannot be a regular user.
+                  You must set this to `false` for `root`
+            '';
+          };
          groups = lib.mkOption {
            type = lib.types.listOf lib.types.str;
            default = [ ];
@@ -73,8 +90,8 @@
            ...
          }:
          {
-            users.mutableUsers = false;
            users.users.${settings.user} = {
+              isNormalUser = settings.regularUser;
              extraGroups = settings.groups;

              hashedPasswordFile =
@@ -122,4 +139,11 @@
          };
      };
  };
+
+  perMachine = {
+    nixosModule = {
+      # Immutable users to ensure that this module has exclusive control over the users.
+      users.mutableUsers = false;
+    };
+  };
 }
--- a/clanServices/users/tests/vm/default.nix
+++ b/clanServices/users/tests/vm/default.nix
@@ -31,7 +31,6 @@
    server = {
      users.users.testuser.group = "testuser";
      users.groups.testuser = { };
-      users.users.testuser.isNormalUser = true;
    };
  };

--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -51,6 +51,7 @@ nav:
          - 🚀 Creating Your First Clan: guides/getting-started/index.md
          - 📀 Create USB Installer (optional): guides/getting-started/installer.md
          - ⚙️ Add Machines: guides/getting-started/add-machines.md
+          - ⚙️ Add User: guides/getting-started/add-user.md
          - ⚙️ Add Services: guides/getting-started/add-services.md
          - 🔐 Secrets & Facts: guides/getting-started/secrets.md
          - 🚢 Deploy Machine: guides/getting-started/deploy.md
@@ -79,6 +80,7 @@ nav:
          - Migrate existing Flakes: guides/migrations/migration-guide.md
          - Migrate inventory Services: guides/migrations/migrate-inventory-services.md
          - Facts Vars Migration: guides/migrations/migration-facts-vars.md
+          - Disk id: guides/migrations/disk-id.md
      - macOS: guides/macos.md
  - Reference:
      - Overview: reference/index.md
--- a/docs/nix/render_options/init.py
+++ b/docs/nix/render_options/init.py
@@ -29,13 +29,13 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any

-from clan_lib.api.modules import (
+from clan_lib.errors import ClanError
+from clan_lib.services.modules import (
    CategoryInfo,
    Frontmatter,
    extract_frontmatter,
    get_roles,
 )
-from clan_lib.errors import ClanError

 # Get environment variables
 CLAN_CORE_PATH = Path(os.environ["CLAN_CORE_PATH"])
--- a/docs/site/guides/getting-started/add-machines.md
+++ b/docs/site/guides/getting-started/add-machines.md
@@ -10,64 +10,23 @@ See the complete [list](../../guides/more-machines.md#automatic-registration) of

 ## Create a machine

-=== "flake.nix (flake-parts)"
+=== "clan.nix (declarative)"

-    ```{.nix hl_lines=12-15}
+    ```{.nix hl_lines="3-4"}
    {
-        inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-        inputs.nixpkgs.follows = "clan-core/nixpkgs";
-        inputs.flake-parts.follows = "clan-core/flake-parts";
-        inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";
-
-        outputs =
-            inputs@{ flake-parts, ... }:
-            flake-parts.lib.mkFlake { inherit inputs; } {
-                imports = [ inputs.clan-core.flakeModules.default ];
-                clan = {
-                    inventory.machines = {
-                        # Define a machine
-                        jon = { };
-                    };
-                };
-
-                systems = [
-                    "x86_64-linux"
-                    "aarch64-linux"
-                    "x86_64-darwin"
-                    "aarch64-darwin"
-                ];
+        inventory.machines = {
+            # Define a machine
+            jon = { };
        };
-    }
-    ```

-=== "flake.nix (classic)"
-
-    ```{.nix hl_lines=11-14}
-    {
-        inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-        inputs.nixpkgs.follows = "clan-core/nixpkgs";
-
-        outputs =
-            { self, clan-core, ... }:
-            let
-                clan = clan-core.lib.clan {
-                    inherit self;
-
-                    inventory.machines = {
-                        # Define a machine
-                        jon = { };
-                    };
-                };
-            in
-            {
-                inherit (clan.config)
-                    nixosConfigurations
-                    nixosModules
-                    clanInternals
-                    darwinConfigurations
-                    darwinModules
-                    ;
-            };
+        # Additional NixOS configuration can be added here.
+        # machines/jon/configuration.nix will be automatically imported.
+        # See: https://docs.clan.lol/guides/more-machines/#automatic-registration
+        machines = {
+            # jon = { config, ... }: {
+            #   environment.systemPackages = [ pkgs.asciinema ];
+            # };
+        };
    }
    ```

@@ -89,16 +48,15 @@ See the complete [list](../../guides/more-machines.md#automatic-registration) of

    The option: `machines.<name>` is used to add extra *nixosConfiguration* to a machine

-```{.nix .annotate title="flake.nix" hl_lines="3-13 18-22"}
-# Sometimes this attribute set is defined in clan.nix
-clan = {
+Add the following to your `clan.nix` file for each machine.
+This example demonstrates what is needed based on a machine called `jon`:
+
+```{.nix .annotate title="clan.nix" hl_lines="3-6 15-19"}
+{
    inventory.machines = {
        jon = {
-            # Define targetHost here
-            # Required before deployment
-            deploy.targetHost = "root@jon"; # (1)
-            # Define tags here
-            tags = [ ];
+            # Define tags here (optional)
+            tags = [ ]; # (1)
        };
        sara = {
            deploy.targetHost = "root@sara";
@@ -117,9 +75,24 @@ clan = {
 }
 ```

-1. It is required to define a *targetHost* for each machine before deploying. Best practice has been, to use the zerotier ip/hostname or the ip from the from overlay network you decided to use.
+1. Tags can be used to automatically add this machine to services later on. - You dont need to set this now.
 2. Add your *ssh key* here - That will ensure you can always login to your machine via *ssh* in case something goes wrong.

+### (Optional) Create a `configuration.nix`
+
+```nix title="./machines/jon/configuration.nix"
+{
+    imports = [
+        # enables GNOME desktop (optional)
+        ../../modules/gnome.nix
+    ];
+
+    # Set nixosOptions here
+    # Or import your own modules via 'imports'
+    # ...
+}
+```
+
 ### (Optional) Renaming a Machine

 Older templates included static machine folders like `jon` and `sara`.
--- a/docs/site/guides/getting-started/add-services.md
+++ b/docs/site/guides/getting-started/add-services.md
@@ -17,104 +17,61 @@ To learn more: [Guide about clanService](../clanServices.md)

 ## Configure a Zerotier Network (recommended)

-```{.nix title="flake.nix" hl_lines="20-28"}
+```{.nix title="clan.nix" hl_lines="8-16"}
 {
-    inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-    inputs.nixpkgs.follows = "clan-core/nixpkgs";
-    inputs.flake-parts.follows = "clan-core/flake-parts";
-    inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";
-
-    outputs =
-        inputs@{ flake-parts, ... }:
-        flake-parts.lib.mkFlake { inherit inputs; } {
-            imports = [ inputs.clan-core.flakeModules.default ];
-            # Sometimes this attribute set is defined in clan.nix
-            clan = {
-                inventory.machines = {
-                    jon = {
-                        targetHost = "root@jon";
-                    };
-                    sara = {
-                        targetHost = "root@jon";
-                    };
-                };
-                inventory.instances = {
-                    zerotier = { # (1)
-                        # Defines 'jon' as the controller
-                        roles.controller.machines.jon = {};
-                        # Defines all machines as networking peer.
-                        # The 'all' tag is a clan builtin.
-                        roles.peer.tags.all = {};
-                    };
-                }
-            };
-
-            systems = [
-                "x86_64-linux"
-                "aarch64-linux"
-                "x86_64-darwin"
-                "aarch64-darwin"
-            ];
+    inventory.machines = {
+        jon = { };
+        sara = { };
    };
+
+    inventory.instances = {
+        zerotier = { # (1)
+            # Replace with the name (string) of your machine that you will use as zerotier-controller
+            # See: https://docs.zerotier.com/controller/
+            # Deploy this machine first to create the network secrets
+            roles.controller.machines."jon" = { }; # (2)
+            # Peers of the network
+            # this line means 'all' clan machines will be 'peers'
+            roles.peer.tags.all = { }; # (3)
+        };
+    };
+    # ...
+    # elided
 }
 ```

 1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them.
   Or read [authoring/clanServices](../authoring/clanServices/index.md) if you want to bring your own

+2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine.
+
+3. This line will add all machines of your clan as `peer` to zerotier
+
 ## Adding more recommended defaults

 Adding the following services is recommended for most users:

-```{.nix title="flake.nix" hl_lines="25-35"}
+```{.nix title="clan.nix" hl_lines="7-14"}
 {
-    inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-    inputs.nixpkgs.follows = "clan-core/nixpkgs";
-    inputs.flake-parts.follows = "clan-core/flake-parts";
-    inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";
-
-    outputs =
-        inputs@{ flake-parts, ... }:
-        flake-parts.lib.mkFlake { inherit inputs; } {
-            imports = [ inputs.clan-core.flakeModules.default ];
-            # Sometimes this attribute set is defined in clan.nix
-            clan = {
-                inventory.machines = {
-                    jon = {
-                        targetHost = "root@jon";
-                    };
-                    sara = {
-                        targetHost = "root@jon";
-                    };
-                };
-                inventory.instances = {
-                    zerotier = {
-                        roles.controller.machines.jon = {};
-                        roles.peer.tags.all = {};
-                    };
-                    admin = { # (1)
-                        roles.default.tags.all = { };
-                        roles.default.settings = {
-                            allowedKeys = {
-                                "my-user" = "ssh-ed25519 AAAAC3N..."; # elided
-                            };
-                        };
-                    };
-                    state-version = { # (2)
-                        roles.default.tags.all = { };
-                    };
+    inventory.machines = {
+        jon = { };
+        sara = { };
+    };
+    inventory.instances = {
+        admin = { # (1)
+            roles.default.tags.all = { };
+            roles.default.settings = {
+                allowedKeys = {
+                    "my-user" = "ssh-ed25519 AAAAC3N..."; # (2)
                };
            };
-            systems = [
-                "x86_64-linux"
-                "aarch64-linux"
-                "x86_64-darwin"
-                "aarch64-darwin"
-            ];
+        };
+        # ...
+        # elided
    };
 }
 ```

 1. The `admin` service will generate a **root-password** and **add your ssh-key** that allows for convienient administration.
-
-2. The `state-version` service will generate a [nixos state version](https://wiki.nixos.org/wiki/FAQ/When_do_I_update_stateVersion) for each system once it is deployed.
+2. Equivalent to directly setting `authorizedKeys` like in [configuring a machine](./add-machines.md#configuring-a-machine)
+3. Adds `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.
--- a/docs/site/guides/getting-started/add-user.md
+++ b/docs/site/guides/getting-started/add-user.md
@@ -0,0 +1,127 @@
+# How to add users
+
+!!! Note "Under construction"
+
+The users concept of clan is not done yet. This guide outlines some solutions from our community.
+Defining users can be done in many different ways. We want to highlight two approaches:
+
+- Using clan's [users](../../reference/clanServices/users.md) service.
+- Using a custom approach.
+
+## Adding Users using the [users](../../reference/clanServices/users.md) service
+
+To add a first *user* this guide will be leveraging two things:
+
+- [clanServices](../../reference/clanServices/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`.
+- [clanServices/users](../../reference/clanServices/users.md): Implements logic for adding a single user perInstance.
+
+The example shows how to add a user called `jon`:
+
+```{.nix title="clan.nix" hl_lines="7-21"}
+{
+    inventory.machines = {
+        jon = { };
+        sara = { };
+    };
+    inventory.instances = {
+        jon-user = { # (1)
+            module.name = "users";
+
+            roles.default.tags.all = { }; # (2)
+
+            roles.default.settings = {
+                user = "jon"; # (3)
+                groups = [
+                    "wheel" # Allow using 'sudo'
+                    "networkmanager" # Allows to manage network connections.
+                    "video" # Allows to access video devices.
+                    "input" # Allows to access input devices.
+                ];
+            };
+        };
+        # ...
+        # elided
+    };
+}
+```
+
+1. Add `user = jon` as a user on all machines. Will create a `home` directory, and prompt for a password before deployment.
+2. Add this user to `all` machines
+3. Define the `name` of the user to be `jon`
+
+The `users` service creates a `/home/jon` directory, allows `jon` to sign in and will take care of the users password as part of [deployment](./deploy.md).
+
+For more information see [clanService/users](../../reference/clanServices/users.md)
+
+## Using a custom approach
+
+Some people like to define a `users` folder in their repository root.
+That allows to bind all user specific logic to a single place (`default.nix`)
+Which can be imported into individual machines to make the user avilable on that machine.
+
+```bash
+.
+├── machines
+│   ├── jon
+# ......
+├── users
+│   ├── jon
+│   │   └── default.nix # <- a NixOS module; sets some options
+# ... ... ...
+```
+
+## using [home-manager](https://github.com/nix-community/home-manager)
+
+When using clan's `users` service it is possible to define extraModules.
+In fact this is always possible when using clan's services.
+
+We can use this property of clan services to bind a nixosModule to the user, which configures home-manager.
+
+```{.nix title="clan.nix" hl_lines="22"}
+{
+    inventory.machines = {
+        jon = { };
+        sara = { };
+    };
+    inventory.instances = {
+        jon-user = {
+            module.name = "users";
+
+            roles.default.tags.all = { };
+
+            roles.default.settings = {
+                user = "jon",
+                groups = [
+                    "wheel"
+                    "networkmanager"
+                    "video"
+                    "input"
+                ];
+            };
+
+            roles.default.extraModules = [ ./users/jon/home.nix ]; # (1)
+        };
+        # ...
+        # elided
+    };
+}
+```
+
+1. Type `path` or `string`: Must point to a seperate file. Inlining a module is not possible
+
+!!! Note "This is inspiration"
+    Our community might come up with better solutions soon.
+    We are seeking contributions to improve this pattern if you have a nicer solution in mind.
+
+```nix title="users/jon/home.nix"
+# NixOS module to import home-manager and the home-manager configuration of 'jon'
+{ self, ...}:
+{
+  imports = [ self.inputs.home-manager.nixosModules.default ];
+  home-manager.users.jon = {
+    imports = [
+      ./home-configuration.nix
+    ];
+  };
+}
+```
--- a/docs/site/guides/getting-started/deploy.md
+++ b/docs/site/guides/getting-started/deploy.md
@@ -1,6 +1,6 @@
 # Deploy a machine

-Now that you have created a new machine, we will walk through how to install it.
+Now that you have created a machines, added some services and setup secrets. This guide will walk through how to deploy it.

 ## Prerequisites

@@ -10,256 +10,205 @@ Now that you have created a new machine, we will walk through how to install it.
    - [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
    - [x] **Initialized secrets**: See [secrets](secrets.md) for how to initialize your secrets.

-=== "**Physical Hardware**"
+## Physical Hardware

-    - [x] **USB Flash Drive**: See [Clan Installer](installer.md)
+!!! note "skip this if using a cloud VM"

-    !!! Steps
+Steps:

-        1. Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md).
+- Create a NixOS installer image and transfer it to a bootable USB drive as described in the [installer](./installer.md).
+- Boot the target machine and connect it to a network that makes it reachable from your setup computer.
+- Note down a reachable ip adress (*ipv4*, *ipv6* or *tor*)

-        2. Boot the target machine and connect it to a network that makes it reachable from your setup computer.
+---

-=== "**Cloud VMs**"
+The installer will generate a password and local addresses on boot, then run ssh with these preconfigured.
+The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code.

-    - [x] Any cloud machine if it is reachable via SSH and supports `kexec`.
+Sample boot screen shows:

-    !!! Warning "NixOS can cause strange issues when booting in certain cloud environments."
-        If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel)
+- Root password
+- IP address
+- Optional Tor and mDNS details
+
+```{ .bash .annotate .no-copy .nohighlight}
+┌─────────────────────────────────────────────────────────────────────────────────────┐
+│ ┌───────────────────────────┐                                                       │
+│ │███████████████████████████│ # This is the QR Code (1)                             │
+│ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│                                                       │
+│ │██ █   █ █▀▄▄▄█ ▀█ █   █ ██│                                                       │
+│ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│                                                       │
+│ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│                                                       │
+│ │███▀▀▀ █▄▄█ ▀▄   ▄▀▄█   ███│                                                       │
+│ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│                                                       │
+│ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│                                                       │
+│ │██ █   █ █ █  █ ▄▄▄  ▄▀▀ ██│                                                       │
+│ │██ █▄▄▄█ █ ▄ ▄    ▄ ▀█ ▄███│                                                       │
+│ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│                                                       │
+│ │███████████████████████████│                                                       │
+│ └───────────────────────────┘                                                       │
+│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
+│ │Root password: cheesy-capital-unwell  # password (2)                             │ │
+│ │Local network addresses:                                                         │ │
+│ │enp1s0           UP    192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │
+│ │enp2s0           DOWN                                                            │ │
+│ │wlan0            DOWN # connect to wlan (3)                                      │ │
+│ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion    │ │
+│ │Multicast DNS: nixos-installer.local                                             │ │
+│ └─────────────────────────────────────────────────────────────────────────────────┘ │
+│ Press 'Ctrl-C' for console access                                                   │
+│                                                                                     │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+1.  This is not an actual QR code, because it is displayed rather poorly on text sites.
+    This would be the actual content of this specific QR code prettified:
+    ```json
+    {
+        "pass": "cheesy-capital-unwell",
+        "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion",
+        "addrs": [
+        "2001:9e8:347:ca00:21e:6ff:fe45:3c92"
+        ]
+    }
+    ```
+
+    To generate the actual QR code, that would be displayed use:
+    ```shellSession
+    echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8
+    ```
+2.  The root password for the installer medium.
+    This password is autogenerated and meant to be easily typeable.
+3.  See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually).
+
+!!! tip
+    Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop
+
+## Cloud VMs
+
+!!! note "skip this if using a physical machine"
+
+Clan supports any cloud machine if it is reachable via SSH and supports `kexec`.
+
+Steps:
+
+- Go to the configuration panel and note down how to connect to the machine via ssh.
+
+!!! tip "NixOS can cause strange issues when booting in certain cloud environments."
+    If on Linode: Make sure that the system uses "Direct Disk boot kernel" (found in the configuration panel)

 ## Setting `targetHost`

-=== "flake.nix (flake-parts)"
+In your nix files set the targetHost (reachable ip) that you retrieved in the previous step.

-    ```{.nix hl_lines="22"}
-    {
-        inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-        inputs.nixpkgs.follows = "clan-core/nixpkgs";
-        inputs.flake-parts.follows = "clan-core/flake-parts";
-        inputs.flake-parts.inputs.nixpkgs-lib.follows = "clan-core/nixpkgs";
+```{.nix title="clan.nix" hl_lines="9"}
+{
+  # Ensure this is unique among all clans you want to use.
+  meta.name = "my-clan";

-        outputs =
-            inputs@{ flake-parts, ... }:
-            flake-parts.lib.mkFlake { inherit inputs; } {
-            systems = [
-                "x86_64-linux"
-                "aarch64-linux"
-                "x86_64-darwin"
-                "aarch64-darwin"
-            ];
-            imports = [ inputs.clan-core.flakeModules.default ];
+  inventory.machines = {
+    # Define machines here.
+    # The machine name will be used as the hostname.
+    jon = {
+        deploy.targetHost = "root@192.168.192.4"; # (1)
+    };
+  };
+  # ...
+  # elided
+}
+```

-            clan = {
-                inventory.machines = {
-                    jon = {
-                        # targetHost will get picked up by cli commands
-                        deploy.targetHost = "root@jon";
-                    };
-                };
-            };
-        };
-    }
-    ```
-
-=== "flake.nix (classic)"
-
-    ```{.nix hl_lines="14"}
-    {
-        inputs.clan-core.url = "https://git.clan.lol/clan/clan-core/archive/main.tar.gz";
-        inputs.nixpkgs.follows = "clan-core/nixpkgs";
-
-        outputs =
-            { self, clan-core, ... }:
-            let
-                clan = clan-core.lib.clan {
-                    inherit self;
-
-                    inventory.machines = {
-                        jon = {
-                            # targetHost will get picked up by cli commands
-                            deploy.targetHost = "root@jon";
-                        };
-                    };
-                };
-            in
-            {
-                inherit (clan.config)
-                    nixosConfigurations
-                    nixosModules
-                    clanInternals
-                    darwinConfigurations
-                    darwinModules
-                    ;
-            };
-    }
-    ```
+1. Use the ip address of your targetMachine that you want to deploy. If using the [flash-installer](./installer.md) it should display its local ip-address when booted.

 !!! warning
    The use of `root@` in the target address implies SSH access as the `root` user.
    Ensure that the root login is secured and only used when necessary.

-## Identify the Target Disk
+See also [how to set TargetHost](../target-host.md) for other methods.

-On the setup computer, SSH into the target:
+## Retrieve the hardware report

-```bash title="setup computer"
-ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
+By default clan uses [nixos-facter](https://github.com/nix-community/nixos-facter) which captures detailed information about the machine or virtual environment.
+
+To generate the hardware-report (`facter.json`) run:
+
+```bash
+clan machines update-hardware-config <machineName>
 ```

-Replace `<IP>` with the machine's IP or hostname if mDNS (i.e. Avahi) is available.
+Example output:

-Which should show something like:
-
-```{.shellSession hl_lines="6" .no-copy}
-NAME        ID-LINK                                         FSTYPE   SIZE MOUNTPOINT
-sda         usb-ST_16GB_AA6271026J1000000509-0:0                    14.9G
-├─sda1      usb-ST_16GB_AA6271026J1000000509-0:0-part1                 1M
-├─sda2      usb-ST_16GB_AA6271026J1000000509-0:0-part2      vfat     100M /boot
-└─sda3      usb-ST_16GB_AA6271026J1000000509-0:0-part3      ext4     2.9G /
-nvme0n1     nvme-eui.e8238fa6bf530001001b448b4aec2929              476.9G
-├─nvme0n1p1 nvme-eui.e8238fa6bf530001001b448b4aec2929-part1 vfat     512M
-├─nvme0n1p2 nvme-eui.e8238fa6bf530001001b448b4aec2929-part2 ext4   459.6G
-└─nvme0n1p3 nvme-eui.e8238fa6bf530001001b448b4aec2929-part3 swap    16.8G
+```shell-session
+$ clan machines update-hardware-config jon
+[jon] $ nixos-facter
+Successfully generated: ./machines/jon/facter.json
 ```

-Look for the top-level disk device (e.g., nvme0n1 or sda) and copy its `ID-LINK`. Avoid using partition IDs like `nvme0n1p1`.
+See [update-hardware-config cli reference](../../reference/cli/machines.md#machines-update-hardware-config) for further configuration possibilities if needed.

-In this example we would copy `nvme-eui.e8238fa6bf530001001b448b4aec2929`
+## Configure your disk schema
+
+By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
+
+To setup a disk schema for a machine run
+
+```bash
+clan templates apply disk single-disk jon --set mainDisk ""
+```
+
+Which should fail and give the valid options for the specific hardware:
+
+```shellSession
+Invalid value  for placeholder mainDisk - Valid options:
+/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368
+```
+
+Re-run the command with the correct disk:
+
+```bash
+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
+
+```shellSession
+Applied disk template 'single-disk' to machine 'jon'
+```
+
+A disko.nix file should be created in `machines/jon`
+You can have a look and customize it if needed.

 !!! tip
    For advanced partitioning, see [Disko templates](https://github.com/nix-community/disko-templates) or [Disko examples](https://github.com/nix-community/disko/tree/master/example).

-## Fill in hardware specific machine configuration
-
-Edit the following fields inside the `./machines/<machine_name>/configuration.nix`
-
-<!-- Note: Use "jon" instead of "<machine>" as "<" is not supported in title tag -->
-
-```nix title="./machines/jon/configuration.nix" hl_lines="12 15 19"
-{
-    imports = [
-    # contains your disk format and partitioning configuration.
-    ../../modules/disko.nix
-    # this file is shared among all machines
-    ../../modules/shared.nix
-    # enables GNOME desktop (optional)
-    ../../modules/gnome.nix
-    ];
-
-    # Put your username here for login
-    users.users.user.name = "__YOUR_USERNAME__";
-
-    # Replace this __CHANGE_ME__ with the copied result of the lsblk command
-    disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
-
-    # IMPORTANT! Add your SSH key here
-    # e.g. > cat ~/.ssh/id_ed25519.pub
-    users.users.root.openssh.authorizedKeys.keys = [ "__YOUR_SSH_KEY__" ];
-
-    # ...
-}
-```
-
-!!! Info "Replace `__YOUR_USERNAME__` with the ip of your machine, if you use avahi you can also use your hostname"
-!!! Info "Replace `__CHANGE_ME__` with the appropriate `ID-LINK` identifier, such as `nvme-eui.e8238fa6bf530001001b448b4aec2929`"
-!!! Info "Replace `__YOUR_SSH_KEY__` with your personal key, like `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILoMI0NC5eT9pHlQExrvR5ASV3iW9+BXwhfchq0smXUJ jon@jon-desktop`"
-
 ## Deploy the machine

-**Finally deployment time!** Use the following command to build and deploy the image via SSH onto your machine.
-
-=== "**Image Installer**"
-
-    The installer will generate a password and local addresses on boot, then run ssh with these preconfigured.
-    The installer shows it's deployment relevant information in two formats, a text form, as well as a QR code.
-
-    Sample boot screen shows:
-
-    - Root password
-    - IP address
-    - Optional Tor and mDNS details
-
-    ```{ .bash .annotate .no-copy .nohighlight}
-    ┌─────────────────────────────────────────────────────────────────────────────────────┐
-    │ ┌───────────────────────────┐                                                       │
-    │ │███████████████████████████│ # This is the QR Code (1)                             │
-    │ │██ ▄▄▄▄▄ █▀▄█▀█▀▄█ ▄▄▄▄▄ ██│                                                       │
-    │ │██ █   █ █▀▄▄▄█ ▀█ █   █ ██│                                                       │
-    │ │██ █▄▄▄█ █▀▄ ▀▄▄▄█ █▄▄▄█ ██│                                                       │
-    │ │██▄▄▄▄▄▄▄█▄▀ ▀▄▀▄█▄▄▄▄▄▄▄██│                                                       │
-    │ │███▀▀▀ █▄▄█ ▀▄   ▄▀▄█   ███│                                                       │
-    │ │██▄██▄▄█▄▄▀▀██▄▀ ▄▄▄ ▄▀█▀██│                                                       │
-    │ │██ ▄▄▄▄▄ █▄▄▄▄ █ █▄█ █▀ ███│                                                       │
-    │ │██ █   █ █ █  █ ▄▄▄  ▄▀▀ ██│                                                       │
-    │ │██ █▄▄▄█ █ ▄ ▄    ▄ ▀█ ▄███│                                                       │
-    │ │██▄▄▄▄▄▄▄█▄▄▄▄▄▄█▄▄▄▄▄█▄███│                                                       │
-    │ │███████████████████████████│                                                       │
-    │ └───────────────────────────┘                                                       │
-    │ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
-    │ │Root password: cheesy-capital-unwell  # password (2)                             │ │
-    │ │Local network addresses:                                                         │ │
-    │ │enp1s0           UP    192.168.178.169/24 metric 1024 fe80::21e:6ff:fe45:3c92/64 │ │
-    │ │enp2s0           DOWN                                                            │ │
-    │ │wlan0            DOWN # connect to wlan (3)                                      │ │
-    │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion    │ │
-    │ │Multicast DNS: nixos-installer.local                                             │ │
-    │ └─────────────────────────────────────────────────────────────────────────────────┘ │
-    │ Press 'Ctrl-C' for console access                                                   │
-    │                                                                                     │
-    └─────────────────────────────────────────────────────────────────────────────────────┘
-    ```
-
-    1.  This is not an actual QR code, because it is displayed rather poorly on text sites.
-        This would be the actual content of this specific QR code prettified:
-        ```json
-        {
-            "pass": "cheesy-capital-unwell",
-            "tor": "6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion",
-            "addrs": [
-            "2001:9e8:347:ca00:21e:6ff:fe45:3c92"
-            ]
-        }
-        ```
-
-        To generate the actual QR code, that would be displayed use:
-        ```shellSession
-        echo '{"pass":"cheesy-capital-unwell","tor":"6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion","addrs":["2001:9e8:347:ca00:21e:6ff:fe45:3c92"]}' | nix run nixpkgs#qrencode -- -s 2 -m 2 -t utf8
-        ```
-    2.  The root password for the installer medium.
-        This password is autogenerated and meant to be easily typeable.
-    3.  See [how to connect to wlan](./installer.md#optional-connect-to-wifi-manually).
-
-    !!! tip
-        Use [KDE Connect](https://apps.kde.org/de/kdeconnect/) for easyily sharing QR codes from phone to desktop
-
-=== "**Cloud VM**"
-
-    Just run the command **Option B: Cloud VM** below
+**Finally deployment time!** Use one of the following commands to build and deploy the image via SSH onto your machine.

 ### Deployment Commands

 #### Using password auth

 ```bash
-clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
+clan machines install [MACHINE] --target-host <IP>
 ```

 #### Using QR JSON

 ```bash
-clan machines install [MACHINE] --json "[JSON]" --update-hardware-config nixos-facter
+clan machines install [MACHINE] --json "[JSON]"
 ```

 #### Using QR image file

 ```bash
-clan machines install [MACHINE] --png [PATH] --update-hardware-config nixos-facter
+clan machines install [MACHINE] --png [PATH]
 ```

 #### Option B: Cloud VM

 ```bash
-clan machines install [MACHINE] --target-host <IP> --update-hardware-config nixos-facter
+clan machines install [MACHINE] --target-host <IP>
 ```

 !!! success
--- a/docs/site/guides/getting-started/index.md
+++ b/docs/site/guides/getting-started/index.md
@@ -38,31 +38,24 @@ By the end of this guide, you'll have a fresh NixOS configuration ready to push

 ## Add Clan CLI to Your Shell

-Add the Clan CLI into your environment:
+Create a new clan

 ```bash
-nix shell git+https://git.clan.lol/clan/clan-core#clan-cli --refresh
+nix run git+https://git.clan.lol/clan/clan-core#clan-cli --refresh -- flakes create
 ```

+This should prompt for a *name*:
+
 ```terminalSession
-clan --help
+Enter a name for the new clan: my-clan
 ```

-Should print the avilable commands.
+Enter a *name*, confirm with *enter*. A directory with that name will be created and initialized.

-Also checkout the [cli-reference documentation](../../reference/cli/index.md).
+!!! Note
+    This command uses the `default` template

-## Initialize Your Project
-
-If you want to migrate an existing project, follow this [guide](../migrations/migration-guide.md).
-
-Set the foundation of your Clan project by initializing it by running:
-
-```bash
-clan flakes create my-clan
-```
-
-This command creates a `flake.nix` and some other files for your project.
+    See `clan templates list` and the `--help` reference for how to use other templates.

 ## Explore the Project Structure

@@ -83,36 +76,48 @@ For example, you might see something like:
 └── README.md
 ```

-Don’t worry if your output looks different—the template evolves over time.
+Don’t worry if your output looks different — Clan templates evolve over time.

-??? info "Recommended way of sourcing the `clan` CLI tool"
+To interact with your newly created clan the you need to load the `clan` cli-package it into your environment by running:

-    The default template adds the `clan` CLI tool to the development shell.
-    This means that you can access the `clan` CLI tool directly from the folder
-    you are in right now.
+=== "Automatic (direnv, recommended)"
+    - prerequisite: [install nix-direnv](https://github.com/nix-community/nix-direnv)

-    In the `my-clan` directory, run the following command:
+    ```
+    direnv allow
+    ```
+
+=== "Manual (nix develop)"

    ```
    nix develop
    ```

-    This will ensure the `clan` CLI tool is available in your shell environment.
+verify that you can run `clan` commands:

-    To automatically add the `clan` CLI tool to your environment without having to
-    run `nix develop` every time, we recommend setting up [direnv](https://direnv.net/).
-
-```
+```bash
 clan show
 ```

 You should see something like this:

-```terminal-session
-Name: my-clan
+```shellSession
+Name: __CHANGE_ME__
 Description: None
 ```

+To change the name of your clan edit `meta.name` in the `clan.nix` or `flake.nix` file
+
+```{.nix title="clan.nix" hl_lines="3"}
+{
+  # Ensure this is unique among all clans you want to use.
+  meta.name = "__CHANGE_ME__";
+
+  # ...
+  # elided
+}
+```
+
 ---

 ## Next Steps
@@ -123,6 +128,7 @@ You can continue with **any** of the following steps at your own pace:
 - [x] [Initialize Clan](./index.md#initialize-your-project)
 - [ ] [Create USB Installer (optional)](./installer.md)
 - [ ] [Add Machines](./add-machines.md)
+- [ ] [Add a User](./add-user.md)
 - [ ] [Add Services](./add-services.md)
 - [ ] [Configure Secrets](./secrets.md)
 - [ ] [Deploy](./deploy.md) - Requires configured secrets
--- a/docs/site/guides/migrations/disk-id.md
+++ b/docs/site/guides/migrations/disk-id.md
@@ -0,0 +1,98 @@
+# Migrate disko config from `clanModules.disk-id`
+
+If you previously bootstrapped a machine's disk using `clanModules.disk-id`, you should now migrate to a standalone, self-contained disko configuration. This ensures long-term stability and avoids reliance on dynamic values from Clan.
+
+If your `disko.nix` currently looks something like this:
+
+```nix title="disko.nix"
+{
+  lib,
+  clan-core,
+  config,
+  ...
+}:
+
+let
+  suffix = config.clan.core.vars.generators.disk-id.files.diskId.value;
+in
+{
+  imports = [
+    clan-core.clanModules.disk-id
+  ];
+
+  # DO NOT EDIT THIS FILE AFTER INSTALLATION of a machine
+  # Otherwise your system might not boot because of missing partitions / filesystems
+  boot.loader.grub.efiSupport = lib.mkDefault true;
+  boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
+  disko.devices = {
+    disk = {
+      "main" = {
+        # suffix is to prevent disk name collisions
+        name = "main-" + suffix;
+        type = "disk";
+        # Set the following in flake.nix for each maschine:
+        # device = <uuid>;
+        content = {
+          # edlied
+        };
+      };
+    };
+  };
+}
+```
+
+## Step 1: Retrieve your `disk-id`
+
+Run the following command to retrieve the generated disk ID for your machine:
+
+```bash
+clan vars list <machineName>
+```
+
+Which should print the generated `disk-id/diskId` value in clear text
+You should see output like:
+
+```shellSession
+disk-id/diskId: fcef30a749f8451d8f60c46e1ead726f
+# ...
+# elided
+```
+
+Copy this value — you'll need it in the next step.
+
+## ✍️ Step 2: Replace Dynamic Configuration with Static Values
+
+✅ Goal: Make your disko.nix file standalone.
+
+We are going to make three changes:
+
+- Remove `let in, imports, {lib,clan-core,config, ...}:` to isolate the file.
+- Replace `suffix` with the actual disk-id
+- Move `disko.devices.disk.main.device` from `flake.nix` or `configuration.nix` into this file.
+
+```{.nix title="disko.nix" hl_lines="7-9 11-14"}
+{
+  boot.loader.grub.efiSupport = lib.mkDefault true;
+  boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
+  disko.devices = {
+    disk = {
+      "main" = {
+        #       ↓ Copy the disk-id into place
+        name = "main-fcef30a749f8451d8f60c46e1ead726f";
+        type = "disk";
+
+        # Some earlier guides had this line in a flake.nix
+        # disko.devices.disk.main.device = "/dev/disk/by-id/__CHANGE_ME__";
+        #        ↓ Copy the '/dev/disk/by-id' into here instead
+        device = "/dev/disk/by-id/nvme-eui.e8238fa6bf530001001b448b4aec2929";
+
+        # edlied;
+      };
+    };
+  };
+}
+```
+
+These steps are only needed for existing configurations that depend on the `diskId` module.
+
+For newer machines clan offers simple *disk templates* via its [templates cli](../../reference/cli/templates.md)
--- a/lib/modules/inventoryClass/service-list-from-inputs.nix
+++ b/lib/modules/inventoryClass/service-list-from-inputs.nix
@@ -35,10 +35,20 @@ in
        inputName: v: lib.mapAttrs (inspectModule inputName) v.clan.modules
      ) inputsWithModules;
  };
-  options.localModules = lib.mkOption {
+  options.moduleSchemas = lib.mkOption {
+    # { sourceName :: { moduleName :: { roleName :: Schema }}}
    readOnly = true;
    type = lib.types.raw;
-    default = config.modulesPerSource.self;
+    default = lib.mapAttrs (
+      _inputName: moduleSet:
+      lib.mapAttrs (
+        _moduleName: module:
+        (clanLib.evalService {
+          modules = [ module ];
+          prefix = [ ];
+        }).config.result.api.schema
+      ) moduleSet
+    ) config.modulesPerSource;
  };
  options.templatesPerSource = lib.mkOption {
    # { sourceName :: { moduleName :: {} }}
--- a/nixosModules/clanCore/vars/secret/sops/collectFiles.nix
+++ b/nixosModules/clanCore/vars/secret/sops/collectFiles.nix
@@ -0,0 +1,37 @@
+# collectFiles helper function
+{
+  lib ? import <nixpkgs/lib>,
+}:
+let
+  inherit (lib)
+    filterAttrs
+    flatten
+    mapAttrsToList
+    ;
+in
+generators:
+let
+  relevantFiles =
+    generator:
+    filterAttrs (
+      _name: f: f.secret && f.deploy && (f.neededFor == "users" || f.neededFor == "services")
+    ) generator.files;
+  allFiles = flatten (
+    mapAttrsToList (
+      gen_name: generator:
+      mapAttrsToList (fname: file: {
+        name = fname;
+        generator = gen_name;
+        neededForUsers = file.neededFor == "users";
+        inherit (generator) share;
+        inherit (file)
+          owner
+          group
+          mode
+          restartUnits
+          ;
+      }) (relevantFiles generator)
+    ) generators
+  );
+in
+allFiles
--- a/nixosModules/clanCore/vars/secret/sops/default.nix
+++ b/nixosModules/clanCore/vars/secret/sops/default.nix
@@ -7,7 +7,7 @@
 }:
 let

-  inherit (import ./funcs.nix { inherit lib; }) collectFiles;
+  collectFiles = import ./collectFiles.nix { inherit lib; };

  machineName = config.clan.core.settings.machine.name;

--- a/nixosModules/clanCore/vars/secret/sops/funcs.nix
+++ b/nixosModules/clanCore/vars/secret/sops/funcs.nix
@@ -1,42 +0,0 @@
-{
-  lib ? import <nixpkgs/lib>,
-  ...
-}:
-let
-
-  inherit (lib)
-    filterAttrs
-    flatten
-    mapAttrsToList
-    ;
-in
-{
-
-  collectFiles =
-    generators:
-    let
-      relevantFiles =
-        generator:
-        filterAttrs (
-          _name: f: f.secret && f.deploy && (f.neededFor == "users" || f.neededFor == "services")
-        ) generator.files;
-      allFiles = flatten (
-        mapAttrsToList (
-          gen_name: generator:
-          mapAttrsToList (fname: file: {
-            name = fname;
-            generator = gen_name;
-            neededForUsers = file.neededFor == "users";
-            inherit (generator) share;
-            inherit (file)
-              owner
-              group
-              mode
-              restartUnits
-              ;
-          }) (relevantFiles generator)
-        ) generators
-      );
-    in
-    allFiles;
-}
--- a/pkgs/clan-app/ui/src/index.tsx
+++ b/pkgs/clan-app/ui/src/index.tsx
@@ -3,7 +3,7 @@ import { render } from "solid-js/web";

 import "./index.css";
 import { QueryClient } from "@tanstack/solid-query";
-import { CubeScene } from "./scene/qubes";
+import { CubeScene } from "./scene/cubes";

 export const client = new QueryClient();

--- a/pkgs/clan-app/ui/src/scene/cubes.tsx
+++ b/pkgs/clan-app/ui/src/scene/cubes.tsx
@@ -402,24 +402,16 @@ export function CubeScene() {
      if (selected) {
        // When selected, make all faces red-ish but maintain the lighting difference
        materials.forEach((material, index) => {
-          (material as THREE.MeshBasicMaterial).color.set(
-            index === 2
-              ? 0xff6666 // Top face - lighter red
-              : index === 0 || index === 4
-                ? 0xdce4e5 // Front/right faces - keep
-                : 0xa4b3b5, // Shadow faces - keep
-          );
+          if (index === 2) {
+            (material as THREE.MeshBasicMaterial).color.set(0xff6666);
+          }
        });
      } else {
        // Normal colors - restore original face colors
        materials.forEach((material, index) => {
-          (material as THREE.MeshBasicMaterial).color.set(
-            index === 2
-              ? 0xffffff // Top face - light
-              : index === 0 || index === 4
-                ? 0xdce4e5 // Front/right faces - medium
-                : 0xa4b3b5, // Shadow faces - dark
-          );
+          if (index === 2) {
+            (material as THREE.MeshBasicMaterial).color.set(0xffffff);
+          }
        });
      }
    }
--- a/pkgs/clan-cli/bin/clan
+++ b/pkgs/clan-cli/bin/clan
@@ -6,7 +6,7 @@ sys.path.insert(
    0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
 )

-from clan_cli import main  # NOQA
+from clan_cli.cli import main  # NOQA

 if __name__ == "__main__":
    main()
--- a/pkgs/clan-cli/bin/clan-config
+++ b/pkgs/clan-cli/bin/clan-config
@@ -6,7 +6,7 @@ sys.path.insert(
    0, os.path.join(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
 )

-from clan_cli import config  # NOQA
+from clan_cli.cli import config  # NOQA

 if __name__ == "__main__":
    config.main()
--- a/pkgs/clan-cli/clan_cli/init.py
+++ b/pkgs/clan-cli/clan_cli/init.py
@@ -1,486 +0,0 @@
-import argparse
-import contextlib
-import logging
-import sys
-from pathlib import Path
-from types import ModuleType
-
-from clan_lib.custom_logger import setup_logging
-from clan_lib.dirs import get_clan_flake_toplevel_or_env
-from clan_lib.errors import ClanError
-from clan_lib.flake import Flake
-
-from . import (
-    backups,
-    clan,
-    secrets,
-    select,
-    state,
-    templates,
-    vms,
-)
-from .arg_actions import AppendOptionAction
-from .clan import show
-from .facts import cli as facts
-from .flash import cli as flash_cli
-from .hyperlink import help_hyperlink
-from .machines import cli as machines
-from .profiler import profile
-from .ssh import deploy_info as ssh_cli
-from .vars import cli as vars_cli
-
-log = logging.getLogger(__name__)
-
-argcomplete: ModuleType | None = None
-with contextlib.suppress(ImportError):
-    import argcomplete  # type: ignore[no-redef]
-
-
-def flake_path(arg: str) -> str:
-    flake_dir = Path(arg).resolve()
-    if flake_dir.exists() and flake_dir.is_dir():
-        return str(flake_dir)
-    return arg
-
-
-def default_flake() -> str | None:
-    val = get_clan_flake_toplevel_or_env()
-    if val:
-        return str(val)
-    return None
-
-
-def create_flake_from_args(args: argparse.Namespace) -> Flake:
-    """Create a Flake object from parsed arguments, including nix_options."""
-    flake_path_str = args.flake
-    nix_options = getattr(args, "option", [])
-    return Flake(flake_path_str, nix_options=nix_options)
-
-
-def add_common_flags(parser: argparse.ArgumentParser) -> None:
-    def argument_exists(parser: argparse.ArgumentParser, arg: str) -> bool:
-        """
-        Check if an argparse argument already exists.
-        This is needed because the aliases subcommand doesn't *really*
-        create an alias - it duplicates the actual parser in the tree
-        making duplication inevitable while naively traversing.
-
-        The error that would be thrown by argparse:
-        - argparse.ArgumentError
-        """
-        return any(
-            arg in action.option_strings
-            for action in parser._actions  # noqa: SLF001
-        )
-
-    if not argument_exists(parser, "--debug"):
-        parser.add_argument(
-            "--debug",
-            help="Enable debug logging",
-            action="store_true",
-            default=False,
-        )
-
-    if not argument_exists(parser, "--option"):
-        parser.add_argument(
-            "--option",
-            help="Nix option to set",
-            nargs=2,
-            metavar=("name", "value"),
-            action=AppendOptionAction,
-            default=[],
-        )
-
-    if not argument_exists(parser, "--flake"):
-        parser.add_argument(
-            "--flake",
-            help="path to the flake where the clan resides in, can be a remote flake or local, can be set through the [CLAN_DIR] environment variable",
-            default=default_flake(),
-            metavar="PATH",
-            type=flake_path,
-        )
-
-
-def register_common_flags(parser: argparse.ArgumentParser) -> None:
-    has_subparsers = False
-    for action in parser._actions:  # noqa: SLF001
-        if isinstance(action, argparse._SubParsersAction):  # noqa: SLF001
-            for _choice, child_parser in action.choices.items():
-                has_subparsers = True
-                register_common_flags(child_parser)
-
-    if not has_subparsers:
-        add_common_flags(parser)
-
-
-def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog=prog,
-        usage="%(prog)s [-h] [SUBCOMMAND]",
-        description="The clan cli tool",
-        epilog=(
-            f"""
-Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli")}
-For more detailed information, visit: {help_hyperlink("docs", "https://docs.clan.lol")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-
-    subparsers = parser.add_subparsers()
-
-    show_parser = subparsers.add_parser(
-        "show",
-        help="Show meta information about the clan",
-        description="Show meta information about the clan",
-        epilog=(
-            """
-This command prints the metadata of a clan.
-
-Examples:
-
-  $ clan show --flake [PATH]
-  Name: My Empty Clan
-  Description: some nice description
-  Icon: A path to the png
-"""
-        ),
-    )
-    show_parser.set_defaults(func=show.show_command)
-
-    parser_backups = subparsers.add_parser(
-        "backups",
-        aliases=["b"],
-        help="Manage backups of clan machines",
-        description="Manage backups of clan machines",
-        epilog=(
-            f"""
-This subcommand provides an interface to backups that clan machines expose.
-
-Examples:
-
-  $ clan backups list [MACHINE]
-  List backups for the machine [MACHINE]
-
-  $ clan backups create [MACHINE]
-  Create a backup for the machine [MACHINE].
-
-  $ clan backups restore [MACHINE] [PROVIDER] [NAME]
-  The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
-  with the name [NAME].
-
-For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    backups.register_parser(parser_backups)
-
-    parser_flake = subparsers.add_parser(
-        "flakes",
-        aliases=["f"],
-        help="Create a clan flake inside the current directory",
-        description="Create a clan flake inside the current directory",
-        epilog=(
-            f"""
-Examples:
-  $ clan flakes create [DIR]
-  Will create a new clan flake in the specified directory and create it if it
-  doesn't exist yet. The flake will be created from a default template.
-
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-
-    clan.register_parser(parser_flake)
-
-    parser_templates = subparsers.add_parser(
-        "templates",
-        help="Subcommands to interact with templates",
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    templates.register_parser(parser_templates)
-
-    parser_flash = subparsers.add_parser(
-        "flash",
-        help="Flashes your machine to an USB drive",
-        description="Flashes your machine to an USB drive",
-        epilog=(
-            f"""
-Examples:
-  $ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
-  Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
-
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
-            """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    flash_cli.register_parser(parser_flash)
-
-    parser_ssh = subparsers.add_parser(
-        "ssh",
-        help="Ssh to a remote machine",
-        description="Ssh to a remote machine",
-        epilog=(
-            f"""
-This subcommand allows seamless ssh access to the nixos-image builders or a machine of your clan.
-
-Examples:
-
-  $ clan ssh [ssh_args ...] berlin`
-
-  Will ssh in to the machine called `berlin`, using the
-  `clan.core.networking.targetHost` specified in its configuration
-
-  $ clan ssh [ssh_args ...] --json [JSON]
-  Will ssh in to the machine based on the deployment information contained in
-  the json string. [JSON] can either be a json formatted string itself, or point
-  towards a file containing the deployment information
-
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    ssh_cli.register_parser(parser_ssh)
-
-    parser_secrets = subparsers.add_parser(
-        "secrets",
-        help="Manage secrets",
-        description="Manage secrets",
-        epilog=(
-            f"""
-This subcommand provides an interface to secrets.
-
-Examples:
-
-  $ clan secrets list [regex]
-  Will list secrets for all managed machines.
-  It accepts an optional regex, allowing easy filtering of returned secrets.
-
-  $ clan secrets get [SECRET]
-  Will display the content of the specified secret.
-
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    secrets.register_parser(parser_secrets)
-
-    parser_facts = subparsers.add_parser(
-        "facts",
-        help="Manage facts",
-        description="Manage facts",
-        epilog=(
-            f"""
-
-This subcommand provides an interface to facts of clan machines.
-Facts are artifacts that a service can generate.
-There are public and secret facts.
-Public facts can be referenced by other machines directly.
-Public facts can include: ip addresses, public keys.
-Secret facts can include: passwords, private keys.
-
-A service is an included clan-module that implements facts generation functionality.
-For example the zerotier module will generate private and public facts.
-In this case the public fact will be the resulting zerotier-ip of the machine.
-The secret fact will be the zerotier-identity-secret, which is used by zerotier
-to prove the machine has control of the zerotier-ip.
-
-Examples:
-
-  $ clan facts generate
-  Will generate facts for all machines.
-
-  $ clan facts generate --service [SERVICE] --regenerate
-  Will regenerate facts, if they are already generated for a specific service.
-  This is especially useful for resetting certain passwords while leaving the rest
-  of the facts for a machine in place.
-
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    facts.register_parser(parser_facts)
-
-    # like facts but with vars instead of facts
-    parser_vars = subparsers.add_parser(
-        "vars",
-        aliases=["va"],
-        help="Manage vars",
-        description="Manage vars",
-        epilog=(
-            f"""
-This subcommand provides an interface to `vars` of clan machines.
-Vars are variables that a service can generate.
-There are public and secret vars.
-Public vars can be referenced by other machines directly.
-Public vars can include: ip addresses, public keys.
-Secret vars can include: passwords, private keys.
-
-A service is an included clan-module that implements vars generation functionality.
-For example the zerotier module will generate private and public vars.
-In this case the public var will be the resulting zerotier-ip of the machine.
-The secret var will be the zerotier-identity-secret, which is used by zerotier
-to prove the machine has control of the zerotier-ip.
-
-Examples:
-
-    $ clan vars generate
-    Will generate vars for all machines.
-
-    $ clan vars generate --service [SERVICE] --regenerate
-    Will regenerate vars, if they are already generated for a specific service.
-    This is especially useful for resetting certain passwords while leaving the rest
-    of the vars for a machine in place.
-
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    vars_cli.register_parser(parser_vars)
-
-    parser_machine = subparsers.add_parser(
-        "machines",
-        aliases=["m"],
-        help="Manage machines and their configuration",
-        description="Manage machines and their configuration",
-        epilog=(
-            f"""
-This subcommand provides an interface to machines managed by Clan.
-
-Examples:
-
-  $ clan machines list
-  List all the machines managed by Clan.
-
-  $ clan machines update [MACHINES]
-  Will update the specified machines [MACHINES], if [MACHINES] is omitted, the command
-  will attempt to update every configured machine.
-
-  $ clan machines install [MACHINE] --target-host [TARGET_HOST]
-  Will install the specified machine [MACHINE] to the specified [TARGET_HOST].
-  If the `--target-host` flag is omitted will try to find host information by
-  checking the deployment configuration inside the specified machine.
-
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    machines.register_parser(parser_machine)
-
-    parser_vms = subparsers.add_parser(
-        "vms", help="Manage virtual machines", description="Manage virtual machines"
-    )
-    vms.register_parser(parser_vms)
-
-    parser_select = subparsers.add_parser(
-        "select",
-        aliases=["se"],
-        help="Select nixos values from the flake",
-        description="Select nixos values from the flake",
-        epilog=(
-            """
-This subcommand provides an interface nix values defined in the flake.
-
-Examples:
-
-  $ clan select nixosConfigurations.*.config.networking.hostName
-    List hostnames of all nixos configurations as JSON.
-
-  $ clan select nixosConfigurations.{jon,alice}.config.clan.core.vars.generators.*.name
-    List all vars generators for jon and alice.
-
-  $ clan select nixosConfigurations.jon.config.envirnonment.systemPackages.1
-    List the first system package for jon.
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    select.register_parser(parser_select)
-
-    parser_state = subparsers.add_parser(
-        "state",
-        aliases=["st"],
-        help="Query state information about machines",
-        description="Query state information about machines",
-        epilog=(
-            f"""
-This subcommand provides an interface to the state managed by Clan.
-
-State can be folders and databases that modules depend on managed by Clan.
-
-State directories can be added to on a per machine basis:
-```
-  config.clan.core.state.[SERVICE_NAME].folders = [
-    "/home"
-    "/root"
-  ];
-```
-Here [SERVICE_NAME] can be set freely, if the user sets them extra `userdata`
-can be a good choice.
-
-Examples:
-
-  $ clan state list [MACHINE]
-  List state of the machines managed by Clan.
-
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
-        """
-        ),
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    state.register_parser(parser_state)
-
-    if argcomplete:
-        argcomplete.autocomplete(parser, exclude=["morph"])
-
-    register_common_flags(parser)
-
-    return parser
-
-
-# this will be the entrypoint under /bin/clan (see pyproject.toml config)
-@profile
-def main() -> None:
-    parser = create_parser()
-    args = parser.parse_args()
-
-    if len(sys.argv) == 1:
-        parser.print_help()
-
-    if debug := getattr(args, "debug", False):
-        setup_logging(logging.DEBUG)
-        log.debug("Debug log activated")
-    else:
-        setup_logging(logging.INFO)
-
-    if not hasattr(args, "func"):
-        return
-
-    # Convert flake path to Flake object with nix_options if flake argument exists
-    if hasattr(args, "flake") and args.flake is not None:
-        args.flake = create_flake_from_args(args)
-
-    try:
-        args.func(args)
-    except ClanError as e:
-        if debug:
-            log.exception("Exited with error")
-        else:
-            log.error("%s", e)
-        sys.exit(1)
-    except KeyboardInterrupt as ex:
-        log.warning("Interrupted by user", exc_info=ex)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()
--- a/pkgs/clan-cli/clan_cli/main.py
+++ b/pkgs/clan-cli/clan_cli/main.py
@@ -1,4 +1,4 @@
-from . import main
+from .cli import main

 if __name__ == "__main__":
    main()
--- a/pkgs/clan-cli/clan_cli/clan/create.py
+++ b/pkgs/clan-cli/clan_cli/clan/create.py
@@ -4,6 +4,7 @@ import logging
 from pathlib import Path

 from clan_lib.clan.create import CreateOptions, create_clan
+from clan_lib.errors import ClanError

 log = logging.getLogger(__name__)

@@ -26,10 +27,10 @@ def register_create_parser(parser: argparse.ArgumentParser) -> None:
    )

    parser.add_argument(
-        "path",
-        type=Path,
-        help="Path where to write the clan template to",
-        default=Path(),
+        "name",
+        type=str,
+        nargs="?",
+        help="Name of the clan to create. If not provided, will prompt for a name.",
    )

    parser.add_argument(
@@ -40,9 +41,18 @@ def register_create_parser(parser: argparse.ArgumentParser) -> None:
    )

    def create_flake_command(args: argparse.Namespace) -> None:
+        # Ask for a path interactively if none provided
+        if args.name is None:
+            user_input = input("Enter a name for the new clan: ").strip()
+            if not user_input:
+                msg = "Error: name is required."
+                raise ClanError(msg)
+
+            args.name = Path(user_input)
+
        create_clan(
            CreateOptions(
-                dest=args.path,
+                dest=Path(args.name),
                template=args.template,
                setup_git=not args.no_git,
                src_flake=args.flake,
--- a/pkgs/clan-cli/clan_cli/cli.py
+++ b/pkgs/clan-cli/clan_cli/cli.py
@@ -0,0 +1,508 @@
+import argparse
+import contextlib
+import logging
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from clan_lib.custom_logger import setup_logging
+from clan_lib.dirs import get_clan_flake_toplevel_or_env
+from clan_lib.errors import ClanError
+from clan_lib.flake import Flake
+
+from . import (
+    backups,
+    clan,
+    secrets,
+    select,
+    state,
+    templates,
+    vms,
+)
+from .arg_actions import AppendOptionAction
+from .clan import show
+from .facts import cli as facts
+from .flash import cli as flash_cli
+from .hyperlink import help_hyperlink
+from .machines import cli as machines
+from .profiler import profile
+from .ssh import deploy_info as ssh_cli
+from .vars import cli as vars_cli
+
+log = logging.getLogger(__name__)
+
+argcomplete: ModuleType | None = None
+with contextlib.suppress(ImportError):
+    import argcomplete  # type: ignore[no-redef]
+
+
+def flake_path(arg: str) -> str:
+    flake_dir = Path(arg).resolve()
+    if flake_dir.exists() and flake_dir.is_dir():
+        return str(flake_dir)
+    return arg
+
+
+def default_flake() -> str | None:
+    val = get_clan_flake_toplevel_or_env()
+    if val:
+        return str(val)
+    return None
+
+
+def create_flake_from_args(args: argparse.Namespace) -> Flake:
+    """Create a Flake object from parsed arguments, including nix_options."""
+    flake_path_str = args.flake
+    nix_options = getattr(args, "option", [])
+    return Flake(flake_path_str, nix_options=nix_options)
+
+
+def add_common_flags(parser: argparse.ArgumentParser) -> None:
+    def argument_exists(parser: argparse.ArgumentParser, arg: str) -> bool:
+        """
+        Check if an argparse argument already exists.
+        This is needed because the aliases subcommand doesn't *really*
+        create an alias - it duplicates the actual parser in the tree
+        making duplication inevitable while naively traversing.
+
+        The error that would be thrown by argparse:
+        - argparse.ArgumentError
+        """
+        return any(
+            arg in action.option_strings
+            for action in parser._actions  # noqa: SLF001
+        )
+
+    if not argument_exists(parser, "--debug"):
+        parser.add_argument(
+            "--debug",
+            help="Enable debug logging",
+            action="store_true",
+            default=False,
+        )
+
+    if not argument_exists(parser, "--option"):
+        parser.add_argument(
+            "--option",
+            help="Nix option to set",
+            nargs=2,
+            metavar=("name", "value"),
+            action=AppendOptionAction,
+            default=[],
+        )
+
+    if not argument_exists(parser, "--flake"):
+        parser.add_argument(
+            "--flake",
+            help="path to the flake where the clan resides in, can be a remote flake or local, can be set through the [CLAN_DIR] environment variable",
+            default=default_flake(),
+            metavar="PATH",
+            type=flake_path,
+        )
+
+
+def register_common_flags(parser: argparse.ArgumentParser) -> None:
+    has_subparsers = False
+    for action in parser._actions:  # noqa: SLF001
+        if isinstance(action, argparse._SubParsersAction):  # noqa: SLF001
+            for _choice, child_parser in action.choices.items():
+                has_subparsers = True
+                register_common_flags(child_parser)
+
+    if not has_subparsers:
+        add_common_flags(parser)
+
+
+def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=prog,
+        usage="%(prog)s [-h] [SUBCOMMAND]",
+        description="The clan cli tool",
+        epilog=(
+            f"""
+Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli")}
+For more detailed information, visit: {help_hyperlink("docs", "https://docs.clan.lol")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers()
+
+    show_parser = subparsers.add_parser(
+        "show",
+        help="Show meta information about the clan",
+        description="Show meta information about the clan",
+        epilog=(
+            """
+This command prints the metadata of a clan.
+
+Examples:
+
+  $ clan show --flake [PATH]
+  Name: My Empty Clan
+  Description: some nice description
+  Icon: A path to the png
+"""
+        ),
+    )
+    show_parser.set_defaults(func=show.show_command)
+
+    parser_backups = subparsers.add_parser(
+        "backups",
+        aliases=["b"],
+        help="Manage backups of clan machines",
+        description="Manage backups of clan machines",
+        epilog=(
+            f"""
+This subcommand provides an interface to backups that clan machines expose.
+
+Examples:
+
+  $ clan backups list [MACHINE]
+  List backups for the machine [MACHINE]
+
+  $ clan backups create [MACHINE]
+  Create a backup for the machine [MACHINE].
+
+  $ clan backups restore [MACHINE] [PROVIDER] [NAME]
+  The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
+  with the name [NAME].
+
+For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    backups.register_parser(parser_backups)
+
+    parser_flake = subparsers.add_parser(
+        "flakes",
+        aliases=["f"],
+        help="Create a clan flake inside the current directory",
+        description="Create a clan flake inside the current directory",
+        epilog=(
+            f"""
+Examples:
+  $ clan flakes create [DIR]
+  Will create a new clan flake in the specified directory and create it if it
+  doesn't exist yet. The flake will be created from a default template.
+
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    clan.register_parser(parser_flake)
+
+    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)
+
+    parser_flash = subparsers.add_parser(
+        "flash",
+        help="Flashes your machine to an USB drive",
+        description="Flashes your machine to an USB drive",
+        epilog=(
+            f"""
+Examples:
+  $ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
+  Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
+
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
+            """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    flash_cli.register_parser(parser_flash)
+
+    parser_ssh = subparsers.add_parser(
+        "ssh",
+        help="Ssh to a remote machine",
+        description="Ssh to a remote machine",
+        epilog=(
+            f"""
+This subcommand allows seamless ssh access to the nixos-image builders or a machine of your clan.
+
+Examples:
+
+  $ clan ssh [ssh_args ...] berlin`
+
+  Will ssh in to the machine called `berlin`, using the
+  `clan.core.networking.targetHost` specified in its configuration
+
+  $ clan ssh [ssh_args ...] --json [JSON]
+  Will ssh in to the machine based on the deployment information contained in
+  the json string. [JSON] can either be a json formatted string itself, or point
+  towards a file containing the deployment information
+
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    ssh_cli.register_parser(parser_ssh)
+
+    parser_secrets = subparsers.add_parser(
+        "secrets",
+        help="Manage secrets",
+        description="Manage secrets",
+        epilog=(
+            f"""
+This subcommand provides an interface to secrets.
+
+Examples:
+
+  $ clan secrets list [regex]
+  Will list secrets for all managed machines.
+  It accepts an optional regex, allowing easy filtering of returned secrets.
+
+  $ clan secrets get [SECRET]
+  Will display the content of the specified secret.
+
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    secrets.register_parser(parser_secrets)
+
+    parser_facts = subparsers.add_parser(
+        "facts",
+        help="Manage facts",
+        description="Manage facts",
+        epilog=(
+            f"""
+Note: Facts are being deprecated, please use Vars instead.
+For a migration guide visit: {help_hyperlink("vars", "https://docs.clan.lol/guides/migrations/migration-facts-vars")}
+
+This subcommand provides an interface to facts of clan machines.
+Facts are artifacts that a service can generate.
+There are public and secret facts.
+Public facts can be referenced by other machines directly.
+Public facts can include: ip addresses, public keys.
+Secret facts can include: passwords, private keys.
+
+A service is an included clan-module that implements facts generation functionality.
+For example the zerotier module will generate private and public facts.
+In this case the public fact will be the resulting zerotier-ip of the machine.
+The secret fact will be the zerotier-identity-secret, which is used by zerotier
+to prove the machine has control of the zerotier-ip.
+
+Examples:
+
+  $ clan facts generate
+  Will generate facts for all machines.
+
+  $ clan facts generate --service [SERVICE] --regenerate
+  Will regenerate facts, if they are already generated for a specific service.
+  This is especially useful for resetting certain passwords while leaving the rest
+  of the facts for a machine in place.
+
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    facts.register_parser(parser_facts)
+
+    # like facts but with vars instead of facts
+    parser_vars = subparsers.add_parser(
+        "vars",
+        aliases=["va"],
+        help="Manage vars",
+        description="Manage vars",
+        epilog=(
+            f"""
+This subcommand provides an interface to `vars` of clan machines.
+Vars are variables that a service can generate.
+There are public and secret vars.
+Public vars can be referenced by other machines directly.
+Public vars can include: ip addresses, public keys.
+Secret vars can include: passwords, private keys.
+
+A service is an included clan-module that implements vars generation functionality.
+For example the zerotier module will generate private and public vars.
+In this case the public var will be the resulting zerotier-ip of the machine.
+The secret var will be the zerotier-identity-secret, which is used by zerotier
+to prove the machine has control of the zerotier-ip.
+
+Examples:
+
+    $ clan vars generate
+    Will generate vars for all machines.
+
+    $ clan vars generate --service [SERVICE] --regenerate
+    Will regenerate vars, if they are already generated for a specific service.
+    This is especially useful for resetting certain passwords while leaving the rest
+    of the vars for a machine in place.
+
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    vars_cli.register_parser(parser_vars)
+
+    parser_machine = subparsers.add_parser(
+        "machines",
+        aliases=["m"],
+        help="Manage machines and their configuration",
+        description="Manage machines and their configuration",
+        epilog=(
+            f"""
+This subcommand provides an interface to machines managed by Clan.
+
+Examples:
+
+  $ clan machines list
+  List all the machines managed by Clan.
+
+  $ clan machines update [MACHINES]
+  Will update the specified machines [MACHINES], if [MACHINES] is omitted, the command
+  will attempt to update every configured machine.
+
+  $ clan machines install [MACHINE] --target-host [TARGET_HOST]
+  Will install the specified machine [MACHINE] to the specified [TARGET_HOST].
+  If the `--target-host` flag is omitted will try to find host information by
+  checking the deployment configuration inside the specified machine.
+
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    machines.register_parser(parser_machine)
+
+    parser_vms = subparsers.add_parser(
+        "vms", help="Manage virtual machines", description="Manage virtual machines"
+    )
+    vms.register_parser(parser_vms)
+
+    parser_select = subparsers.add_parser(
+        "select",
+        aliases=["se"],
+        help="Select nixos values from the flake",
+        description="Select nixos values from the flake",
+        epilog=(
+            """
+This subcommand provides an interface nix values defined in the flake.
+
+Examples:
+
+  $ clan select nixosConfigurations.*.config.networking.hostName
+    List hostnames of all nixos configurations as JSON.
+
+  $ clan select nixosConfigurations.{jon,alice}.config.clan.core.vars.generators.*.name
+    List all vars generators for jon and alice.
+
+  $ clan select nixosConfigurations.jon.config.envirnonment.systemPackages.1
+    List the first system package for jon.
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    select.register_parser(parser_select)
+
+    parser_state = subparsers.add_parser(
+        "state",
+        aliases=["st"],
+        help="Query state information about machines",
+        description="Query state information about machines",
+        epilog=(
+            f"""
+This subcommand provides an interface to the state managed by Clan.
+
+State can be folders and databases that modules depend on managed by Clan.
+
+State directories can be added to on a per machine basis:
+```
+  config.clan.core.state.[SERVICE_NAME].folders = [
+    "/home"
+    "/root"
+  ];
+```
+Here [SERVICE_NAME] can be set freely, if the user sets them extra `userdata`
+can be a good choice.
+
+Examples:
+
+  $ clan state list [MACHINE]
+  List state of the machines managed by Clan.
+
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
+        """
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    state.register_parser(parser_state)
+
+    if argcomplete:
+        argcomplete.autocomplete(parser, exclude=["morph"])
+
+    register_common_flags(parser)
+
+    return parser
+
+
+# this will be the entrypoint under /bin/clan (see pyproject.toml config)
+@profile
+def main() -> None:
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if len(sys.argv) == 1:
+        parser.print_help()
+
+    if debug := getattr(args, "debug", False):
+        setup_logging(logging.DEBUG)
+        log.debug("Debug log activated")
+    else:
+        setup_logging(logging.INFO)
+
+    if not hasattr(args, "func"):
+        return
+
+    # Convert flake path to Flake object with nix_options if flake argument exists
+    if hasattr(args, "flake") and args.flake is not None:
+        args.flake = create_flake_from_args(args)
+
+    try:
+        args.func(args)
+    except ClanError as e:
+        if debug:
+            log.exception("Exited with error")
+        else:
+            log.error("%s", e)
+        sys.exit(1)
+    except KeyboardInterrupt as ex:
+        log.warning("Interrupted by user", exc_info=ex)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
--- a/pkgs/clan-cli/clan_cli/templates/init.py
+++ b/pkgs/clan-cli/clan_cli/templates/init.py
@@ -1,6 +1,7 @@
 # !/usr/bin/env python3
 import argparse

+from .apply import register_apply_parser
 from .list import register_list_parser


@@ -12,5 +13,9 @@ def register_parser(parser: argparse.ArgumentParser) -> None:
        help="the command to run",
        required=True,
    )
-    list_parser = subparser.add_parser("list", help="List avilable templates")
+    list_parser = subparser.add_parser("list", help="List available templates")
+    apply_parser = subparser.add_parser(
+        "apply", help="Apply a template of the specified type"
+    )
    register_list_parser(list_parser)
+    register_apply_parser(apply_parser)
--- a/pkgs/clan-cli/clan_cli/templates/apply.py
+++ b/pkgs/clan-cli/clan_cli/templates/apply.py
@@ -0,0 +1,15 @@
+import argparse
+
+from .apply_disk import register_apply_disk_template_parser
+
+
+def register_apply_parser(parser: argparse.ArgumentParser) -> None:
+    subparser = parser.add_subparsers(
+        title="template_type",
+        description="the template type to apply",
+        help="the template type to apply",
+        required=True,
+    )
+    disk_parser = subparser.add_parser("disk", help="Apply a disk template")
+
+    register_apply_disk_template_parser(disk_parser)
--- a/pkgs/clan-cli/clan_cli/templates/apply_disk.py
+++ b/pkgs/clan-cli/clan_cli/templates/apply_disk.py
@@ -0,0 +1,82 @@
+import argparse
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+from clan_lib.machines.machines import Machine
+from clan_lib.templates.disk import set_machine_disk_schema
+
+from clan_cli.completions import (
+    add_dynamic_completer,
+    complete_machines,
+)
+
+log = logging.getLogger(__name__)
+
+
+class AppendSetAction(argparse.Action):
+    def __init__(self, option_strings: str, dest: str, **kwargs: Any) -> None:
+        super().__init__(option_strings, dest, **kwargs)
+
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: str | Sequence[str] | None,
+        option_string: str | None = None,
+    ) -> None:
+        lst = getattr(namespace, self.dest)
+        assert isinstance(values, list), "values must be a list"
+        lst.append((values[0], values[1]))
+
+
+def apply_command(args: argparse.Namespace) -> None:
+    """Apply a disk template to a machine."""
+    set_tuples: list[tuple[str, str]] = args.set
+
+    placeholders = dict(set_tuples)
+
+    set_machine_disk_schema(
+        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.machine}' ")
+
+
+def register_apply_disk_template_parser(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "template",
+        type=str,
+        help="The name of the disk template to apply",
+    )
+    machine_action = parser.add_argument(
+        "machine",
+        type=str,
+        help="The machine to apply the template to",
+    )
+    add_dynamic_completer(machine_action, complete_machines)
+    parser.add_argument(
+        "--set",
+        help="Set a placeholder in the template to a value",
+        nargs=2,
+        metavar=("placeholder", "value"),
+        action=AppendSetAction,
+        default=[],
+    )
+    parser.add_argument(
+        "--force",
+        help="Force apply the template even if the machine already has a disk schema",
+        action="store_true",
+        default=False,
+    )
+    parser.add_argument(
+        "--skip-hardware-check",
+        help="Disables hardware checking. By default this command checks that the facter.json report exists and validates provided options",
+        action="store_true",
+        default=False,
+    )
+
+    parser.set_defaults(func=apply_command)
--- a/pkgs/clan-cli/clan_cli/tests/helpers/cli.py
+++ b/pkgs/clan-cli/clan_cli/tests/helpers/cli.py
@@ -2,7 +2,7 @@ import argparse
 import logging
 import shlex

-from clan_cli import create_flake_from_args, create_parser
+from clan_cli.cli import create_flake_from_args, create_parser
 from clan_lib.custom_logger import print_trace

 log = logging.getLogger(__name__)
--- a/pkgs/clan-cli/clan_cli/tests/test_modules.py
+++ b/pkgs/clan-cli/clan_cli/tests/test_modules.py
@@ -5,7 +5,6 @@ from typing import TYPE_CHECKING
 import pytest
 from clan_cli.machines.create import CreateOptions, create_machine
 from clan_cli.tests.fixtures_flakes import FlakeForTest
-from clan_lib.api.modules import list_modules
 from clan_lib.flake import Flake
 from clan_lib.nix import nix_eval, run
 from clan_lib.nix_models.clan import (
@@ -16,6 +15,7 @@ from clan_lib.nix_models.clan import (
 )
 from clan_lib.persist.inventory_store import InventoryStore
 from clan_lib.persist.util import set_value_by_path
+from clan_lib.services.modules import list_service_modules

 if TYPE_CHECKING:
    from .age_keys import KeyPair
@@ -27,10 +27,9 @@ from clan_lib.machines.machines import Machine as MachineMachine
@pytest.mark.with_core
 def test_list_modules(test_flake_with_core: FlakeForTest) -> None:
    base_path = test_flake_with_core.path
-    modules_info = list_modules(str(base_path))
+    modules_info = list_service_modules(Flake(str(base_path)))

-    assert "localModules" in modules_info
-    assert "modulesPerSource" in modules_info
+    assert "modules" in modules_info


@pytest.mark.impure
--- a/pkgs/clan-cli/clan_lib/machines/actions.py
+++ b/pkgs/clan-cli/clan_lib/machines/actions.py
@@ -65,14 +65,14 @@ def get_machine(flake: Flake, name: str) -> InventoryMachine:
        InventoryMachine: An instance representing the machine's inventory details.

    Raises:
-        ClanError: If the machine with the specified name is not found in the inventory.
+        ClanError: If the machine with the specified name is not found in the clan
    """
    inventory_store = InventoryStore(flake=flake)
    inventory = inventory_store.read()

    machine_inv = inventory.get("machines", {}).get(name)
    if machine_inv is None:
-        msg = f"Machine {name} not found in inventory"
+        msg = f"Machine {name} does not exist"
        raise ClanError(msg)

    return InventoryMachine(**machine_inv)
--- a/pkgs/clan-cli/clan_lib/machines/hardware.py
+++ b/pkgs/clan-cli/clan_lib/machines/hardware.py
@@ -118,7 +118,7 @@ def run_machine_hardware_info(
    commit_file(
        hw_file,
        opts.machine.flake.path,
-        f"machines/{opts.machine}/{hw_file.name}: update hardware configuration",
+        f"machines/{opts.machine.name}/{hw_file.name}: update hardware configuration",
    )
    try:
        get_machine_target_platform(opts.machine)
--- a/pkgs/clan-cli/clan_lib/machines/list.py
+++ b/pkgs/clan-cli/clan_lib/machines/list.py
@@ -5,13 +5,13 @@ from dataclasses import dataclass
 from clan_cli.machines.hardware import HardwareConfig

 from clan_lib.api import API
-from clan_lib.api.disk import MachineDiskMatter
-from clan_lib.api.modules import parse_frontmatter
 from clan_lib.dirs import specific_machine_dir
 from clan_lib.flake import Flake
 from clan_lib.machines.actions import get_machine, list_machines
 from clan_lib.machines.machines import Machine
 from clan_lib.nix_models.clan import InventoryMachine
+from clan_lib.services.modules import parse_frontmatter
+from clan_lib.templates.disk import MachineDiskMatter

 log = logging.getLogger(__name__)

--- a/pkgs/clan-cli/clan_lib/services/instances.py
+++ b/pkgs/clan-cli/clan_lib/services/instances.py
@@ -0,0 +1,115 @@
+from typing import TypedDict
+
+from clan_lib.api import API
+from clan_lib.errors import ClanError
+from clan_lib.flake.flake import Flake
+from clan_lib.nix_models.clan import (
+    InventoryInstanceModule,
+    InventoryInstanceRolesType,
+    InventoryInstancesType,
+    InventoryMachinesType,
+)
+from clan_lib.persist.inventory_store import InventoryStore
+from clan_lib.persist.util import set_value_by_path
+from clan_lib.services.modules import (
+    get_service_module,
+)
+
+# TODO: move imports out of cli/__init__.py causing import cycles
+# from clan_lib.machines.actions import list_machines
+
+
+@API.register
+def list_service_instances(flake: Flake) -> InventoryInstancesType:
+    """
+    Returns all currently present service instances including their full configuration
+    """
+
+    inventory_store = InventoryStore(flake)
+    inventory = inventory_store.read()
+    instances = inventory.get("instances", {})
+    return instances
+
+
+def collect_tags(machines: InventoryMachinesType) -> set[str]:
+    res = set()
+    for _, machine in machines.items():
+        res |= set(machine.get("tags", []))
+
+    return res
+
+
+# Removed 'module' ref - Needs to be passed seperately
+class InstanceConfig(TypedDict):
+    roles: InventoryInstanceRolesType
+
+
+@API.register
+def create_service_instance(
+    flake: Flake,
+    module_ref: InventoryInstanceModule,
+    instance_name: str,
+    instance_config: InstanceConfig,
+) -> None:
+    module = get_service_module(flake, module_ref)
+
+    inventory_store = InventoryStore(flake)
+    inventory = inventory_store.read()
+
+    instances = inventory.get("instances", {})
+    if instance_name in instances:
+        msg = f"service instance '{instance_name}' already exists."
+        raise ClanError(msg)
+
+    target_roles = instance_config.get("roles")
+    if not target_roles:
+        msg = "Creating a service instance requires adding roles"
+        raise ClanError(msg)
+
+    available_roles = set(module.get("roles", {}).keys())
+
+    unavailable_roles = list(filter(lambda r: r not in available_roles, target_roles))
+    if unavailable_roles:
+        msg = f"Unknown roles: {unavailable_roles}. Use one of {available_roles}"
+        raise ClanError(msg)
+
+    role_configs = instance_config.get("roles")
+    if not role_configs:
+        return
+
+    ## Validate machine references
+    all_machines = inventory.get("machines", {})
+    available_machine_refs = set(all_machines.keys())
+    available_tag_refs = collect_tags(all_machines)
+
+    for role_name, role_members in role_configs.items():
+        machine_refs = role_members.get("machines")
+        msg = f"Role: '{role_name}' - "
+        if machine_refs:
+            unavailable_machines = list(
+                filter(lambda m: m not in available_machine_refs, machine_refs)
+            )
+            if unavailable_machines:
+                msg += f"Unknown machine reference: {unavailable_machines}. Use one of {available_machine_refs}"
+                raise ClanError(msg)
+
+        tag_refs = role_members.get("tags")
+        if tag_refs:
+            unavailable_tags = list(
+                filter(lambda m: m not in available_tag_refs, tag_refs)
+            )
+
+            if unavailable_tags:
+                msg += (
+                    f"Unknown tags: {unavailable_tags}. Use one of {available_tag_refs}"
+                )
+                raise ClanError(msg)
+
+    # TODO:
+    # Validate instance_config roles settings against role schema
+
+    set_value_by_path(inventory, f"instances.{instance_name}", instance_config)
+    set_value_by_path(inventory, f"instances.{instance_name}.module", module_ref)
+    inventory_store.write(
+        inventory, message=f"services: instance '{instance_name}' init"
+    )
--- a/pkgs/clan-cli/clan_lib/services/modules.py
+++ b/pkgs/clan-cli/clan_lib/services/modules.py
@@ -4,10 +4,10 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, TypedDict

+from clan_lib.api import API
 from clan_lib.errors import ClanError
 from clan_lib.flake import Flake
-
-from . import API
+from clan_lib.nix_models.clan import InventoryInstanceModuleType


 class CategoryInfo(TypedDict):
@@ -154,22 +154,96 @@ class ModuleInfo(TypedDict):
    roles: dict[str, None]


-class ModuleLists(TypedDict):
-    modulesPerSource: dict[str, dict[str, ModuleInfo]]
-    localModules: dict[str, ModuleInfo]
+class ModuleList(TypedDict):
+    modules: dict[str, dict[str, ModuleInfo]]


@API.register
-def list_modules(base_path: str) -> ModuleLists:
+def list_service_modules(flake: Flake) -> ModuleList:
    """
    Show information about a module
    """
-    flake = Flake(base_path)
-    modules = flake.select(
-        "clanInternals.inventoryClass.{?modulesPerSource,?localModules}"
-    )
+    modules = flake.select("clanInternals.inventoryClass.modulesPerSource")

-    return modules
+    return ModuleList({"modules": modules})
+
+
+@API.register
+def get_service_module(
+    flake: Flake, module_ref: InventoryInstanceModuleType
+) -> ModuleInfo:
+    """
+    Returns the module information for a given module reference
+
+    :param module_ref: The module reference to get the information for
+    :return: Dict of module information
+    :raises ClanError: If the module_ref is invalid or missing required fields
+    """
+
+    input_name, module_name = check_service_module_ref(flake, module_ref)
+
+    avilable_modules = list_service_modules(flake)
+    module_set = avilable_modules.get("modules", {}).get(input_name)
+
+    assert module_set is not None  # Since check_service_module_ref already checks this
+
+    module = module_set.get(module_name)
+
+    assert module is not None  # Since check_service_module_ref already checks this
+
+    return module
+
+
+def check_service_module_ref(
+    flake: Flake,
+    module_ref: InventoryInstanceModuleType,
+) -> tuple[str, str]:
+    """
+    Checks if the module reference is valid
+
+    :param module_ref: The module reference to check
+    :raises ClanError: If the module_ref is invalid or missing required fields
+    """
+    avilable_modules = list_service_modules(flake)
+
+    input_ref = module_ref.get("input", None)
+    if input_ref is None:
+        msg = "Setting module_ref.input is currently required"
+        raise ClanError(msg)
+
+    module_set = avilable_modules.get("modules", {}).get(input_ref)
+
+    if module_set is None:
+        msg = f"module set for input '{input_ref}' not found"
+        msg += f"\nAvilable input_refs: {avilable_modules.get('modules', {}).keys()}"
+        raise ClanError(msg)
+
+    module_name = module_ref.get("name")
+    assert module_name
+    module = module_set.get(module_name)
+    if module is None:
+        msg = f"module with name '{module_name}' not found"
+        raise ClanError(msg)
+
+    return (input_ref, module_name)
+
+
+@API.register
+def get_service_module_schema(
+    flake: Flake, module_ref: InventoryInstanceModuleType
+) -> dict[str, Any]:
+    """
+    Returns the schema for a service module
+
+    :param module_ref: The module reference to get the schema for
+    :return: Dict of schemas for the service module roles
+    :raises ClanError: If the module_ref is invalid or missing required fields
+    """
+    input_name, module_name = check_service_module_ref(flake, module_ref)
+
+    return flake.select(
+        f"clanInternals.inventoryClass.moduleSchemas.{input_name}.{module_name}"
+    )


@dataclass
--- a/pkgs/clan-cli/clan_lib/templates/disk.py
+++ b/pkgs/clan-cli/clan_lib/templates/disk.py
@@ -6,12 +6,12 @@ from typing import Any, TypedDict
 from uuid import uuid4

 from clan_lib.api import API
-from clan_lib.api.modules import Frontmatter, extract_frontmatter
 from clan_lib.dirs import TemplateType, clan_templates
 from clan_lib.errors import ClanError
 from clan_lib.git import commit_file
 from clan_lib.machines.hardware import HardwareConfig, get_machine_hardware_config
 from clan_lib.machines.machines import Machine
+from clan_lib.services.modules import Frontmatter, extract_frontmatter

 log = logging.getLogger(__name__)

@@ -72,8 +72,18 @@ templates: dict[str, dict[str, Callable[[dict[str, Any]], Placeholder]]] = {
 }


+def get_empty_placeholder(label: str) -> Placeholder:
+    return Placeholder(
+        label,
+        options=None,
+        required=not label.endswith("*"),
+    )
+
+
@API.register
-def get_machine_disk_schemas(machine: Machine) -> dict[str, DiskSchema]:
+def get_machine_disk_schemas(
+    machine: Machine, check_hw: bool = True
+) -> dict[str, DiskSchema]:
    """
    Get the available disk schemas.
    This function reads the disk schemas from the templates directory and returns them as a dictionary.
@@ -89,11 +99,13 @@ def get_machine_disk_schemas(machine: Machine) -> dict[str, DiskSchema]:
    hw_report = {}

    hw_report_path = HardwareConfig.NIXOS_FACTER.config_path(machine)
-    if not hw_report_path.exists():
+    if check_hw and not hw_report_path.exists():
        msg = "Hardware configuration missing"
        raise ClanError(msg)
-    with hw_report_path.open("r") as hw_report_file:
-        hw_report = json.load(hw_report_file)
+
+    if hw_report_path.exists():
+        with hw_report_path.open("r") as hw_report_file:
+            hw_report = json.load(hw_report_file)

    for disk_template in disk_templates.iterdir():
        if disk_template.is_dir():
@@ -109,7 +121,10 @@ def get_machine_disk_schemas(machine: Machine) -> dict[str, DiskSchema]:
            placeholders = {}

            if placeholder_getters:
-                placeholders = {k: v(hw_report) for k, v in placeholder_getters.items()}
+                placeholders = {
+                    k: v(hw_report) if hw_report else get_empty_placeholder(k)
+                    for k, v in placeholder_getters.items()
+                }

            raw_readme = (disk_template / "README.md").read_text()
            frontmatter, readme = extract_frontmatter(
@@ -139,34 +154,41 @@ def set_machine_disk_schema(
    # Use get disk schemas to get the placeholders and their options
    placeholders: dict[str, str],
    force: bool = False,
+    check_hw: bool = True,
 ) -> None:
    """
    Set the disk placeholders of the template
    """
+    # Ensure the machine exists
+    machine.get_inv_machine()
+
    # Assert the hw-config must exist before setting the disk
    hw_config = get_machine_hardware_config(machine)
    hw_config_path = hw_config.config_path(machine)

-    if not hw_config_path.exists():
-        msg = "Hardware configuration must exist before applying disk schema"
-        raise ClanError(msg)
+    if check_hw:
+        if not hw_config_path.exists():
+            msg = "Hardware configuration must exist for checking."
+            msg += f"\nrun 'clan machines update-hardware-config {machine.name}' to generate a hardware report. Alternatively disable hardware checking to skip this check"
+            raise ClanError(msg)

-    if hw_config != HardwareConfig.NIXOS_FACTER:
-        msg = "Hardware configuration must use type FACTER for applying disk schema automatically"
-        raise ClanError(msg)
+        if hw_config != HardwareConfig.NIXOS_FACTER:
+            msg = "Hardware configuration must use type FACTER for applying disk schema automatically"
+            raise ClanError(msg)

    disk_schema_path = clan_templates(TemplateType.DISK) / f"{schema_name}/default.nix"

    if not disk_schema_path.exists():
-        msg = f"Disk schema not found at {disk_schema_path}"
+        msg = f"Disk schema '{schema_name}' not found at {disk_schema_path}"
+        msg += f"\nAvailable schemas: {', '.join([p.name for p in clan_templates(TemplateType.DISK).iterdir()])}"
        raise ClanError(msg)

    # Check that the placeholders are valid
-    disk_schema = get_machine_disk_schemas(machine)[schema_name]
+    disk_schema = get_machine_disk_schemas(machine, check_hw)[schema_name]
    # 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
@@ -183,12 +205,15 @@ def set_machine_disk_schema(
                description=f"Available placeholders: {disk_schema.placeholders.keys()}",
            )

-        # Invalid value. Check if the value is one of the provided options
-        if ph.options and placeholder_value not in ph.options:
+        # Checking invalid value: if the value is one of the provided options
+        if check_hw and ph.options and placeholder_value not in ph.options:
            msg = (
                f"Invalid value {placeholder_value} for placeholder {placeholder_name}"
            )
-            raise ClanError(msg, description=f"Valid options: {ph.options}")
+            raise ClanError(
+                msg,
+                description=f"Valid options: \n{'\n'.join(ph.options)}",
+            )

    placeholders_toml = "\n".join(
        [f"""# {k} = "{v}" """ for k, v in placeholders.items() if v is not None]
@@ -221,6 +246,9 @@ def set_machine_disk_schema(
            disk_config.write(header)
            disk_config.write(config_str)

+        # TODO: return files to commit
+        # Don't commit here
+        # The top level command will usually collect files and commit them in batches
        commit_file(
            disko_file_path,
            machine.flake.path,
--- a/pkgs/clan-cli/clan_lib/templates/filesystem.py
+++ b/pkgs/clan-cli/clan_lib/templates/filesystem.py
@@ -1,3 +1,4 @@
+import shutil
 from pathlib import Path

 from clan_lib.flake import Flake
@@ -35,5 +36,7 @@ def copy_from_nixstore(src: Path, dest: Path) -> None:
    Uses `cp -r` to recursively copy the directory.
    Ensures the destination directory is writable by the user.
    """
-    run(["cp", "-r", str(src), str(dest)])
-    run(["chmod", "-R", "u+w", str(dest)])
+    shutil.copytree(src, dest, dirs_exist_ok=True, symlinks=True)
+    run(
+        ["chmod", "-R", "u+w", str(dest)]
+    )  # Ensure the destination is writable by the user
--- a/pkgs/clan-cli/clan_lib/tests/test_create.py
+++ b/pkgs/clan-cli/clan_lib/tests/test_create.py
@@ -16,8 +16,6 @@ from clan_cli.secrets.sops import maybe_get_admin_public_keys
 from clan_cli.secrets.users import add_user
 from clan_cli.vars.generate import get_generators, run_generators

-from clan_lib.api.disk import hw_main_disk_options, set_machine_disk_schema
-from clan_lib.api.modules import list_modules
 from clan_lib.cmd import RunOpts, run
 from clan_lib.dirs import specific_machine_dir
 from clan_lib.errors import ClanError
@@ -33,7 +31,9 @@ from clan_lib.nix_models.clan import (
 from clan_lib.nix_models.clan import InventoryMachineDeploy as MachineDeploy
 from clan_lib.persist.inventory_store import InventoryStore
 from clan_lib.persist.util import set_value_by_path
+from clan_lib.services.modules import list_service_modules
 from clan_lib.ssh.remote import Remote, check_machine_ssh_login
+from clan_lib.templates.disk import hw_main_disk_options, set_machine_disk_schema

 log = logging.getLogger(__name__)

@@ -206,9 +206,9 @@ def test_clan_create_api(
    store = InventoryStore(clan_dir_flake)
    inventory = store.read()

-    modules = list_modules(str(clan_dir_flake.path))
+    modules = list_service_modules(clan_dir_flake)
    assert (
-        modules["modulesPerSource"]["clan-core"]["admin"]["manifest"]["name"]
+        modules["modules"]["clan-core"]["admin"]["manifest"]["name"]
        == "clan-core/admin"
    )

--- a/pkgs/clan-cli/docs.py
+++ b/pkgs/clan-cli/docs.py
@@ -4,7 +4,7 @@ import sys
 from dataclasses import dataclass
 from pathlib import Path

-from clan_cli import create_parser
+from clan_cli.cli import create_parser

 hidden_subcommands = ["machine", "b", "f", "m", "se", "st", "va"]

--- a/pkgs/clan-cli/openapi.py
+++ b/pkgs/clan-cli/openapi.py
@@ -41,7 +41,7 @@ TOP_LEVEL_RESOURCES = {
    "secret",  # sops & key operations
    "log",  # log operations
    "generator",  # vars generators operations
-    "module",  # module (clan.service) management
+    "service",  # clan.service management
    "system",  # system operations
 }

--- a/pkgs/clan-cli/pyproject.toml
+++ b/pkgs/clan-cli/pyproject.toml
@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "clan"
 description = "clan cli tool"
 dynamic = ["version"]
-scripts = { clan = "clan_cli:main" }
+scripts = { clan = "clan_cli.cli:main" }
 license = { text = "MIT" }

 [project.urls]
--- a/templates/clan/default/clan.nix
+++ b/templates/clan/default/clan.nix
@@ -2,6 +2,11 @@
  # Ensure this is unique among all clans you want to use.
  meta.name = "__CHANGE_ME__";

+  inventory.machines = {
+    # Define machines here.
+    # jon = { };
+  };
+
  # Docs: See https://docs.clan.lol/reference/clanServices
  inventory.instances = {

--- a/templates/clan/default/modules/disko.nix
+++ b/templates/clan/default/modules/disko.nix
@@ -1,61 +0,0 @@
-{
-  lib,
-  clan-core,
-  config,
-  ...
-}:
-
-let
-  suffix = config.clan.core.vars.generators.disk-id.files.diskId.value;
-in
-{
-  imports = [
-    clan-core.clanModules.disk-id
-  ];
-
-  # DO NOT EDIT THIS FILE AFTER INSTALLATION of a machine
-  # Otherwise your system might not boot because of missing partitions / filesystems
-  boot.loader.grub.efiSupport = lib.mkDefault true;
-  boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
-  disko.devices = {
-    disk = {
-      "main" = {
-        # suffix is to prevent disk name collisions
-        name = "main-" + suffix;
-        type = "disk";
-        # Set the following in flake.nix for each maschine:
-        # device = <uuid>;
-        content = {
-          type = "gpt";
-          partitions = {
-            "boot" = {
-              size = "1M";
-              type = "EF02"; # for grub MBR
-              priority = 1;
-            };
-            "ESP" = {
-              size = "512M";
-              type = "EF00";
-              content = {
-                type = "filesystem";
-                format = "vfat";
-                mountpoint = "/boot";
-                mountOptions = [ "nofail" ];
-              };
-            };
-            "root" = {
-              size = "100%";
-              content = {
-                type = "filesystem";
-                format = "ext4";
-                # format = "btrfs";
-                # format = "bcachefs";
-                mountpoint = "/";
-              };
-            };
-          };
-        };
-      };
-    };
-  };
-}
--- a/templates/clan/default/modules/shared.nix
+++ b/templates/clan/default/modules/shared.nix
@@ -1,28 +0,0 @@
-{
-  clan-core,
-  # Optional, if you want to access other flakes:
-  # self,
-  ...
-}:
-{
-  imports = [
-    clan-core.clanModules.user-password
-  ];
-
-  # Locale service discovery and mDNS
-  services.avahi.enable = true;
-
-  # generate a random password for our user below
-  # can be read using `clan secrets get <machine-name>-user-password` command
-  clan.user-password.user = "user";
-  users.users.user = {
-    isNormalUser = true;
-    extraGroups = [
-      "wheel"
-      "networkmanager"
-      "video"
-      "input"
-    ];
-    uid = 1000;
-  };
-}
--- a/templates/clan/flake-parts/clan.nix
+++ b/templates/clan/flake-parts/clan.nix
@@ -1,81 +1,50 @@
-{ self }:
 {
-  meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.
+  # Ensure this is unique among all clans you want to use.
+  meta.name = "__CHANGE_ME__";

-  inherit self;
+  inventory.machines = {
+    # Define machines here.
+    # jon = { };
+  };
+
+  # Docs: See https://docs.clan.lol/reference/clanServices
+  inventory.instances = {
+
+    # Docs: https://docs.clan.lol/reference/clanServices/admin/
+    # Admin service for managing machines
+    # This service adds a root password and SSH access.
+    admin = {
+      roles.default.tags.all = { };
+      roles.default.settings.allowedKeys = {
+        # Insert the public key that you want to use for SSH access.
+        # All keys will have ssh access to all machines ("tags.all" means 'all machines').
+        # Alternatively set 'users.users.root.openssh.authorizedKeys.keys' in each machine
+        "admin-machine-1" = "__YOUR_PUBLIC_KEY__";
+      };
+    };
+
+    # Docs: https://docs.clan.lol/reference/clanServices/zerotier/
+    # The lines below will define a zerotier network and add all machines as 'peer' to it.
+    # !!! Manual steps required:
+    #   - Define a controller machine for the zerotier network.
+    #   - Deploy the controller machine first to initilize the network.
+    zerotier = {
+      # Replace with the name (string) of your machine that you will use as zerotier-controller
+      # See: https://docs.zerotier.com/controller/
+      # Deploy this machine first to create the network secrets
+      roles.controller.machines."__YOUR_CONTROLLER__" = { };
+      # Peers of the network
+      # tags.all means 'all machines' will joined
+      roles.peer.tags.all = { };
+    };
+  };
+
+  # Additional NixOS configuration can be added here.
+  # machines/jon/configuration.nix will be automatically imported.
+  # See: https://docs.clan.lol/guides/more-machines/#automatic-registration
  machines = {
-    # "jon" will be the hostname of the machine
-    jon =
-      { pkgs, ... }:
-      {
-        imports = [
-          ./modules/shared.nix
-          ./modules/disko.nix
-          ./machines/jon/configuration.nix
-        ];
-
-        nixpkgs.hostPlatform = "x86_64-linux";
-
-        # Set this for clan commands use ssh i.e. `clan machines update`
-        # If you change the hostname, you need to update this line to root@<new-hostname>
-        # This only works however if you have avahi running on your admin machine else use IP
-        clan.core.networking.targetHost = pkgs.lib.mkDefault "root@jon";
-
-        # You can get your disk id by running the following command on the installer:
-        # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-        # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-        disko.devices.disk.main = {
-          device = "/dev/disk/by-id/__CHANGE_ME__";
-        };
-
-        # IMPORTANT! Add your SSH key here
-        # e.g. > cat ~/.ssh/id_ed25519.pub
-        users.users.root.openssh.authorizedKeys.keys = throw ''
-          Don't forget to add your SSH key here!
-          users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
-        '';
-
-        # Zerotier needs one controller to accept new nodes. Once accepted
-        # the controller can be offline and routing still works.
-        clan.core.networking.zerotier.controller.enable = true;
-      };
-    # "sara" will be the hostname of the machine
-    sara =
-      { pkgs, ... }:
-      {
-        imports = [
-          ./modules/shared.nix
-          ./modules/disko.nix
-          ./machines/sara/configuration.nix
-        ];
-
-        nixpkgs.hostPlatform = "x86_64-linux";
-
-        # Set this for clan commands use ssh i.e. `clan machines update`
-        # If you change the hostname, you need to update this line to root@<new-hostname>
-        # This only works however if you have avahi running on your admin machine else use IP
-        clan.core.networking.targetHost = pkgs.lib.mkDefault "root@sara";
-
-        # You can get your disk id by running the following command on the installer:
-        # Replace <IP> with the IP of the installer printed on the screen or by running the `ip addr` command.
-        # ssh root@<IP> lsblk --output NAME,ID-LINK,FSTYPE,SIZE,MOUNTPOINT
-        disko.devices.disk.main = {
-          device = "/dev/disk/by-id/__CHANGE_ME__";
-        };
-
-        # IMPORTANT! Add your SSH key here
-        # e.g. > cat ~/.ssh/id_ed25519.pub
-        users.users.root.openssh.authorizedKeys.keys = throw ''
-          Don't forget to add your SSH key here!
-          users.users.root.openssh.authorizedKeys.keys = [ "<YOUR SSH_KEY>" ]
-        '';
-
-        /*
-          After jon is deployed, uncomment the following line
-          This will allow sara to share the VPN overlay network with jon
-          The networkId is generated by the first deployment of jon
-        */
-        # clan.core.networking.zerotier.networkId = builtins.readFile ../../vars/per-machine/jon/zerotier/zerotier-network-id/value;
-      };
+    # jon = { config, ... }: {
+    #   environment.systemPackages = [ pkgs.asciinema ];
+    # };
  };
 }
--- a/templates/clan/flake-parts/flake.nix
+++ b/templates/clan/flake-parts/flake.nix
@@ -6,7 +6,6 @@

  outputs =
    inputs@{
-      self,
      flake-parts,
      ...
    }:
@@ -22,7 +21,9 @@
      ];

      # https://docs.clan.lol/guides/getting-started/flake-parts/
-      clan = import ./clan.nix { inherit self; };
+      clan = {
+        imports = [ ./clan.nix ];
+      };

      perSystem =
        { pkgs, inputs', ... }:
--- a/templates/clan/flake-parts/machines/jon/configuration.nix
+++ b/templates/clan/flake-parts/machines/jon/configuration.nix
@@ -1,38 +0,0 @@
-{ config, ... }:
-let
-  username = config.networking.hostName;
-in
-{
-  imports = [ ./hardware-configuration.nix ];
-
-  # Locale service discovery and mDNS
-  services.avahi.enable = true;
-
-  services.xserver.enable = true;
-  services.xserver.desktopManager.gnome.enable = true;
-  services.xserver.displayManager.gdm.enable = true;
-  # Disable the default gnome apps to speed up deployment
-  services.gnome.core-utilities.enable = false;
-
-  # Enable automatic login for the user.
-  services.displayManager.autoLogin = {
-    enable = true;
-    user = username;
-  };
-
-  users.users.${username} = {
-    initialPassword = username;
-    isNormalUser = true;
-    extraGroups = [
-      "wheel"
-      "networkmanager"
-      "video"
-      "audio"
-      "input"
-      "dialout"
-      "disk"
-    ];
-    uid = 1000;
-    openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
-  };
-}
--- a/templates/clan/flake-parts/machines/sara/configuration.nix
+++ b/templates/clan/flake-parts/machines/sara/configuration.nix
@@ -1,39 +0,0 @@
-{ config, ... }:
-
-let
-  username = config.networking.hostName;
-in
-{
-  imports = [ ./hardware-configuration.nix ];
-
-  # Locale service discovery and mDNS
-  services.avahi.enable = true;
-
-  services.xserver.enable = true;
-  services.xserver.desktopManager.gnome.enable = true;
-  services.xserver.displayManager.gdm.enable = true;
-  # Disable the default gnome apps to speed up deployment
-  services.gnome.core-utilities.enable = false;
-
-  # Enable automatic login for the user.
-  services.displayManager.autoLogin = {
-    enable = true;
-    user = username;
-  };
-
-  users.users.${username} = {
-    initialPassword = username;
-    isNormalUser = true;
-    extraGroups = [
-      "wheel"
-      "networkmanager"
-      "video"
-      "audio"
-      "input"
-      "dialout"
-      "disk"
-    ];
-    uid = 1000;
-    openssh.authorizedKeys.keys = config.users.users.root.openssh.authorizedKeys.keys;
-  };
-}
--- a/templates/clan/flake-parts/modules/disko.nix
+++ b/templates/clan/flake-parts/modules/disko.nix
@@ -1,51 +0,0 @@
-{ lib, clan-core, ... }:
-
-let
-  suffix = config.clan.core.vars.generators.disk-id.files.diskId.value;
-in
-{
-  imports = [
-    clan-core.clanModules.disk-id
-  ];
-
-  boot.loader.grub.efiSupport = lib.mkDefault true;
-  boot.loader.grub.efiInstallAsRemovable = lib.mkDefault true;
-  disko.devices = {
-    disk = {
-      "main" = {
-        # suffix is to prevent disk name collisions
-        name = "main-" + suffix;
-        type = "disk";
-        # Set the following in flake.nix for each maschine:
-        # device = <uuid>;
-        content = {
-          type = "gpt";
-          partitions = {
-            "boot" = {
-              size = "1M";
-              type = "EF02"; # for grub MBR
-              priority = 1;
-            };
-            "ESP" = {
-              size = "512M";
-              type = "EF00";
-              content = {
-                type = "filesystem";
-                format = "vfat";
-                mountpoint = "/boot";
-              };
-            };
-            "root" = {
-              size = "100%";
-              content = {
-                type = "filesystem";
-                format = "ext4";
-                mountpoint = "/";
-              };
-            };
-          };
-        };
-      };
-    };
-  };
-}
--- a/templates/flake-module.nix
+++ b/templates/flake-module.nix
@@ -5,6 +5,27 @@
  };

  flake = {
+    checks.x86_64-linux.equal-templates =
+      inputs.nixpkgs.legacyPackages.x86_64-linux.runCommand "minimal-clan-flake" { }
+        ''
+          file1=${./clan/default/clan.nix}
+          file2=${./clan/flake-parts/clan.nix}
+
+          echo "Comparing $file1 and $file2"
+          if cmp -s "$file1" "$file2"; then
+            echo "clan.nix files are identical"
+          else
+            echo "clan.nix files are out of sync"
+            echo "Please make sure to keep templates clan.nix files in sync."
+            echo "files: templates/clan/default/clan.nix templates/clan/flake-parts/clan.nix"
+            echo "--------------------------------\n"
+            diff "$file1" "$file2"
+            echo "--------------------------------\n\n"
+            exit 1
+          fi
+
+          touch $out
+        '';
    checks.x86_64-linux.template-minimal =
      let
        path = self.clan.templates.clan.minimal.path;
Author	SHA1	Message	Date
a-kenji	0a502ab242	pkgs/cli: Add facts deprecation warning to `clan facts` help output	2025-07-15 14:28:36 +02:00
hsjobeki	b2e424fa2e	Merge pull request 'ui/scene: refactor simplify select animation' (#4325 ) from ui-scene-1 into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4325	2025-07-13 18:56:12 +00:00
Johannes Kirschbauer	1568bb3860	ui/scene: simplify select animation	2025-07-13 20:44:12 +02:00
Johannes Kirschbauer	b549012aa1	ui/scene: rename file	2025-07-13 20:43:35 +02:00
hsjobeki	45594e118b	Merge pull request 'clan_cli: move __init__.py into cli.py' (#4323 ) from cli into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4323	2025-07-13 16:14:21 +00:00
Johannes Kirschbauer	b36abb8fcd	clan_cli: add empty __init__.py for relative imports	2025-07-13 18:03:56 +02:00
Johannes Kirschbauer	63b4813c46	clan_cli: rename references	2025-07-13 15:53:10 +02:00
Johannes Kirschbauer	3d103fdb26	clan_cli: move __init__.py into cli.py This helps to reduce import cycles in python If ANY python module from clan_cli is imported all the imports of the __init__.py are executed leading to a lot of cycles	2025-07-13 15:52:29 +02:00
hsjobeki	ed470ed2b1	Merge pull request 'api/services: add get_service_module_schema endpoint' (#4324 ) from lazy-schemas into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4324	2025-07-13 13:07:48 +00:00
Johannes Kirschbauer	4d7aad78ae	api/services: add get_service_module_schema	2025-07-13 14:56:57 +02:00
Johannes Kirschbauer	5c0ac5d0cc	services: add modules schema to inventoryClass	2025-07-13 14:17:57 +02:00
hsjobeki	4cc149b3c3	Merge pull request 'api/modules: remove redundant localModules' (#4322 ) from api-modules into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4322	2025-07-13 12:05:11 +00:00
Johannes Kirschbauer	db592a565d	instances: create_service_instance init	2025-07-13 13:57:02 +02:00
Johannes Kirschbauer	84865f37b8	lib/modules: list modules consistent argument	2025-07-13 13:57:02 +02:00
Johannes Kirschbauer	21f8a69989	lib/modules: rename 'list_modules' to 'list_service_modules'	2025-07-13 13:57:02 +02:00
Johannes Kirschbauer	fb745beda5	lib/disks: move from api to templates	2025-07-13 13:57:02 +02:00
Johannes Kirschbauer	86db003973	lib/modules: move from api to services module	2025-07-13 13:57:02 +02:00
Johannes Kirschbauer	d9368ec01c	api/modules: remove redundant localModules	2025-07-13 11:52:19 +02:00
hsjobeki	f6bf1481f5	Merge pull request 'docs/getting-started: seperate step to add a user' (#4321 ) from docs-users into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4321	2025-07-13 09:37:17 +00:00
Johannes Kirschbauer	0ac0b422e6	docs/users: add explanation for groups	2025-07-13 11:33:22 +02:00
Johannes Kirschbauer	2ecb9a533d	docs/getting-started: seperate step to add a user	2025-07-13 11:31:14 +02:00
Michael Hoang	379d675372	Merge pull request 'users: fix eval when used to manage `root`' (#4319 ) from push-qnllumxpxumt into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4319	2025-07-13 02:35:35 +00:00
Michael Hoang	10f89d6612	users: fix eval when used to manage `root`	2025-07-13 12:30:16 +10:00
hsjobeki	cde9df1536	Merge pull request 'docs/deploy: remove unneeded --update-hardware-config nixos-facter' (#4318 ) from templates-1 into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4318	2025-07-12 15:51:13 +00:00
Johannes Kirschbauer	8c1587e400	docs/deploy: remove unneeded --update-hardware-config nixos-facter	2025-07-12 17:48:13 +02:00
hsjobeki	e88b05dd9c	Merge pull request 'Templates/cli: improve ux and docs' (#4317 ) from templates-1 into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4317	2025-07-12 15:31:55 +00:00
Johannes Kirschbauer	318cc4b1ec	Templates/cli: improve ux and docs	2025-07-12 17:21:23 +02:00
hsjobeki	6ff2e8de94	Merge pull request 'Templates: remove deprecated files' (#4316 ) from templates-1 into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4316	2025-07-12 15:11:32 +00:00
hsjobeki	346e56191a	Merge pull request 'pkgs/clan(templates): Fix template help' (#4315 ) from ke-fix-template-help into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4315	2025-07-12 15:06:31 +00:00
Johannes Kirschbauer	696e4b984f	Templates/flake-parts: remove machines Users create machines if they need them	2025-07-12 16:59:16 +02:00
Johannes Kirschbauer	de1d0c8747	Templates: remove disko.nix from all templates	2025-07-12 16:58:52 +02:00
Johannes Kirschbauer	86ea1b0a60	Templates: remove shared.nix - user-password is now part of the new 'users' module (https://docs.clan.lol/reference/clanServices/users/) - setting 'users.users.user' is not needed and also part of the 'users' module - services.avahi.enable = true; is not strictly needed can become part of an mdns guide, but shouldnt be part of the default template	2025-07-12 16:58:02 +02:00
hsjobeki	241550921f	Merge pull request 'docs/getting-started: refactor and align with new templates' (#4313 ) from getting-started into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4313	2025-07-12 14:43:29 +00:00
a-kenji	f69dd29f79	pkgs/clan(templates): Fix template help Currently the template help has the following interface: ``` usage: clan [-h] [SUBCOMMAND] The clan cli tool positional arguments: {show,backups,b,flakes,f,templates,flash,ssh,secrets,facts,vars,va,machines,m,vms,select,se,state,st} show Show meta information about the clan backups (b) Manage backups of clan machines flakes (f) Create a clan flake inside the current directory templates Subcommands to interact with templates flash Flashes your machine to an USB drive ssh Ssh to a remote machine secrets Manage secrets facts Manage facts vars (va) Manage vars machines (m) Manage machines and their configuration vms Manage virtual machines select (se) Select nixos values from the flake state (st) Query state information about machines options: -h, --help show this help message and exit Online reference for the clan cli tool: ]8;;https://docs.clan.lol/reference/cli\https://docs.clan.lol/reference/cli]8;;\ For more detailed information, visit: ]8;;https://docs.clan.lol\https://docs.clan.lol]8;;\ ```	2025-07-12 16:42:05 +02:00
hsjobeki	648f3ec084	Merge pull request 'pkgs/clan(templates): Add machine completions' (#4312 ) from ke-templates-machines-add-shell-completions into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4312	2025-07-12 14:40:57 +00:00
Johannes Kirschbauer	f362cfb983	Docs: fix code annotations	2025-07-12 16:40:02 +02:00
Johannes Kirschbauer	66ddc399d0	Docs: fix typos	2025-07-12 16:39:20 +02:00
Johannes Kirschbauer	20a6375c2a	Docs: align workflow, remove targetHost before deployment	2025-07-12 16:35:43 +02:00
Johannes Kirschbauer	2882e9e8da	Docs: rewrite deployment instructions	2025-07-12 16:35:43 +02:00
Johannes Kirschbauer	2c910f8616	docs: add guide how to create configuration.nix	2025-07-12 16:35:43 +02:00
Johannes Kirschbauer	5e80e0a833	docs: add service update instructions	2025-07-12 16:35:43 +02:00
Johannes Kirschbauer	055cf3d924	docs: add machines update instructions	2025-07-12 16:35:43 +02:00
Johannes Kirschbauer	3d8ddd1be1	docs: create clan update cli instructions	2025-07-12 16:35:41 +02:00
a-kenji	71ee2fcbb6	pkgs/clan(templates): Add machine completions Add machine completions for the `--to-machine` subcommand	2025-07-12 16:02:51 +02:00
hsjobeki	279df893cc	Merge pull request 'cli/create: add interactive name method' (#4310 ) from getting-started into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4310	2025-07-12 13:27:38 +00:00
Johannes Kirschbauer	ed2663ac7b	clan/create: rename path to name argument	2025-07-12 15:16:31 +02:00
Johannes Kirschbauer	c4f67ca44d	templates/copy: fix use shutil to copy hidden dot files	2025-07-12 15:08:40 +02:00
kenji	5f8d65bd80	Merge pull request 'pkgs/clan: Fix command typos' (#4309 ) from kenji/ke-fix-command-typos into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4309	2025-07-12 12:49:57 +00:00
Johannes Kirschbauer	98185217bd	templates: add example how to add inventory.machines	2025-07-12 14:49:27 +02:00
Johannes Kirschbauer	876e57e81e	cli/create: add interactive name method	2025-07-12 14:12:10 +02:00
hsjobeki	d601237853	Merge pull request 'modules/user: Improve user module' (#4305 ) from user into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4305	2025-07-12 11:57:44 +00:00
a-kenji	2439d508ef	pkgs/clan: Fix command typos	2025-07-12 13:54:37 +02:00
Johannes Kirschbauer	0dd5b284eb	Users: add option for regularUser	2025-07-12 13:44:16 +02:00
hsjobeki	a47d65d3ed	Merge pull request 'diskId: add migration docs and a big fat warning' (#4307 ) from disk-migration into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4307	2025-07-12 11:15:51 +00:00
hsjobeki	5484b584f1	Merge pull request 'cli/templates: init apply disk' (#4306 ) from templates-cli into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4306	2025-07-12 11:15:47 +00:00
Johannes Kirschbauer	461c628a98	diskId: add migration docs and a big fat warning	2025-07-11 20:47:53 +02:00
Johannes Kirschbauer	70454878ff	cli/templates: init apply disk	2025-07-11 18:53:54 +02:00
Johannes Kirschbauer	7b6e63d6ca	lib/disks: add parameter to disable hardware checking	2025-07-11 18:53:54 +02:00
Johannes Kirschbauer	67eb2274ab	cli/machine/hardware: improve error message	2025-07-11 18:53:54 +02:00
Johannes Kirschbauer	794872e235	get_machine: fix error message for not existing machine	2025-07-11 18:53:54 +02:00
Johannes Kirschbauer	7765e7155e	lib/copy: fix, copying the content of tempate directory, not the directory itself	2025-07-11 18:53:54 +02:00
Johannes Kirschbauer	3871cb7ab4	Templates: keep clan.nix in sync between default and flake-parts	2025-07-11 16:42:20 +02:00
Johannes Kirschbauer	a4131a0822	Modules/users: add isNormalUser true NormalUsers get: - Home directory - Can login This is expected for users created through this module. We can make it configurable if the use arises	2025-07-11 16:32:16 +02:00
hsjobeki	02111109f8	Merge pull request 'Vars/helper: remove unneeded wrapper arount collectFiles' (#4304 ) from vars-angnostic into main Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4304	2025-07-11 14:31:20 +00:00
Johannes Kirschbauer	3e489d5cff	Templates/flake-parts: consistent default clan	2025-07-11 16:19:01 +02:00
Johannes Kirschbauer	2f027cad3c	Vars/helper: remove unneeded wrapper arount collectFiles	2025-07-11 16:14:02 +02:00