Merge pull request 'quickstart: improve and add machines section' (#336) from DavHau-dave into main

docs/quickstart.md

@@ -1,22 +1,24 @@
 # Initializing a New Clan Project
 
-## Clone the Clan Template
+## Create a new Clan flake
 
 1. To start a new project, execute the following command to add the clan cli to your shell:
 
-```bash
+```shellSession
 $ nix shell git+https://git.clan.lol/clan/clan-core
 ```
 
-2. Than use the following command to clone the clan core template into the current directory:
+2. Then use the following commands to initialize a new clan-flake:
 
 ```
-$ clan create .
+$ mkdir ./my-flake
+$ cd ./my-flake
+$ clan create
 ```
 
 This action will generate two primary files: `flake.nix` and `.clan-flake`.
 
-```bash
+```shellSession
 $ ls -la
 drwx------ joerg users   5 B  a minute ago   ./
 drwxrwxrwt root  root  139 B  12 seconds ago ../
@@ -30,9 +32,29 @@ drwxrwxrwt root  root  139 B  12 seconds ago ../
 The `.clan-flake` marker file serves an optional purpose: it helps the `clan-cli` utility locate the project's root directory.
 If `.clan-flake` is missing, `clan-cli` will instead search for other indicators like `.git`, `.hg`, `.svn`, or `flake.nix` to identify the project root.
 
-## Modifying the configuration
+## Add your first machine
 
-After cloning the template the next step is to modify the `flake.nix` and follow the instructions in it to add more machines.
+```shellSession
+$ clan machines create my-machine
+$ clan machines list
+my-machine
+```
+
+## configure your machine
+
+In this example we crate a user named `my-user` that is allowed to login to the machine
+
+```shellSession
+$ clan config --machine my-machine users.users.my-user.hashedPassword $(mkpasswd)
+```
+
+## Test your machine config inside a VM
+
+```shellSession
+$ nix build .#nixosConfigurations.my-machine.config.system.build.vm
+...
+$ ./result/bin/run-nixos-vm
+```
 
 ---
 
@@ -48,7 +70,7 @@ Absolutely, let's break down the migration step by step, explaining each action
    cp -r /etc/nixos ~/nixos-backup
    ```
 
-2. **Update Flake Inputs**: The patch adds a new input named `clan-core` to your `flake.nix`. This input points to a Git repository for Clan Core. Here's the addition:
+2. **Update Flake Inputs**: Add a new input for the `clan-core` dependency:
 
    ```nix
    inputs.clan-core = {

pkgs/clan-cli/clan_cli/__init__.py

@@ -16,9 +16,16 @@ except ImportError:
 
 def create_parser(prog: Optional[str] = None) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog=prog, description="cLAN tool")
+
+    parser.add_argument(
+        "--debug",
+        help="Enable debug logging",
+        action="store_true",
+    )
+
     subparsers = parser.add_subparsers()
 
-    parser_create = subparsers.add_parser("create", help="create a clan flake")
+    parser_create = subparsers.add_parser("create", help="create a clan flake inside the current directory")
     create.register_parser(parser_create)
 
     parser_config = subparsers.add_parser("config", help="set nixos configuration")
@@ -58,6 +65,8 @@ def main() -> None:
     try:
         args.func(args)
     except ClanError as e:
+        if args.debug:
+            raise
         print(f"{sys.argv[0]}: {e}")
         sys.exit(1)