feat: install on specific machines by machine id

docs/command-line-interface.md

@@ -11,15 +11,17 @@ repository.
 
 You can call `sofmani` with the following flags to alter the behavior for the current run:
 
-| Flag                | Description                                             |
-| ------------------- | ------------------------------------------------------- |
-| `-d`, `--debug`     | Enable debug mode.                                      |
-| `-D`, `--no-debug`  | Disable debug mode (default).                           |
-| `-u`, `--update`    | Enable update checking.                                 |
-| `-U`, `--no-update` | Disable update checking (default).                      |
-| `-f`, `--filter`    | Filter by installer name (can be used multiple times)\* |
-| `-h`, `--help`      | Display help information and exit.                      |
-| `-v`, `--version`   | Display version information and exit.                   |
+| Flag                  | Description                                             |
+| --------------------- | ------------------------------------------------------- |
+| `-d`, `--debug`       | Enable debug mode.                                      |
+| `-D`, `--no-debug`    | Disable debug mode (default).                           |
+| `-u`, `--update`      | Enable update checking.                                 |
+| `-U`, `--no-update`   | Disable update checking (default).                      |
+| `-f`, `--filter`      | Filter by installer name (can be used multiple times)\* |
+| `-l`, `--log-file`    | Set log file path, or show current path if no value.    |
+| `-m`, `--machine-id`  | Show machine ID and exit.                               |
+| `-h`, `--help`        | Display help information and exit.                      |
+| `-v`, `--version`     | Display version information and exit.                   |
 
 Each of these flags overrides the loaded config file, so while your default config can choose not to
 check for updates by default, you or another user can add the `--update` flag to override this
@@ -50,6 +52,21 @@ included.
 - To only installers that contain "sofmani", but exclude ones tagged "config", use
   `-f sofmani -f "!tag:config"`.
 
+### Machine ID
+
+The machine ID is a unique, deterministic identifier for the current machine. It is generated from
+stable system identifiers (hardware UUID on macOS, `/etc/machine-id` on Linux, registry GUID on
+Windows) and remains constant even if hostname or other system settings change.
+
+To view the current machine's ID:
+
+```sh
+sofmani --machine-id
+```
+
+This ID can be used with the `machines` configuration option to run specific installers only on
+certain machines. See [Installer Configuration](./installer-configuration.md#fields) for details.
+
 ## Examples
 
 Search for the config in one of the default directories, and enable update checking:

docs/configuration-reference.md

@@ -38,6 +38,19 @@ Here is a breakdown of all configuration options:
   - OS environment variables are passed and may be overridden for this config and all of its
     installers here.
 
+- **`machine_aliases`** (Object)
+  - A mapping of friendly names to machine IDs.
+  - Use `sofmani --machine-id` to get the machine ID for each of your machines.
+  - These aliases can then be used in installer `machines.only` and `machines.except` fields
+    instead of the raw machine IDs.
+  - Example:
+    ```yaml
+    machine_aliases:
+      work-laptop: 5fa2a8e8193868df
+      home-desktop: a1b2c3d4e5f67890
+      home-server: fedcba0987654321
+    ```
+
 ## Example Config
 
 ```yaml

docs/installer-configuration.md

@@ -47,6 +47,22 @@ These fields are shared by all installer types. Some fields may vary in behavior
       - **Type**: Array of Strings
       - **Description**: Platforms where the step should **not** execute; replaces `platforms.only`.
 
+- **`machines`**
+
+  - **Type**: Object (optional)
+  - **Description**: Machine-specific execution controls. Use this to run installers only on
+    specific machines. Get the machine ID by running `sofmani --machine-id`. You can use either
+    raw machine IDs or aliases defined in the top-level `machine_aliases` configuration.
+    See `machines` subfields below.
+  - **Subfields**:
+    - **`machines.only`**
+      - **Type**: Array of Strings
+      - **Description**: Machine IDs or aliases where the step should execute. Supercedes
+        `machines.except`.
+    - **`machines.except`**
+      - **Type**: Array of Strings
+      - **Description**: Machine IDs or aliases where the step should **not** execute.
+
 - **`steps`**
 
   - **Type**: Array of Installers
@@ -356,6 +372,49 @@ install:
           command: 'curl https://pyenv.run | bash'
 ```
 
+### Machine-specific installers
+
+```yaml
+# Define friendly names for your machines (get IDs with `sofmani --machine-id`)
+machine_aliases:
+  work-laptop: a1b2c3d4e5f67890
+  home-desktop: 5fa2a8e8193868df
+  home-server: fedcba0987654321
+
+install:
+  # Only install on specific machines using aliases
+  - name: work-tools
+    type: group
+    machines:
+      only: ['work-laptop']
+    steps:
+      - name: slack
+        type: brew
+        opts:
+          cask: true
+      - name: zoom
+        type: brew
+        opts:
+          cask: true
+
+  # Install everywhere except the home server
+  - name: desktop-apps
+    type: group
+    machines:
+      except: ['home-server']
+    steps:
+      - name: firefox
+        type: brew
+        opts:
+          cask: true
+
+  # You can also use raw machine IDs directly
+  - name: special-tool
+    type: brew
+    machines:
+      only: ['a1b2c3d4e5f67890'] # Raw machine ID also works
+```
+
 ### manifest
 
 ```yaml