docs: improve add-alias help text and update CLI reference documentation

bobmatnyc · bobmatnyc · commit adc6fd9e538d · 2026-04-09T08:31:10.000-04:00
diff --git a/README.md b/README.md
@@ -75,6 +75,7 @@ gitflow-analytics -c config.yaml --weeks 8
 - **📊 DORA Metrics**: Deployment frequency, lead time, change failure rate, and MTTR
 - **💰 Cost Tracking**: Monitor LLM API usage with detailed token and cost reporting
 - **📈 Weekly Trends**: Track classification pattern changes over time with proper Monday-aligned weeks
+- **🏷️ Non-Interactive Alias Management**: `gfa add-alias` command for scripting alias mappings — single or batch via YAML/JSON file, with `--dry-run` support
 
 ## 🔥 Core Capabilities
 
diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md
@@ -190,6 +190,100 @@ gitflow-analytics alias-rename -c config.yaml \
 - Always test with `--dry-run` first to preview changes
 - See [Managing Aliases Guide](../guides/managing-aliases.md#renaming-developers) for detailed usage
 
+### add-alias
+Add alias mappings to a configuration file non-interactively. Suitable for scripting and CI pipelines where interactive prompts are not available.
+
+```bash
+gfa add-alias -c config.yaml \
+  --canonical "developer@example.com" \
+  --alias "dev@personal.com" \
+  --alias "Dev Name" \
+  [OPTIONS]
+```
+
+**Required Options**:
+- `-c, --config PATH` - Path to YAML configuration file
+
+**Mapping Options** (mutually exclusive — use one or the other):
+- `--canonical EMAIL` - Primary/canonical email for this developer identity; combine with one or more `--alias` flags
+- `--from-file PATH` - YAML or JSON file containing batch alias mappings (cannot be combined with `--canonical`)
+- `--alias EMAIL_OR_NAME` - Email address or display name to map to `--canonical`; repeatable
+
+**Behaviour Flags**:
+- `--dry-run` - Show what would be changed without writing to the config file
+- `--apply` - Trigger identity re-resolution after updating the config
+
+**Examples**:
+```bash
+# Map a personal email and display name to a canonical work email
+gfa add-alias -c config.yaml \
+  --canonical "alice@company.com" \
+  --alias "alice@gmail.com" \
+  --alias "Alice Smith"
+
+# Preview changes before writing
+gfa add-alias -c config.yaml \
+  --canonical "alice@company.com" \
+  --alias "alice@gmail.com" \
+  --dry-run
+
+# Load batch mappings from a YAML file and re-resolve identities
+gfa add-alias -c config.yaml \
+  --from-file aliases.yaml \
+  --apply
+
+# Load batch mappings from a JSON file
+gfa add-alias -c config.yaml \
+  --from-file aliases.json
+```
+
+**Supported `--from-file` Formats**:
+
+1. **GFA native YAML** — a config file with a `developer_aliases:` key:
+   ```yaml
+   developer_aliases:
+     - canonical: "alice@company.com"
+       aliases: ["alice@gmail.com", "Alice Smith"]
+   ```
+
+2. **Flat YAML list** — a list of `{canonical, aliases}` objects:
+   ```yaml
+   - canonical: "alice@company.com"
+     aliases:
+       - alice@gmail.com
+       - Alice Smith
+   - canonical: "bob@company.com"
+     aliases:
+       - bob@personal.com
+   ```
+
+3. **JSON array** — equivalent structure in JSON:
+   ```json
+   [
+     {"canonical": "alice@company.com", "aliases": ["alice@gmail.com", "Alice Smith"]},
+     {"canonical": "bob@company.com",   "aliases": ["bob@personal.com"]}
+   ]
+   ```
+
+**What It Does**:
+1. Reads the existing `analysis.identity.manual_mappings` (or `developer_aliases`) section in the config
+2. Merges new aliases into the matching canonical entry, or creates a new entry if the canonical is not yet present
+3. Skips duplicates — existing aliases are never written twice (idempotent)
+4. Writes the updated config back to disk (unless `--dry-run` is specified)
+5. Optionally triggers identity re-resolution via `--apply`
+
+**Use Cases**:
+- Onboarding automation: script alias setup as part of repo initialisation
+- CI pipelines: keep alias mappings in a separate file and apply them on deploy
+- Bulk imports: migrate alias lists from another tool's export format
+- Safe updates: use `--dry-run` to audit changes before committing them
+
+**Notes**:
+- `--from-file` and `--canonical` are mutually exclusive; combining them is an error
+- The operation is idempotent: running the same command twice produces the same config
+- Always verify with `--dry-run` before running in unattended automation
+- See [Managing Aliases Guide](../guides/managing-aliases.md) for detailed identity management guidance
+
 ## 📊 Output Formats
 
 ### CSV Format (`--format csv`)
diff --git a/src/gitflow_analytics/cli_identity_alias_ops.py b/src/gitflow_analytics/cli_identity_alias_ops.py
@@ -635,39 +635,39 @@ def _load_alias_file(file_path: str) -> list[dict]:
     "-c",
     required=True,
     type=click.Path(exists=True),
-    help="Config YAML path",
+    help="Path to YAML configuration file",
 )
 @click.option(
     "--canonical",
     required=False,
     default=None,
-    help="Canonical email address",
+    help="Primary/canonical email for this developer identity",
 )
 @click.option(
     "--alias",
     "aliases",
     multiple=True,
-    help="Alias email or name (repeatable)",
+    help="Email or name to map to canonical (repeatable, e.g. --alias old@co.com --alias 'Jane Smith')",
 )
 @click.option(
     "--from-file",
     "from_file",
     required=False,
     default=None,
     type=click.Path(exists=True),
-    help="YAML/JSON file with batch alias mappings",
+    help="YAML or JSON file with batch alias mappings (see format below)",
 )
 @click.option(
     "--apply",
     is_flag=True,
     default=False,
-    help="After writing config, rerun identity resolution to propagate to historical commits",
+    help="Trigger identity re-resolution after updating config (propagates to cached data)",
 )
 @click.option(
     "--dry-run",
     is_flag=True,
     default=False,
-    help="Print what would be done without making changes",
+    help="Show what would be changed without writing to config",
 )
 def add_alias_command(
     config: str,
@@ -677,18 +677,66 @@ def add_alias_command(
     apply: bool,
     dry_run: bool,
 ) -> None:
-    """Add known alias mappings to config non-interactively.
+    """Add alias mappings to config non-interactively.
+
+    Maps one or more alias emails/names to a canonical developer identity
+    in analysis.identity.manual_mappings. Supports single mappings via
+    --canonical/--alias flags, or bulk import via --from-file.
+
+    \b
+    USAGE MODES:
 
-    Use --canonical + --alias for a single mapping, or --from-file for batch.
+      Single mapping (--canonical + --alias):
+        Adds or updates one developer's alias list. Multiple --alias
+        flags may be provided to add several aliases at once.
+
+      Batch import (--from-file):
+        Reads a YAML or JSON file containing multiple mappings.
+        Mutually exclusive with --canonical.
 
     \b
-    Examples:
+    FILE FORMATS (--from-file):
+
+      GFA native YAML (developer_aliases list):
+        developer_aliases:
+          - canonical: john@work.com
+            aliases:
+              - john@gmail.com
+              - "John Doe"
+          - canonical: jane@corp.com
+            aliases:
+              - jane@personal.com
+
+      Flat YAML list:
+        - canonical: john@work.com
+          aliases: [john@gmail.com]
 
-      # Single alias
-      gfa add-alias -c config.yaml --canonical john@work.com --alias john@gmail.com --alias "John Doe"
+      JSON array:
+        [{"canonical": "john@work.com", "aliases": ["john@gmail.com"]}]
 
-      # Batch from YAML file
+    \b
+    EXAMPLES:
+
+      # Add single alias
+      gfa add-alias -c config.yaml --canonical john@work.com --alias john@gmail.com
+
+      # Add multiple aliases at once
+      gfa add-alias -c config.yaml --canonical john@work.com \\
+          --alias john@gmail.com --alias "John Doe"
+
+      # Preview without writing
+      gfa add-alias -c config.yaml --canonical john@work.com \\
+          --alias john@gmail.com --dry-run
+
+      # Batch import from file
       gfa add-alias -c config.yaml --from-file aliases.yaml
+
+    \b
+    NOTE:
+      Existing canonical entries are merged (not replaced). Duplicate
+      aliases are silently skipped. Use --dry-run to preview changes.
+      After updating config, run 'gfa identities --apply' to propagate
+      changes to cached data (or use --apply when that flag is wired).
     """
     # Validate args
     if not from_file and not canonical:
